NAV Navbar
cURL JSON CodeSnippet

1. Introduction

Veri5Digital’s eSign Android SDK can be integrated with Clients Android Application to :

Note :

This document explains the steps to integrate the eSign Android SDK into clients Android Application. Sample code snippets are wherever applicable are available for reference.

2. Steps to Integrate eSign WEB SDK

Clients should follow the below steps for integrating eSign Android SDK to client application.

  1. Client should get on boarded or registered with Veri5Digital Platform and get client credentials and other parameters required for integration.

  2. Installation of ESP Android Application

  3. Integration of Document Upload API to upload the document to be Signed.

  4. Integration of eSign SDK into Clients Application

  5. Integration of Document Download API to download the signed document.

Veri5Digital Platform provides Preprod Environment for Integration and Production Environment for actual production purposes.

We recommend you to integrate your application in pre-prod environment first and then move to production post testing and certification in Pre-Prod Environment.

2.1 Client Registration

For a client to get access to service and do integration, client registration is mandatory.

As part of registration , Client has to obtain values for following params for both Pre-Prod and Production Environments.

Note :

2.2 Integration of Document Upload API ( _upload )

Clients application should invoke upload document ( _upload ) API to submit the document that has to be eSigned.

Given below are the details of the Request Payload of _upload request. Sample request follows the same.

API Name : _upload

Method : POST

Preprod URL : https://preprod.aadhaarbridge.com/api/_upload

Production URL : https://preprod.aadhaarbridge.com/api/_upload

_upload Request Details

Content-Type: multipart/form-data

Refer below table for the request body parameters. Client application should POST these parameters as a FORM Submit Action.

Table : _upload API Request Body Parameters

Field Name Type Comments Example
saCode String, Mandatory Your client code received during onboarding and also you can get this info from Client a1b2c3
request_id String, Mandatory Unique transaction identifier Client app has to generate the same.For each request it should be unique.This is used for uniquely identifying the transaction. 12345678910111
docNo String, Mandatory This is document number. requestId and docNo are together used to identify each document uniquely. Please pass value ‘1’ always. 1
hash String, Mandatory This should be a SHA-256 value of Hash Sequence defined for _upload request. Purpose of this is to ensure the integrity of the request. Refer to Appendix A for hash generation logic. 9780cd0d2c e77eef8f649 42f54e0281 a0e220ff6bb cce0a03df27 a2b15575f58
file1 Multipart File,, Mandatory file1 attribute is the actual file that you want to eSign
docType String,Mandatory, This indicates the type of document being uploaded for eSign. We currently support pdf and XML file formats. PDF Or XML
pageNo String,Optional Indicates page no on which you want signature to be placed . By Default : “1”, ie in case where pageNo is not provided. If value is ‘all”, eSign will appear in all pages.. “1,4,7” (for specific pages. In this case eSign will appear on pages 1, 4 and 7) all - (all pages)
rectangle String,Mandatory Comma separated integers indicating coordinates of rectangle where signature will be placed. Details are given below.. 100,100,400,200
reason String,Mandatory Specify the reason for e-signing this document. This will be part of signature rectangle. This should be valid string of length 6 to 50 characters.
location String, optional Optionally specify the location where e-signing is being done. This will be part of signature rectangle. Bangalore,Karnataka

Sample Html Code for _upload

Below given code snippet demonstrates how to invoke the Veri5 Digital eSign SDK from a form in clients application.

<form action="https://preprod.aadhaarbridge.com/api/_upload" method="post"
enctype="multipart/form-data">
<input type="text" name="saCode" value="<<your sa code>>">
<input type="text" name="<<requestId>>" >
<input type="text" name="<<docNo>>" >
<input type="text" name="<<hash>>" >
<input type="file" name="<<file1>>">
<input type="text" name="<<docType>>" >
<input type="text" name="<<pageNo>>" >
<input type="text" name="<<rectangle>>" >
<input type="text" name="<<reason>>" >
<input type="text" name="<<location>>" >
<button type="submit">Submit</button>
</form>

Rectangle Field Details

This defines the coordinates of the rectangular box where eSign will appear in the document.

Rectangle(50, 400, 200, 500) <==> (x1, y1, x2, y2)

Points to Note

_upload Response Details

Response structure is as given below, where fields

success : Indicates the status of the API execution. Possible values are true or false.

errorCode : Contains the error code whose details are given in below table.

message : Message corresponding to the error code.

Note : Error Code is Empty String in case of success is true.

{
"success":true/false,
"errorCode":"",
"message":""
}

Sample Response
{
"success":true,
"errorCode":"",
"message":"Document uploaded successfully."
}

_upload API Error Codes

