aadhaarapi e-sign gateway

POC: Sagar Giri ([email protected])

Last updated on: Jan 28, 2019

AadhaarAPI E-Sign Gateway 1. INTRODUCTION As a registered ASP under ESP AadhaarAPI provide WEB and Mobile gateway for E-signing of documents. Using these gateways any organisation on-boarded with us can get their documents signed digitally by their customer using Aadhaar number based EKYC (performed on ESP portal). The mode of transaction can be following:

1. Aadhaar Number + OTP (works only on web and android) 2. Aadhaar Number + Fingerprint (works only on windows machine and android) 3. Aadhaar Number + IRIS (works only on Samsung IRIS tablet)

This solves the problem of wet signing of documents, which is a costly and time-consuming process. Aadhaar based E-sign is a valid and legal signature as per government regulations and is accepted widely across India by various organisations. Once you have received the API key generated from the dashboard also download the Android SDK files from the Downloads section. Make sure following files are received inside a zip file:

• .aar file • Demo App • NSDL App.

NOTE: The NSDL App needs to be installed in mobile, only in case of Biometric based E-sign. You don’t need NSDL App for performing OTP based E-sign transaction.

2. PROCESS FLOW 1. Generate the document based on the user info at your backend. 2. At your backend server, Initiate the e-sign transaction using a simple Rest API [POST] call by

converting your document into base64 string or via our Multi-Part Upload API. Details of these are available in the documents later. You will require API key and Agency Id for accessing this API which can be generated from the Dashboard.

3. This gateway transaction id then needs to be communicated back to the frontend(in Android Project) where SDK is to be called.

4. After adding the SDK (.aar file) in your android project, client has to pass the above generated transaction id to an SDK Intent Function, which will open the SDK.

5. SDK will open with a user login after which and the rest of the process till response will be handled by the gateway itself.

6. 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.

7. Result PDF url will be sent to the responseUrl requested via INIT call.

8. Client will also have a REST API available to pull the status of a gateway transaction from

backend and reason of failure.

3. INITIATING A GATEWAY TRANSACTION [IP WHITELISTED IN PRODUCTION]

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

3.1 INIT URL:

URL: POST {{base_url}}/gateway/esign/init/

BASE URL:

For Pre-Production Environment: https://preprod.aadhaarapi.com For Production Environment: https://prod.aadhaarapi.com

Example Url: https://preprod.aadhaarapi.com/gateway/esign/init/

3.2 REQUEST HEADERS: [All Mandatory] QT_API_KEY: <<your api key value – available via Dashboard>>

QT_AGENCY_ID: <<your agency id value – available via Dashboard>>

Content-Type: application/json

3.3 REQUEST BODY PARAMS: [All Mandatory] {

"document": {

"data”: "<<document data in based64 format>>",

"type": "<<pdf is only supported for now>>",

"info”: "<<information about the document – minimum length 15>>"

},

"signerName": "<<name of the signer, must be same as on Aadhaar Card>>",

"signerCity": "<<city of the signer, preferably as mentioned in Aadhaar>>",

"purpose": "Purpose of transaction, Mandatory",

"responseURL":"<<POST[REST] URL to which response is to be sent after the transaction is complete>>",

"version": "2.0 <<current E-sign version>>"

}

https://preprod.aadhaarapi.com

https://prod.aadhaarapi.com

3.4 RESPONSE PARAMS: {

"id": "<<transactionId>>",

"docs": [ "<<document ID>>"

], "request version": "2.0",

"createdAt": "<<timestamp>>" }

Parameters Description/Values Checks

document { Is an object that provides details of the

document. It has below mentioned values in

the object

data PDF document to be signed in base 64 Valid base64 formatted pdf

format.

type Format of the document. For now, only value

pdf is supported

infoInformation about the document to be sent to Minimum length 15

ESP

}

signerName Name of the signer Same as in Aadhaar Card

