1. Getting Started

1.1.    Integration Guide:

Need to integrate Aadhaar Services on your mobile App? Integrate Android SDK in your Application and start using Aadhaar Services (AUTH/ E-KYC) & also save your developers from hassles of compliance, biometric integration and more.
To integrate AadhaarAPI SDK, Follow the steps Shown below:

1.2.     Guidelines:

  • Please drop an email to contact@aadhaarapi.com for registration.Get your SDK Package with pre-prod API key after registration.
  • To register your public devices for availing RD services, follow the guidelines given in Device Registration Manual (provided in your SDK Package).
  • Or get in touch with your biometric device manufacturer for knowing the registration process and in-case you face any issue while registration.
  • SDKs are compatible with android version 5.0 and above.(It also supports android version 4.4 and above for SDK with OTP based aadhaar services).
  • For Biometric SDKs, please check if the android device are usb host compatible with the particular biometric device.
  • Also in-case you face any issue while SDK integration process, kindly raise a ticket on the following link => https://aadhaarapi.freshdesk.com/support/home
  • Production credentials will be issued, After the integration is done & checklist provided by AadhaarAPI team while registration has been followed & verified back by the AadhaarAPI team.

1.3.     Mechanics under the Hood

To open the SDK an intent calls needs to be done by passing transaction id (generated from backend through a post API call) and request type (transaction type + mode); which in deed will open the consent screen of SDK.

After SDK is opened, all the actions/events are handled by the SDK, and will send the response accordingly to the your application through onActivityResult() method.

2. SDK Integration Process

2.1.     Backend Integration

To use SDK, you need to generate gateway transaction id from the backend and pass it in the main activity.

Generating a Gateway Transaction Id

To initiate a gateway transaction a REST API (POST) call has to be made from backend. Use the base URL provided by our team, also pass service type and Aadhaar number of your user or customer, along with the below mentioned request body Params. This call will return Gateway Transaction Id which shall be parsed and passed to your required activity in your android application.

Follow the procedure shown below:

API:

POST {{base_url}}/gateway/init/:type/:aadhaar_number

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

Example URL: https://preprod.quagga.in/gateway/init/ekyc/123456789012

URL Params:

:type – “auth” for Authentication and “ekyc” for EKYC

:aadhaar_number – aadhaar number of resident

Request Body Params:

{
"purpose”: "Purpose of the transaction",
"ver”: "2.1" //2.1 for EKYC and 2.0 for Auth
"storeCode": "Unique store code or user id maintained at client end"
}

Response Params:

{
"id": "fbe96ede-8c81-460e-a799-0e71aa7f2781",
"aadhaar_number": "655972452780",
"createdAt": "2017-05-22T08:34:25.841Z",
"env": 1,
"service_type": 2,
"version": "2.1",
"purpose": "—purpose of the transaction --"
}

The above generated gateway transaction Id has to be passed in the activity to open the sdk.

2.2.     Mobile Integration

2.2.1.     Android Studio Setup

To add SDK file as a library in your Project, perform the following steps shown below:

A. Right click on your project and choose “Open Module Settings”.

To add SDK file as a library in your Project, perform the following steps shown below:

A. Right click on your project and choose “Open Module Settings”.

b1

B. Click the “+” button in the top left to add a new module.

b2

C. Choose “Import .JAR or .AAR Package” and click the “Next” button.

b3

D. Find the AAR file using the ellipsis button (“…”) beside the “File name” field.

b4

E. Keep the app’s module selected and click on the Dependencies pane to add the new module as a dependency.

b5

F. Use the “+” button of the dependencies screen and choose “Module dependency”.

b6

G. Choose the module and click “OK”.

b7

2.2.2. Adding Dependencies

A. Add the below dependencies to build.gradle of your “app” module folder (not to your project root build.gradle):
compile ‘com.android.volley:volley:1.0.0’

Note: If you are using only otp sdk then you can remove the last dependency (i.e. compile ‘org.lucee:bcprov-jdk15on:1.52.0’) from the build .gradle file, as it is only required in biometric scan purpose.

B. Add below strings in ‘strings.xml’ file (res/values /strings.xml):

<string name="api_base_url">https://preprod.quagga.in/gateway/</string>
>
<string name="sdk_envd">PP</string>

Params:

For PreProduction:

For Production:

Note: If you are using only otp sdk then you can remove the uidai certificate name from string and also you can remove the certificate from “assets” folder, as uidai certificate is only required in biometric scan purpose.

C. For Biometric Scan, add the Uidai certificate file inside a package: “assets”.

D. Then, perform a gradle sync and rebuild the project.

2.2.3.Using ‘.aar’ In Your App