errorCode message
1001 saCode is missing
1002 requestId is missing
1003 docNo is missing
1004 hash is missing
1005 file1 is missing
1006 Internal-server-error. Contact us.
1007 saCode is invalid
1008 profile is invalid
1009 SubAUA is not allowed eSign
1010 docType is invalid
1011 docType is missing
1012 docNo is invalid
1013 rectangle is missing
1014 reason is missing
1015 pageNo is invalid
1016 docNo already exists
1017 Could not detect prod/preprod salt.
1018 Invalid Hash
1019 rectangle is invalid
1020 Internal-server-error. Contact us.
1021 No more uploads are allowed.
1022 Invalid file
1023 failed to save document. Contact us.
1024 Max 10 documents are allowed

2.3 Integration of eSign Init API (_init)

Once document is uploaded, you need to initiate eSign request using same requestId that you used to upload documen (see eSign Init API). If request is valid you will be redirected to VEri5Digital’s page to give consent. After clicking on submit you will be redirected to Esign Service Provider’s (ESP) page.

  1. User will be asked to input his Virtual ID (not Aadhaar no.) on ESP page.

  2. Then he will be asked to give consent, generate the OTP and enter it.

  1. User will be asked to input his Virtual ID or Aadhaar no. on ESP page.

  2. Then biometric capture would be done. (Please make sure the RD service is running and biometric device is ready to capture data).

API Name : _init

Method : POST

Preprod URl : https://preprod.aadhaarbridge.com/api/_init

Production URL : https://prod.aadhaarbridge.com/api/_init

Sample Html Code for eSign SDK Initiation

Below given code snippet demonstrates how to invoke the Veri5 Digital eSign SDK from a form in clients application.

  <form method="post" action="https://preprod.aadhaarbridge.com/api/_init">
  <input type="hidden" name="saCode" value="<your sa code>" >
  <input type="hidden" name="api" value="ESIGN" >
  <input type="hidden" name="requestId" value="<request id which was sent in document upload api>" >
  <input type="hidden" name="timeStamp" value="<timestamp in millisecond>" >
  <input type="hidden" name="purpose" value="<purpose of doing Esign>" >
  <input type=”hidden” name=”otp” value=”N/Y”>
  <input type=”hidden” name=”fingerPrint” value=”N/Y”>
  <input type=”hidden” name=”iris” value=”N/Y”>
  <input type="hidden" name="channel" value="BOTH" >
  <input type="hidden" name="esignName" value="abc" >
  <input type="hidden" name="successUrl" value="<successUrl>" >
  <input type="hidden" name="failureUrl" value="<failureUrl>" >
  <input type="hidden" name="hash" value="<sha256 hash value>" >
  <button type="submit">Proceed </button>
  </form >

Additional Error Codes:

Points to Note:

_init Response Details

successUrl?aadhaarId=emptyhash=hash&uuid=uuid&requestId=requestId&success=true/false

Eg:

https://mydomain.com/success.html?aadhaarid=&hash=9780cd0d2ce77eef8f64942f54e0281a0e220ff6bbcce0a03df27a2b15575f58&uuid=33adb2ce-b26b-4cef-a485-1f4ac638fa63&requestId=123456789101112&status=success

failureUrl?&aadhaarId=emptyhash=hash&uuid=uuid&requestId=requestId&success=true/false&errorCode=error-code

Eg:

https://mydomain.com/failure.html?aadhaarid=&hash=9780cd0d2ce77eef8f64942f54e0281a0e220ff6bbcce0a03df27a2b15575f58&uuid=33adb2ce-b26b-4cef-a485-1f4ac638fa63&requestId=123456789101112&success=false&errCode=100

_init API Error Codes