signerCity Place of signing (Current City/As mentioned

in Aadhaar)

purpose Purpose of document signatureMandate as per norms. Will

be used to generate

consent text and logged in

DB.

responseURL POST API URL where the Agency receivesA valid POST API URL, else

the response after the e-signing is completed. response back to your

server will fail.

version Current E-sign version (2.0) Must be 2.0

The above generated gateway transactionId has to be made available in your android project to open the E-Sign SDK.

Note: A transaction is valid only for 30 mins after generation. 4.ADDING SDK (.AAR FILE) TO YOUR PROJECT To add SDK file as library in your Project, Perform the following Steps:

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

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

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

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

4.5 Keep the app’s module selected and click on the Dependencies pane to add the new module as a dependency. 4.6 Use the “+” button of the dependencies screen and choose “Module dependency”.

4.7 Choose the module and click “OK”.

5. CONFIGURING AND LAUNCHING THE E-SIGN SDK

5.1 IMPORT FILES

Import following files in your Activity: import sdk.quagga.in.e_signlib.qtActivity.AadhaarAPIActivity;

import static sdk.quagga.in.e_signlib.qtUtils.QtConstantUtils.ESIGN_ERROR;

import static sdk.quagga.in.e_signlib.qtUtils.QtConstantUtils.ESIGN_SUCCESS;

import static sdk.quagga.in.e_signlib.qtUtils.QtConstantUtils.QT_EMAIL;

import static sdk.quagga.in.e_signlib.qtUtils.QtConstantUtils.QT_RESULT;

import static sdk.quagga.in.e_signlib.qtUtils.QtConstantUtils.QT_REQUEST_TYPE;

import static sdk.quagga.in.e_signlib.qtUtils.QtConstantUtils.QT_TRANSACTION_ID;

import static sdk.quagga.in.e_signlib.qtUtils.QtRequestType.ESIGN;

import static sdk.quagga.in.e_signlib.qtUtils.QtConstantUtils.REQUEST_AADHAARAPI;

5.2 ADD STRINGS(IN STRINGS.XML FILE)

Add following strings in Strings.xml according to the application’s requirement. // must be ‘QT_PP’ for using E-Sign Pre-Production Environment // must be ‘QT_P’ for using E-Sign Production Environment <string name=“qt_env">QT_PP</string>

// must be ‘y' for allowing OTP based e-sign authentication to user; else ‘n’ <string name=“qt_otp_access">y</string>

// must be ‘y' for allowing Fingerprint based e-sign authentication to user; else ‘n’ <string name=“qt_fp_access">n</string>

// must be ‘y' for allowing Iris based e-sign authentication to user; else ‘n’ <string name=“ qt_iris_access">n</string>

// must be ‘y' for allowing Phone based login to user; else ‘n’

<string name=“qt_phone_auth_access">n</string>

// must be ‘y' for allowing signature’s position to be decided by the user; else ‘n’ <string name=“qt_draggable">y</string>

5.3 CALL E-SIGN SDK FROM THE ACTIVITY

Use the Intent Function to call the E-Sign SDK from your Activity as shown below:

String GatewayId, Email;

Intent gatewayIntent = new Intent(YourActivity.this, AadhaarAPIActivity.class);

gatewayIntent.putExtra(QT_TRANSACTION_ID, GatewayId);

gatewayIntent.putExtra(QT_EMAIL, Email); //Not Mandatory, can be added to pre-fill the Login Box

gatewayIntent.putExtra(QT_REQUEST_TYPE, ESIGN.getRequest());

startActivityForResult(gatewayIntent, REQUEST_AADHAARAPI); Params:

GatewayId: “Transaction Id generated from your backend must be passed here”

Email: “Add your end user’s email here to pre-fill the login box”

Set the QT_REQUEST_TYPE as ESIGN.getRequest() for e-sign based transaction.

Example:

GatewayId = "a051231e-ddc7-449d-8635-bb823485a20d";