A. Use of Transaction Id in your application:
  1. Collect customer’s aadhaar number from Android application.
  2. Send aadhaar number back to your backend server.
  3. Call INIT api with aadhaar number, type of service(Auth/E-kyc), along with Version, Store Code, Sub-AUA Id, Purpose of transaction parameters as json body with QT_API_KEY in header over https to generate gateway transaction id.
  4. Pass the generated gateway transaction id back to your Android app.
  5. Pass the gateway transaction id along with other parameter into the SDK.

Handle the response after transaction is complete.

Note: Step 3 has to be performed at the backend and the QT_API_KEY should not be used inside mobile app. This is a security vulnerability and the same has to be fixed in case SDKs older than version 3 are still being used.

B. Then import following files in your activity (depending upon the requirement):

import in.quagga.sdk.ConsentActivity;
import static in.quagga.sdk.utils.ConstantsUtil.GATEWAY_TRANSACTION_ID;
import static in.quagga.sdk.Utils.ConstantsUtil.KEY_ACTIVITY_RESULT;
import static in.quagga.sdk.Utils.ConstantsUtil.KEY_REQUEST_TYPE;
import static in.quagga.sdk.Utils.ConstantsUtil.REQUEST_FOR_BIOMETRIC;
import static in.quagga.sdk.Utils.ConstantsUtil.REQUEST_FOR_OTP;
import static in.quagga.sdk.Utils.ConstantsUtil.RESULT_ERROR;
import static in.quagga.sdk.Utils.EnumRequestType.FINGER_AUTH;
import static in.quagga.sdk.Utils.EnumRequestType.FINGER_EKYC;
import static in.quagga.sdk.Utils.EnumRequestType.OTP_AUTH;
import static in.quagga.sdk.Utils.EnumRequestType.OTP_EKYC;

Note:

  • For OTP you may use the following Import statements:
  • You may use Import depending upon the request type i.e. (AUTH/EKYC).
import static in.quaggga.sdk.utils.ConstantsUtil.REQUEST_FOR_OTP;
import static in.quagga.sdk.utils.EnumRequestType.OTP_EKYC;
import static in.quagga.sdk.utils.EnumRequestType.OTP_AUTH;
  • For Biometric Scan you may use the following Import statements:
  • You may use Import depending upon the request type i.e. (AUTH/EKYC).
import static in.qugga.sdk.utils.ConstantsUtil.REQUEST_FOR_BIOMETRIC;
import static in.quagga.sdk.utils.EnumRequestType.FINGER_EKYC;
import static in.quagga.sdk.utils.EnumRequestType.FINGER_AUTH;

C.  Open the SDK from your Activity using the Intent function as described below:

gatewayIntent = new Intent(YourActivity.this, ConsentActivity.class);
 gatewayIntent.putExtra(GATEWAY_TRANSACTION_ID, id);
 gatewayIntent.putExtra(KEY_REQUEST_TYPE, requestType);
 gatewayIntent.putExtra(KEY_DEVICE_TYPE, deviceType);     // Not required in case of OTP
 startActivityForResult(gatewayIntent, REQUEST_MODE);

Params:

For OTP:

  • id: gateway transaction id generated from backend
  • requestType :
    For auth based transactions:
      FINGER_AUTH.getServiceName ()
    For ekyc based transactions: FINGER_EKYC.getServiceName()
  • deviceType : NO_DEVICE_REQ.getDeviceName()
  • REQUEST_MODE: REQUEST_FOR_OTP 

For BIOMETRIC:

  • id: gateway transaction id generated from backend
  • requestType :
    For auth based transactions:  FINGER_AUTH.getServiceName ()
    For ekyc based transactions: FINGER_EKYC.getServiceName()
  • deviceType :
    For Morpho MSO Biometric Device: MORPHO_MSO.getDeviceName()
    For Secugen Biometric Device:  SECUGEN_HAMSTER_PRO.getDeviceName()
    For Mantra MFS Biometric Device:  MANTRA_MFS.getDeviceName()
  • REQUEST_MODE: REQUEST_FOR_BIOMETRIC

F. For OTP, Result data can be obtained from ‘onActivityResult ()’ method as shown:

