As per the new guidelines, we are moving to AadhaarAPI gateway from rest APIs. The gateway will also provide the ease of integration and simplicity by eliminating the need to handle the complex encryption at the client end. Also, it is completely customizable in terms of look and feel and will get updates as per the new guidelines without any or minimal need of code change at the client end.

Steps to perform an EKYC/AUTH transaction using AadhaarAPI gateway:

  1. Initiate the transaction at your backend using a simple Rest API [POST] call. This will require the type of service (ekyc/auth) and aadhaar number as URL param input and return a gateway transaction id.This gateway transaction id then needs to be communicated back to the frontend where SDK is to be called.
  1. Assuming the SDK files (JS & CSS) at frontend and a small HTML snippet, the client has to pass above-generated transaction id to SDK function to create a new gateway object and then open the gateway using another function call.
  2. This will open the gateway as shown in above image and the rest of the process till response will be handled by the gateway itself.
  3. Once the transaction is successful or failed, appropriate handler function will be called with response JSON, that can be used by the client to process the flow further.
  4. A client will also have a REST API available to pull the response hash from backend to confirm the integrity of the result and in the case of any information loss/tampered at frontend. (Coming soon)


Initiating a Gateway Transaction

To initiate a gateway transaction a REST API call has to be made to the backend. This call will generate a Gateway Transaction Idwhich needs to be passed to the frontend web-sdk to launch the gateway.


[Requires API key in header as – QT_API_KEY : <<your api key value>>]

URL Params: [replace in above URL]

:type – auth or ekyc

:aadhaar_number – aadhaar number of resident

Response Params:

  "id": "fbe96ede-8c81-460e-a799-0e71aa7f2781",
  "aadhaar_number": "655972452780",
  "createdAt": "2017-05-22T08:34:25.841Z",
  "env": 1

The above-generated gateway transaction Id has to be made available to frontend to open the gateway.

Configuring and launching the gateway

  1. Add following CSS file for gateway placeholder before the body tag.
<link rel="stylesheet" href=“./aadhaar-api-web-sdk.css”>
  1. Add following HTML at the end of your page in which you want to open the gateway as a popup.
<div id="quaggaModal" class="qmodel">
    <div id="quaggaModelContent" class="qmodel-content"></div>
  1. Add following javascript after the above HTML tag
<script type="application/javascript" src=“aadhaar-api-web-sdk.js"></script>

Note: Make sure the files are included in a proper order.

  1. After above javascript, you need to call the following functions to open the gateway.

4.1. Setup the gateway UI to match your application.

var gatewayOptions = {
        company_display_name: '<<Add your company name here>>', //(required)
        consent_purpose: '<<Add the purpose of transaction here>>', //(required)
        front_text_color: 'FFFFFF', //(optional)Add the hex for colour of text of company name
        background_color: '2C3E50', //(optional)Add the hex for colour to be set for gateway.
        mobile_email_required: 'Y', //(optional) N if mobile email is not required. 
        logo_url: 'https://your-square-product-logo-image-url-here.png', //(required)
        otp_allowed: 'n', // (optional) default value is ‘y’
        fingerprint_allowed: 'y', //(optional) default value ‘y’
        default_device: 'MFS100', //(optional) If set device selection will not appear
        device_selection_allowed: 'n' //(optional)New config added  to control dropdown access

Default device values allowed:

Secugen Hamster Pro20 – ‘SHP20’

Mantra MFS100 – ‘MFS100’

Morpho MSO1300 – ‘MSO1300′

4.2. Create a new gateway transaction from gateway transaction id.

var myAadhaarGateway 
= new AadhaarAPIGateway('fbe96ede-8c81-460e-a799-0e71aa7f2781', gatewayOptions);

4.3. Open the created gateway.

  • This can be bind to a button click for opening the gateway when needed. For ex:
//Bind your button to launch gateway to openGateway Function

document.getElementById("gatewayBtn").onclick = openGateway;

function openGateway() { openAadhaarGateway(myAadhaarGateway) }

Once the gateway is open, rest of the flow till response handover is handled by the gateway itself.

4.4. Handling the different gateway responses.

function handleAadhaarConsentDenied() {
        console.log('Handling consent denial at client end');
        //Handle the case when user denies consent

    function handleAadhaarEKYCSuccess(responseJSON) {
        console.log('Handling EKYC success at client end');
        //Handle the case when EKYC is successful

    function handleAadhaarEKYCFailure(errorJSON) {
        console.log('Handling EKYC failure at client end');
        //Handle the case when EKYC fails

    function handleAadhaarAUTHSuccess(responseJSON) {
        console.log('Handling AUTH success at client end');
        //Handle the case when AUTH is successful

    function handleAadhaarAUTHFailure(errorJSON) {
        console.log('Handling AUTH failure at client end');
        //Handle the case when user Authentication fails

    function handleAadhaarOTPFailure(errorJSON){
        console.log('Handling OTP failure cases at client end');
        //Handle OTP failure
          Check for errorJSON.resultCode
            119 : No email or mobile associated with aadhaar (when Fingerprint is disabled)
            998 : Invalid Aadhaar Number.
            410 : OTP requested more than 3 times for same transaction (when Fingerprint is disabled)

    //Do not remove this function, even if not used.
    function handleGatewayError(errorJSON) {
        //Handle cases where gateway fails during launch or in between
        //statusCode: 412 - Gateway timed out before launch or during transaction. 
        console.log('Handling Gateway failure at client end');

    function handleGatewayTermination() {
        //Do not remove this function, even if not used.
        console.log('Handling Gateway Termination at client end');

Note: Do not run sample files provided directly, instead run them on some local server or hosted machine. The gateway looks for the domain name in the URL to communicate back the response securely with the page launching the gateway. This requires a proper URL like http://localhost:8080/test or URLs like file://c:/test/sample.html will not work.

Biometric devices Setup:

As of today following devices have been integrated:

  1. Secugen Hamster Pro 20
  2. Mantra MFS 100
  3. Morpho MSO1300

1. Secugen Hamster Pro 20

a. Download and Install following client service for biometric capture to work with the web SDK.

    64 bit windows:

    32-bit windows:

    New SDK: folder Https)

b. Restart your system to start using the biometric capture with web SDK.

2. Mantra MFS100

a. Download the installation manual from the links provided below.(Follow instructions during installation)

    Windows download mantra setup.exe

    Installation Manual:

3. Morpho MFS100

a. Download and Install following client service for biometric capture to work with the web SDK. (Follow instructions during installation)

    Windows download morpho setup.exe