Email = “[email protected]";

5.4 HANDLE SDK RESPONSE

After performing a Successful Transaction: Android download manager will start downloading the Signed PDF file. Also the responses incase of successful transaction as well as response in case of error will be

sent to your activity & can be handled via onActivityResult( ) method as shown below. @Override

protected void onActivityResult(int requestCode, int resultCode, Intent data) {

if (requestCode == REQUEST_AADHAARAPI && null != data) {

String requestType = data.getStringExtra(QT_REQUEST_TYPE);

String serviceType = data.getStringExtra(QT_SERVICE_TYPE);

if(requestType.equalsIgnoreCase(ESIGN.getRequest())){

//To handle the Success JSON response from SDK

if (resultCode == ESIGN_SUCCESS) {

String responseString = data.getStringExtra(QT_RESULT); //handle

successful response from AadhaarAPI’s e-sign SDK here

Log.i("SDK test response ", serviceType + " response: " +responseString); // can be removed

}

// To handle the Error JSON response from SDK

mailto:[email protected]

if (resultCode == ESIGN_ERROR) {

String errorString = data.getStringExtra(QT_RESULT); //handle

error response from AadhaarAPI’s e-sign SDK here

Log.i("SDK test error ", serviceType + " error: "+ errorString); // can be removed

}

}

} 6. END-USER FLOW 1. Customer Login

2. Document displayed for customer.

3. Customer chooses mode of authentication for performing E-sign.

4. Customer is redirected to ESP’s App for Authentication.

5. Customer is authenticated, depending upon the selected authentication mode:

5.1 OTP Mode:

5.2 Biometric Mode:

6. After successful EKYC customer is displayed Sign details received and customer’s consent is taken to attach signature to the document and share a copy with requesting organisation.

7. On success, customer is provided with an option to download the signed file. Also, a download URL is sent to customer’s Email and responseURL which is valid for 48 hours.

8. On failure during request to ESP, customer is displayed an error code and error message. Same error details are sent to the responseURL.

7. RESPONSE FORMAT SENT ON MOBILE 7.1 SUCCESS JSON RESPONSE FORMAT FOR E-SIGN SUCCESS

{ "id": “<<transaction_Id>>",

"response_timestamp": "2018-08-01T09:50:06.831Z", "transaction_status": 16,

"signer_consent": "Y", "request_medium": “ANDROID",

"last_document": “true", "current_document": 1,

"documents": [ { "id": “<<unique-document-id >>”,

"index": 1, "type": “pdf",

"doc_info": "Sample pdf - sample doc", "dynamic_url": “<<links-to-download-document>>”,

"sign_status": "Y", "auth_mode": "O",

"response_status": "Y", "error_code": null,

"error_message": null, "request_timestamp": “2018-08-01T09:50:06.831Z” }, ….

], "dynamic_url": “<<links-to-download-document>>”, "msg": “<<Esign Message from ESP/Internal>>” }

Response Parameter Description/Possible Values

id E-sign Transaction Id

response_timestamp ESP response timestamp.

transaction_status Status Code to track last transaction state. List of codes available in

Annexure1.

signer_consent Y/N - Will be N if user denies consent

request_mediumWEB/ANDROID - Platform from which esign transaction was performed

last_document true/false- true if document is last else false

documents [ Is an object that provides details of the single/multiple documents inarray. It has below mentioned values in the object

{ id Document id

index Index of this document

doc_info Info of this document

type Format of the document. For now, only value pdf is supported

dynamic_url Url to download the signed pdf

sign_status Y/N - if document is signed by the user or not

auth_mode O/F/I – OTP, Fingerprint, Iris

response_status Y/N - if ESP response was success or not.

error_code Error code from ESP/Internal (available only in case of error)

error_message Error message from ESP/Internal (available only in case of error)

request_timestamp } Time at which the request was sent to ESP

] dynamic_url Url to download the signed pdf of the current document

message Message from ESP/Internal

7.2 ERROR JSON RESPONSE FORMAT FOR E_SIGN ERROR { "id": “<<transaction id>>",

"signer_name": “Abc Name", "signer_city": “xyz city",

"current_document": 1, "user_notified": "N",

"purpose": "Development and testing purpose", "transaction_status": 17,

"signer_consent": "Y", "request_medium": "ANDROID",

"signed_document_count": 0, "error_code": "ESP-123",

"error_message": “<<Error Message>>","response_status": "N", "response_timestamp": “2018-08-01T12:09:48.500Z”,

"msg": "Error Code :ESP-123 (<<Error Message>>)” }



signer_name Name of signer as provided in INIT call.

signer_city City of signer as provided in INIT call.

current_document Current document number



Purpose Purpose for signing the document

user_notified Y/N - User notified of the E-sign success and sent a copy of document

to download.


Annexure1.

signed_document_count count of the number of documents signed




Annexure 1 – Transaction Status INITIATED : 1,

INITIATION_FAILED: 2,

OTP_SENT: 3,

OTP_FAILED: 4,

SUCCESSFUL: 5,

FAILED: 6,

OTP_MISMATCH: 7,

FP_MISMATCH: 8,

EXPIRED: 9,

CONSENT_DENIED: 10,

TERMINATED_BY_USER: 11,

OTP_REQUEST_LIMIT_CROSSED: 12,

OTP_FAILURE_LIMIT_CROSSED: 20,

OTP_EXPIRED: 13,

LOGIN_SUCCESS: 14,

ESP_REQ_INITIATED: 15,

ESP_REQ_SUCCESS: 16,

ESP_REQ_FAILED: 17,

USER_NOTIFIED: 18,

TRANSACTION_LIMIT_CROSSED: 19

7.3 ERROR JSON RESPONSE FORMAT FOR GATEWAY ERROR

{ "statusCode": 422,

"message": "Maximum OTP Tries Reached, Transaction Failed” }


msg Error code and error message


statusCode Error code from gateway/sdk

message Error message from gateway/sdk

8. RESPONSE FORMAT SENT ON RESPONSE_URL(ADDED IN INIT API CALL)

8.1 SUCCESS JSON RESPONSE FORMAT FOR E-SIGN SUCCESS

{ "id": “<<transaction_Id>>",

"response_timestamp": "2018-08-01T09:50:06.831Z",

"transaction_status": 16, "signer_consent": "Y", "request_medium": “M", "last_document": “true",

"current_document": 1, "documents": [

{ "id": “<<unique-document-id >>”, "index": 1,

"type": “pdf", "doc_info": "Sample pdf - sample doc",

"dynamic_url": “<<links-to-download-document>>”, "sign_status": "Y", "auth_mode": "O", "response_status": "Y",

"error_code": null, "error_message": null,

"request_timestamp": “2018-08-01T09:50:06.831Z" }, ….]

}





Annexure1.


request_medium W for WEB/ M for Mobile - Platform from which esign transaction was

performed

last_document true/false- true if document is last else false

documents [ Is an object that provides details of the single/multiple documents in

array. It has below mentioned values in the object

{ id Document id


8.2 ERROR JSON RESPONSE FORMAT FOR E_SIGN ERROR

{ "id": “<<transaction_Id>>", "response_timestamp": "2018-08-03T09:14:21.805Z", "transaction_status": 17,

"signer_consent": "Y", "request_medium": "M",

"current_document": 1, "documents": [

{ "id": “<<unique-document-id >>”, "index": 1,

"doc_info": "Sample pdf - sample doc", "type": "pdf",

"dynamic_url": “<<links-to-download-document>>”, "sign_status": "N",

"auth_mode": "O", "response_status": "N",

"error_code": “<<Error code if any>>”,

"error_message": “<<Error message if any>>”,

"request_timestamp": "2018-08-03T09:14:21.805Z" } ]…

}









]





9. BIOMETRIC DEVICES SETUP For bio transactions UIDAI has made use of RD service mandatory and all devices has to be registered with device vendor’s RD management server before performing biometric based transactions. Also for devices to work in windows RD services has to be setup in the windows machine and for Android devices to work, RD service APPs has to be installed from Play-store from specific device vendors.

In order to perform the E-sign transaction via biometric modes (i.e. Fingerprint and Iris).

The device must be registered with their respective device vendor’s RD management server and Application from play store or SDK provided by some device vendor(provided incase of some iris devices) must be installed in your Android Device before performing E-sign transaction through biometric mode.

In case of RD service not working with the Demo apps. please contact the device vendor support team. Once these demo apps are working. You will be able to use these devices with our SDKs.




Annexure1.

documents [ Is an object that provides details of the single/multiple documents in

array. It has below mentioned values in the object

{ id Document id











]

List of supported Biometric Devices

10. PULLING TRANSACTION STATUS AT BACKEND In case the response JSON is lost at frontend, there is an option to pull the transaction status from

backend using the same Esign Transaction Id.

10.1 URL:

GET {{base_url}}/gateway/esign/:esign_transaction_id/fetch/

10.2 RESPONSE PARAMS:

{ "id": “<<transaction id>>", "request_version": "2.0", "signer_consent": "Y", "response_url": "<<POST[REST] URL to which response is to be sent after the transaction is complete>>", "current_document": 1, "signed_document_count": 1, "public_ip": "223.196.31.21", "env": 1, "signer_name": "Demo Name", "signer_city": "Demo City", "purpose": "Development and testing purpose", "transaction_status": 5, "request_medium": "M", "transaction_attempts": 1, "otp_attempts": 1, "otp_failures": 0, "user_notified": "Y",

Sr. No. Device Manufacturer Model

1 Morpho

MSO 1300 E

MSO 1300 E2

MSO 1300 E3

2 Secugen Hamster Pro HU20

3 Mantra %MFS100

4 Startek FM220U

5 Evolute Falcon Identi5 Leopard

6 Cogent CSD 200

7 Precision PB510

8 Freedom ABB-100-NIR

9 Samsung Galaxy IRIS Tab SM-T116IR

"response_to_agency": "Y", "createdAt": "2018-08-03T08:43:39.751Z", "documents": [ { "id": “<<document id>>",

"index": 1, "doc_info": "Sample pdf - sample doc", "type": "pdf", "dynamic_url": “<<Link to download this pdf>>", "sign_status": "Y", "auth_mode": "O", "response_status": "Y", "error_code": “<<error code if any>>”, "error_message": “<<error message if any>>”, "request_timestamp": “2018-08-03T08:47:50.661Z" }

] }



request_version Esign version – currently 2.0


signed_document_count count of the number of documents signed

response_url URL to which the response was sent on completion


request_medium W for Web/ M for Mobile - Platform from which esign transaction was

performed

public_ip End user IP using which the transaction was performed.

env 1/2 – 1(preproduction) & 2 (production)

signer_name Name of signer as provided in INIT call.

purpose Purpose for signing the document

signer_city City of signer as provided in INIT call.


Annexure1.

transaction_attempts Transaction attempt count. Currently allowed only once.

otp_attempts Number of times login OTP was requested

otp_failures Number of times login failed due to wrong OTP

user_notified Y/N - User notified of the E-sign success and sent a copy of document

to download.

response_to_agency Y/N - Response sent to responseURL was success or failure.

createdAt Transaction initiated at - YYYY-MM-DDTHH:MM:SS.122Z

documents[ Is an object that provides details of the single/multiple

documents in array. It has below mentioned values in the object

{ id Document id

index Index of document

doc_info Info of the document








request_timestamp } ,.. ] Time at which the request was sent to ESP

aadhaarapi e-sign gateway

Documents