// handle result from SDK
    @Override
    protected void onActivityResult(int requestCode, int resultCode, Intent data) {
        /*
            Handle result for OTP
            - Remove if OTP is not being used
         */
        if (requestCode == REQUEST_FOR_OTP && null != data) {
            String requestType = data.getStringExtra(KEY_REQUEST_TYPE);

            /*
                Handle result for EKYC
                - Remove if only Auth is used in your App
             */
            if (requestType.equalsIgnoreCase(OTP_EKYC.getServiceName())) {
            
                if (resultCode == RESULT_OK) {
                    String successString = data.getStringExtra(KEY_ACTIVITY_RESULT);
                    //handle success for otp_ekyc
                    response.setText(successString);
                }
                if (resultCode == RESULT_ERROR) {
                    String errorString = data.getStringExtra(KEY_ACTIVITY_RESULT);
                    //handle error for otp_ekyc
                    response.setText(errorString);
                }
            }

            /*
                Handle result for AUTH
                - Remove if only EKYC is used in your app
             */
            if ((requestType.equalsIgnoreCase(OTP_AUTH.getServiceName()))) {

                if (resultCode == RESULT_OK) {
                    String successString = data.getStringExtra(KEY_ACTIVITY_RESULT);
                    //handle success for otp_auth
                    response.setText(successString);
                }
                if (resultCode == RESULT_ERROR) {
                    String errorString = data.getStringExtra(KEY_ACTIVITY_RESULT);
                    //handle error for otp_auth
                    response.setText(errorString);
                }
            }
        }

G. For Biometric, Result data can be obtained from ‘onActivityResult()’ method as shown:

// handle result from SDK
    @Override
    protected void onActivityResult(int requestCode, int resultCode, Intent data) {
        /*
            Handle result for BIOMETRIC
            - Remove if BIOMETRIC is not being used
         */
        if (requestCode == REQUEST_FOR_BIOMETRIC && null != data) {
            String requestType = data.getStringExtra(KEY_REQUEST_TYPE);

            /*
                Handle result for EKYC
                - Remove if only Auth is used in your App
             */
            if (requestType.equalsIgnoreCase(FINGER_EKYC.getServiceName())) {
            
                if (resultCode == RESULT_OK) {
                    String successString = data.getStringExtra(KEY_ACTIVITY_RESULT);
                    //handle success for otp_ekyc
                    response.setText(successString);
                }
                if (resultCode == RESULT_ERROR) {
                    String errorString = data.getStringExtra(KEY_ACTIVITY_RESULT);
                    //handle error for otp_ekyc
                    response.setText(errorString);
                }
            }

            /*
                Handle result for AUTH
                - Remove if only EKYC is used in your app
             */
            if ((requestType.equalsIgnoreCase(FINGER_AUTH.getServiceName()))) {

                if (resultCode == RESULT_OK) {
                    String successString = data.getStringExtra(KEY_ACTIVITY_RESULT);
                    //handle success for otp_auth
                    response.setText(successString);
                }
                if (resultCode == RESULT_ERROR) {
                    String errorString = data.getStringExtra(KEY_ACTIVITY_RESULT);
                    //handle error for otp_auth
                    response.setText(errorString);
                }
            }
        }
  • For OTP, Set the ‘requestCode’ e. the type of operation to be performed as ‘REQUEST_FOR_OTP’, whereas for Biometric, Set the ‘requestCode’ i.e. the type of operation to be performed as ‘REQUEST_FOR_BIOMETRIC’.

For example:

String requestType = data.getStringExtra(KEY_REQUEST_TYPE);
  if (requestType.equalsIgnoreCase(OTP_EKYC.getServiceName()))
  • Then handle the result depending upon your ‘requestType’ e. the type of Transaction required in your app i.e. E-KYC and/or Auth

( For OTP: ‘OTP_EKYC’‘OTP_AUTH’

For Biometric: ‘FINGER_EKYC’‘FINGER_AUTH’ )

For example:

if (requestType.equalsIgnoreCase(OTP_EKYC.getServiceName())) {
  • ‘resultCode’ will handle response or result obtained i.e. response for successful or failed transaction.( ‘RESULT_OK’ will handle success response; ‘RESULT_FAILURE’ will handle error response).

For example:

if (resultCode == RESULT_OK) {
        String successString = data.getStringExtra(KEY_ACTIVITY_RESULT);
        response.setText(successString);
     }
 
  if (resultCode == RESULT_ERROR) {
        String errorString = data.getStringExtra(KEY_ACTIVITY_RESULT);
        response.setText(errorString);
    }

3. Android SDK Experience

 3.1. Running the ‘.aar’ File for OTP In Your App

A.  After successful build and run; by providing transaction Id in the application, User will land into Consent for Authentication Screen.

consent_0

B. After you press “ACCEPT AND CONTINUE” button;if the Aadhaar number is correct& mobile number is registered;then One Time Password i.e. OTP will be sent on Aadhaar registered mobile number.

C. Enter the OTP sent on Aadhaar registered mobile number.

otp

D. If the OTP entered is correct then depending on the request type theEkyc/Auth information will be passed in String format:

3.2. Running the ‘.aar’ File for FingerPrint In Your App

A. After successful build and run; by providing resident’s aadhaar number, User will land into “Consent for Authentication” form.

consent_0

B. After you press “ACCEPT AND CONTINUE” button; plug in the biometric device. And grant USB device the access permission.

C. Press “Proceed” button, and keep any of the resident’s/customer’s finger on the biometric device.

screenshot_20171004-170118

D. If the image quality is bad. Please try again.

screenshot_20171004-170311

E. If the image quality is good eKYC/Auth information will be passed in string format.

screenshot_20171004-170331-1

Note: In order to get a good quality score place the finger properly, such that the quality acquired by the biometric device will be greater than 70.

4. Response Format

4.1. KYC Success Response:

{
    User_Id: ‘OUR SYSTEM USER ID',
    Aadhar_Id: '655XXXXXXXXX’, //Resident’s Aadhaar Number
    e_Kyc: 
        {
            status: 'y’, //eKYC status y/n
            Description: 'Authenticated Successfully’, //Description from Aadhaar
            Code: '124be446983XXXXXXXXXXXXXXX’, //Unique EKYC/AUTH code from UIDAI - used for any
            Audit purposes.
            RRN: '6345XXXXXXXX’, //Unique signature from our licensee - for quick tracking of request further
                                 //  down
            Poi: 
                { //proof of identity
                    CONFIDENTIAL _4
                    Name: ‘RESIDENT NAME HERE’, //Name of Resident
                    Dob: ‘DD-MM-YYYY’,
                    Gender: 'M/F',
                    Phone: ‘XXXXXXXXXX’ //if provided by resident to Aadhaar
                },
            Poa: 
                {//proof of address
                    co: 'S/O: TEST NAME',
                    house: 'house name',
                    street: ’street name',
                    landmark: ’landmark provided to Aadhaar',
                    lc: ‘locality',
                    vtc: ‘name of village/town/city',
                    subdist: ’sub-district',
                    dist: ‘district',
                    state: ’state name',
                    pc: ‘pin code',
                    po: ‘postal code',
                    uidtag: ‘AAPKA AADHAAR',
                    email: ‘email_id_value’ //if provided by resident to Aadhaar
                },
                 Photo: "base-64-image-data-here"
        },
        "payload": "complete response in base-64 encoded format",
       "transactionId":"6d1XXXX-XXXX-XXXX-XXXX-XXXXXXXb53b", // unique gateway transaction Id
   "qTid":"e7c0XXXX-XXXX-XXXX-XXXX-XXXXXXXXe4bd",           // unique aadhaar transaction id sent by AadhaarAPI
   "time":"XXXX20XX, X:XX:XX XM",
   "ver":"2.1",
   "resident_authentication":"O",           //  mode of authentication F: Fingerprint, O: OTP

}

4.2. AUTH Success Response:

{
    User_Id: ‘OUR SYSTEM USER ID',
    Aadhar_Id: '655XXXXXXXXX’, //Resident’s Aadhaar Number
    e_Kyc:
        {
            status: 'y’, //eKYC status y/n
            Description: 'Authenticated Successfully’, //Description from Aadhaar
            Code: '124be446983XXXXXXXXXXXXXXX’, //Unique EKYC/AUTH code from UIDAI - used for any
            Audit purposes.
            RRN: '6345XXXXXXXX’, //Unique signature from our licensee - for quick tracking of request further
            Down
        }
     "transactionId":"6d1XXXX-XXXX-XXXX-XXXX-XXXXXXXb53b", // unique gateway transaction Id
   "qTid":"e7c0XXXX-XXXX-XXXX-XXXX-XXXXXXXXe4bd",           // unique aadhaar transaction id sent by AadhaarAPI
   "time":"XXXX20XX, X:XX:XX XM",
   "ver":"2.1",
   "resident_authentication":"O",           //  mode of authentication F: Fingerprint, O: OTP

}

4.3. Error Response JSON:

{ "statusCode": 400, //ERROR CODE FROM SERVICE
  "errors": [ //In case of multiple errors, check this for multiple messages.
    { "statusCode" : 400,
      "error" : "Bad Request",
      "message" : "OTP validation failed" 
    } ],
  "message" : "OTP validation failed",
  "resultCode": "400", //ERROR CODE FROM UIDAI
  "Code": "2ecd287d9f774b4bbe7de701263e7a92",
  "RRN": "704418326186",
  "transactionId":"6d1XXXX-XXXX-XXXX-XXXX-XXXXXXXb53b", // unique gateway transaction Id
   "qTid":"e7c0XXXX-XXXX-XXXX-XXXX-XXXXXXXXe4bd",           // unique aadhaar transaction id sent by AadhaarAPI
   "resident_authentication":"O",           //  mode of authentication F: Fingerprint, O: OTP
}