errorCode message Resolution
1041 No esign request found for saCode and requestId
1042 Could not download the document Please contact us
1043 Could not calculate hash of the document Please contact us
1044 could not upload temp document Please contact us
1045 Esign Is failed due to internal issues
1061 Could not download document (while attaching the signature) Please contact us
1062 Could not upload document (while attaching the signature) Please contact us
1063 Could not attach sign to the document Please contact us
1064 Internal Server Error Please contact us
1065 Internal Server Error Please contact us
1901-1922,1992,2995 Internal Server Error Please contact us
1991,1993-1996,2996-2999 Technical failure on Esign Provider, Please try again after some time
1999 Unknown Error
3000 Session Has Expired
3001 You have exceeded your maximum allowed limit. Please try with new request
3002 Invalid OTP Value, Please try with new request
3003 User cancelled the transaction
3005 This Aadhaar card is not linked to mobile number/email id.
3006 Biometric for this Aadhaar has been disabled by the user.
3007 You have entered an invalid OTP.
3008 Technical failure on Esign Provider, Please try again after some time
3009 Technical failure on Esign Provider, Please try again after some time
3010 Technical failure on Esign Provider, Please try again after some time
3011 Technical failure on Esign Provider, Please try again after some time
3012 Technical failure on Esign Provider, Please try again after some time
3013 Technical failure on Esign Provider, Please try again after some time
3014 Technical failure on Esign Provider, Please try again after some time
3015 Technical failure on Esign Provider, Please try again after some time
3016 Technical failure on Esign Provider, Please try again after some time
3018 Technical failure on Esign Provider, Please try again after some time
3019 Technical failure on Esign Provider, Please try again after some time
3023 Technical failure on Esign Provider, Please try again after some time
3025 Technical failure on Esign Provider, Please try again after some time
3026 Technical failure on Esign Provider, Please try again after some time
3028 Technical failure on Esign Provider, Please try again after some time
3029 Technical failure on Esign Provider, Please try again after some time
3030 Technical failure on Esign Provider, Please try again after some time
3031 Technical failure on Esign Provider, Please try again after some time
3032 Technical failure on Esign Provider, Please try again after some time
3044 Technical failure on Esign Provider, Please try again after some time
3033 Technical failure on Esign Provider, Please try again after some time
3034 Technical failure on Esign Provider, Please try again after some time
3035 Technical failure on Esign Provider, Please try again after some time
3036 Technical failure on Esign Provider, Please try again after some time
3037 Technical failure on Esign Provider, Please try again after some time
3038 Technical failure on Esign Provider, Please try again after some time
3039 Technical failure on Esign Provider, Please try again after some time
3040 This process was terminated by the user.
3041 This process was terminated by the user after OTP generation.
3042 User interface page expired. Please initiate this process again.
3043 User authentication failed. Please try again.
3045 Technical failure on Esign Provider, Please try again after some time
3046 Technical failure on Esign Provider, Please try again after some time
3047 Technical failure on Esign Provider, Please try again after some time
3048 Consent Not Provided by the User
3049 Invalid OTP Value, Please try with new request
3050 Invalid Biometric Value, Please try with new request
3051 Invalid Iris Value, Please try with new request
3052 Technical failure on Esign Provider, Please try again after some time

2.4 Integration Document Download API ( _download)

At this step signed document will be downloaded.

API Name : _download

Method : POST

Preprod URL :

https://preprod.aadhaarbridge.com/api/_download/<saCode>/<requestId>/<docId>

Production URL :

https://prod.aadhaarbridge.com/api/_download/<saCode>/<requestId>/<docId>

_download Request Details

Content-Type: multipart/form-data

Refer below table for the request body parameters.

name value comments example
saCode String, Mandatory Your client code. You can find this in your user portal.
requestId String, Mandatory Unique transaction identifier for the client. This should be the same across all documents that you want to sign together. Also this should not be the same as aadhaarId since aadhaar number can not be used as primary key for any purpose. 12345678910111
docId String, Mandatory The document number with which the document was uploaded. 1

Sample Code

https://preprod.aadhaarbridge.com/api/_download/a1b2c3/12345678910111/1

Appendix A: Hash generation

It is essential that we have a definitive protocol to verify the integrity of all the communication between Khosla Labs Platform and Client. So for every request coming to KL, client has to supply a hash which KL will use as the first step of verification.

In return, all responses will also contain hash supplied by KL Platform. You should not entertain any request at your callbackUrl if the hash does not match.

Hash Sequence is specified as follows(no space, no commas, no single/double quotes). Hash sequence is defined for each request and response.

Example for _init request, 
If your 
saCode=a1b2c3,
api=ESIGN,
requestId=1234567890101112,
timestamp=1509288409222,
salt=e1d2c3b4,

then

Hash-Sequence=a1b2c3|ESIGN|1234567890101112|1509288409222|e1d2c34
hash =SHA-256(Hash-Sequence)

For validation:

Sample Code Snippet _upload Request Hash Calculation

Function to calculate Hash based on the input hash sequence parameters.Below given function depicts hash calculation for _upload ( Document Upload ) Api.

private String calculateHash(String saCode, String requestId, String docNo, String salt) throws NoSuchAlgorithmException {
  MessageDigest digest;
  digest = MessageDigest.getInstance("SHA-256");         
  if (digest != null) {
      byte[] hash = digest.digest((saCode + "|" + requestId + "|" + docNo + "|" + salt).getBytes());
      return bytesToHex(hash);
  }
  return null;
}

private final static char[] hexArray = "0123456789ABCDEF".toCharArray();
public static String bytesToHex(byte[] bytes) {
  char[] hexChars = new char[bytes.length * 2];
  for (int j = 0; j < bytes.length; j++) {
  int v = bytes[j] & 0xFF;
  hexChars[j * 2] = hexArray[v >>> 4];
  hexChars[j * 2 + 1] = hexArray[v & 0x0F];
  }
  return new String(hexChars);
}
cURL JSON CodeSnippet