Revision History
Sl# | Ver# | Modified By | Update | Updated On |
---|---|---|---|---|
1 | 1.0 | Tech Team | - Initial Draft | 29/05/2019 |
1. Introduction
Khosla Labs’ Veri5 Digital Platform offers Verification APIs that can be used to verify the authenticity of OVD ( Officially Verified Documents ) like PAN,VoterId,Aadhaar etc by doing a check against original data source. For example, authenticity of PAN data can be assured by doing check against Income Tax Database, Voter Id data can be verified against Election Commission Database.
The list of core APIs include :
- verifyUserIdDoc [ PAN ]
- verifyUserIdDoc [ Aadhaar ]
- bankVerification [bank verification]
- verifyGSTIN [ GST Details ]
2. Prerequisite
For a client to get access to APIs, client registration is mandatory. Khoslalabs provide two environments :
Sandbox Environment
Its recommended to have the client first do technical integration of the API in Sandbox environment, followed by testing and certification.Production Environment Post certification in Sandbox Environment, for actual production purposes, clients should move to Production Environment.
The client has to obtain the following values for the following params :
Client Code (client_code), that uniquely identifies the client that is onboarded with the Khosla Labs.
API-Key (api_key), will be provided during onboarding and is used for managing subscription.
Salt ( salt), this is the salt for calculating hash of request payload and will be shared during onboarding. Each api_key will have its own salt.
Hash ( hash ), this is the dynamic param that should be calculated during each SDK invocation.
For invoking API client_code, api_key, and hash have to be mandatorily passed
Refer to Appendix A for Request Headers Information.
Refer to Appendix B for Error Codes.
Refer to Appendix C for Input Image Specifications for achieving better results.
Refer to Appendix D for how to capture good images
2.1 Hostname:
In sandbox environment hostname: sandbox.veri5digital.com in production environment hostname: prod.veri5digital.com
3. API Specification
Khosla Lab’s APIs can be consumed at exposed REST Endpoints. Request and Response Payloads are JSON documents. API communications should be made over HTTPS.
APIs are exposed to consumers in different environments like SandBox and Production. The primary purpose of the sandbox environment is to expose the APIs to consumers where they can test and do technical integrations before moving to actual production.
3.1 API : verifyUserIdDoc [ PAN ]
This API can be used to verify the PAN document details ( PAN#, Name and Dob ) of the user against Income Tax Database.
This API supports different options as mentioned below :
VERIFY_PAN_DATA: Using this option user information in PAN card like Pan Number, Date of Birth and Full Name can be verified against the database.
VERIFY_PAN_NUMBER: PAN card number can be given as Input and verify the same against the database.
Method : POST
Url : https://hostname
/service/api/1.0/verifyUserIdDoc
### 3.1.1 Request Payload
{
"headers": // Please refer Appendix A for details.
{
"client_code": "<your_client_code>",
"sub_client_code": "<your_sub_client_code>",
"channel_code": "",
"channel_version": "",
"stan": "<a_unique_integer>",
"client_ip": "",
"transmission_datetime": "",
"operation_mode": "SELF",
"run_mode": "",
"actor_type": "",
"user_handle_type": "",
"user_handle_value": "",
"location": "NA",
"function_code": "<< VERIFY_PAN >>",
"function_sub_code": << DATA | DOCUMENT | NUMBER>>
},
"request": {
"pan_details": {
"pan_number": "",
"name": "",
"dob": "dd/mm/yyyy", // Can also be any other date depending on the pan type.
"pan_type" : "" // Please refer Table 1 below for types of PANs
"document": "" // Base64 PAN card image if function subcode is DOCUMENT
},
"consent": "",
"consent_message": ""
}
}
Table 1: PAN Type Info
Sl# | Type | Description |
---|---|---|
1 | IND | Individual |
2 | HUF | Hindu Un-divided Family |
3 | AOP | Association Of Persons |
4 | BOI | Body Of Individuals |
5 | COM | Company |
6 | GOV | Government |
7 | AJP | Artificial Juridical Person |
8 | LOA | Local Authority |
9 | FIR | Firm |
10 | TST | Trust |
### 3.1.2 Response Payload
API will respond with verification status as SUCCESS or FAIL depending on the authenticity of the data.
{
"txn_id": "", //unique alphanumeric value against each transaction used to fetch PAN details.
"verified_by":"Income tax e-Filing Portal",
"verified_data":"", // Refer to Table 2 below for details.
"verification_method":"", // VERIFY_PAN_DATA | VERIFY_PAN_DOCUMENT
"stan":"",
"verification_status":"<< SUCCESS | FAIL >>",
"verified_using":"Database Check",
“verification_code”: “”,
"response_status":
{
"code":"",// 000 in case of Success
"message":"",// Refer to Table 2 below for details.
"status":"<< SUCCESS | FAIL >>"
}
}
Table 2 : PAN - Verification Codes And Messages
Sl# | Verification Status | Verification Code | verified_data [Message] |
---|---|---|---|
1 | SUCCESS | 000 | Verification done Successfully and details are matching with the PAN Database. |
2 | FAIL | 400101 | PAN format is correct and PAN number is correct matching against DOB. However, Name is Incorrect. |
3 | FAIL | 400102 | PAN format is correct but PAN or Name or DOB is incorrect. |
4 | FAIL | 400103 | Invalid PAN |
5 | FAIL | 410007 | Verification Service Not Available. |
6 | FAIL | 400099 | Unknown Error Occurred.Please try after some time. |
3.2 API : fetchPanDetails [ PAN ]
This API is used to fetch PAN details of the transaction. To fetch the PAN details(Name/DOB and PAN nunmber), verifyUserIdDoc API needs to called using "function_code": "VERIFY_PAN". "txn_id" obtained in the response in the of verifyUserIdDoc is used in the request of this API. Note: This is an optionl API and return the same data passed in verifyUserIdDoc API.
Method : POST
Url : https://hostname
/service/api/1.0/fetchPanDetails
### 3.2.1 Request Payload
{
"headers": // Please refer Appendix A for details.
{
"client_code": "<your_client_code>",
"sub_client_code": "<your_sub_client_code>",
"channel_code": "",
"channel_version": "",
"stan": "<a_unique_integer>",
"client_ip": "",
"transmission_datetime": "",
"operation_mode": "SELF",
"run_mode": "TEST",
"actor_type": "TEST",
"user_handle_type": "EMAIL",
"user_handle_value": "test@gmail.com",
"location": "",
"function_code": "DEFAULT",
"function_sub_code": "DATA|NUMBER"
},
"request": {
"txn_id": "<<txn_id>>", //unique txn_id in the response of verifyUserIdDoc API
"api_key": "<<your api_key>>",
"hash":"" //Hash will be generated as SHA256(client_code|txn_id|api_key|salt)
}
}
### 3.2.2 Response Payload
Incase of fetching details of PAN, API will respond with response status as SUCCESS or FAIL.
{
"response_data": {
"response_message": ""
},
"response_status": {
"Code":"", // 000 in case of Success
"Message":"", // Refer to Table 2(b) below for details.
"status":"<< SUCCESS | FAIL >>"
}
}
Table 3 : fetchPanDetails - Response Codes And Messages
Sl# | Verification Status | Verification Code | verified_data [Message] |
---|---|---|---|
1 | SUCCESS | 000 | Pan details fetched successfully |
2 | FAIL | 400105 | txnId does not exist |
3 | FAIL | 400106 | Pan OCR does not exist |
4 | FAIL | 400111 | api_key does not exist. |
5 | FAIL | 400112 | txnId does not exist |
6 | FAIL | 400113 | PAN OCR does not exist |
3.3 API : verifyUserIdDoc [ Aadhaar ]
This API can be used to verify the Aadhaar document number against the government database.
This API supports different options as mentioned below :
- VERIFY_AADHAAR_DATA: Using this option Aadhaar number can be verified.
Method : POST
Url : https://hostname
/service/api/1.0/verifyUserIdDoc
### 3.3.1 Request Payload
{
"headers": // Please refer Appendix A for details.
{
"client_code": "<your_client_code>",
"sub_client_code": "<your_sub_client_code>",
"channel_code": "",
"channel_version": "",
"stan": "<a_unique_integer>",
"client_ip": "",
"transmission_datetime": "",
"operation_mode": "SELF",
"run_mode": "",
"actor_type": "",
"user_handle_type": "",
"user_handle_value": "",
"location": "NA",
"function_code": "<< VERIFY_AADHAAR >>",
"function_sub_code": << DATA >>
},
"request": {
"aadhaar_details": {
"aadhaar_number": ""
},
"consent": "",
"consent_message": ""
}
}
### 3.3.2 Response Payload
Incase of Aadhaar data, API will respond with verification status as SUCCESS or FAIL
depending on the authenticity of the data. In case Aadhaar number is valid, you will also get
“Age Band”, “Gender”, “State” and “Mobile Number” if linked, in “verified_data”
{
"verified_by":"UIDAI Portal",
"response_status":{
"code":"",
"message":"",
"status":"<< SUCCESS | FAIL >>"
},
"Verified_data":
{
“Age_band” : “ “,
“Gender” : “ “,
“State” : “”,
“Mobile_number” : “ “
}
"Verification_method":"", // VERIFY_AADHAAR_DATA
"stan":"",
"verification_status":"<< SUCCESS | FAIL >>",
"Verified_using":"Database Check",
“verification_code”: “”
}
Table 4 : Verification Codes And Messages
Sl# | Verification Status | Verification Code | verified_data [Message] |
---|---|---|---|
1 | SUCCESS | 000 | Verification done Successfully and details are matching with the PAN Database. |
2 | FAIL | 400301 | Aadhaar number is not present. |
3 | FAIL | 400302 | Verification is not complete. Please Try again. |
4 | FAIL | 400303 | Not a valid Aadhaar number. |
5 | FAIL | 400304 | UIDAI website not reachable. |
6 | FAIL | 333 | Unknown Error Occurred.Please try after some time. |
3.4 API : bankVerification [ POST ]
Khosla Labs’ Veri5Digital Platform offer bank account verification API that can be implemented to verify a beneficiary's account for money transfer.
This API is used to initiate the transaction.
Method : POST
Url : https://
### 3.4.1 Request Payload
{
"version":"",
"uniqueRequestNo":"", //Has to be unique for every request
"purposeCode":"",
"customerID":"",
"clientCode":"",
"debitAccountNo":"",
"beneficiary":{
"beneficiaryDetail": {
"beneficiaryName": {
"fullName": ""
},
"beneficiaryAddress": {
"address1" : "",
"country": ""
},
"beneficiaryContact": {
"mobileNo": "",//Optional
"emailID": ""//Optional
},
"beneficiaryAccountNo": "",
"beneficiaryIFSC": ""
}
},
"transferType":"", //It has to be IMPS
"transferCurrencyCode":"Rs",
"transferAmount":1.00,
"remitterToBeneficiaryInfo": "" //note from the sender to the receiver
}
### 3.4.2 Response Payload
API will respond with verification status as SUCCESS or FAIL depending on the authenticity of the data.
{
"code":"<< 4000 | 4002 >>",
"message":"",
"status":"<< SUCCESS | FAIL >>",
}
Table 5 : Verification Codes And Messages
Sl# | Verification Status | Verification Code | verified_data [Message] |
---|---|---|---|
1 | SUCCESS | 4000 | ACCOUNT SUCCESSFULLY VERIFIED |
2 | FAIL | 4001 | ACCOUNT NOT VERIFIED(Bank’s specific reason will be included in response payload) |
3 | FAIL | 4002 | UNABLE TO VERIFY ACCOUNT(Caused due to Internal Error) |
3.5 API : verifyGSTIN [ GST Details ]
This API can be used to fetch and verify GST details.
Method : POST
Url : https://hostname
/service/api/1.0/verifyGSTIN
### 3.5.1 Request Payload
{
"headers":
{
"client_code": "<your_client_code>",
"sub_client_code": "<your_sub_client_code>",
"channel_code": "",
"channel_version": "",
"stan": "<a_unique_integer>",
"client_ip": "",
"transmission_datetime": "",
"operation_mode": "SELF",
"run_mode": "",
"actor_type": "",
"user_handle_type": "",
"user_handle_value": "",
"location": "NA",
"function_code": "DEFAULT",
"function_sub_code": "DEFAULT"
},
"request": {
“request_id” : “”,
“gstin” : “”,
“api_key” : “”,
“hash” : “”
}
}
### 3.5.2 Response Payload
API will respond with verification status as SUCCESS or FAIL depending on the authenticity of the data.
{
"response_status":{
"code":"",
"message":"",
"status":"<< SUCCESS | FAIL >>"
},
{
“gstin” : “ “,
“lgnm” : “ “,
“stj” : “ “,
“ctj” : “ “,
“rgdt” : “ “,
“ctb” : “ “,
“dty” : “ “,
“nba” : “ “,
“sts” : “ “,
“cxdt” : “ “,
“lstupdt” : “ “,
“stjCd” : “ “,
“ctjCd”: “ “,
“tradeNam” : “ “,
“adadr” : “ “,
“addr” : “ “,
“bnm” : “ “,
“st” : “ “,
“loc”: “ “,
“bno”: “ “,
“stcd” : “ “,
“flno”: “ “,
“lt” : “ “,
“lg” : “ “,
“pncd” : “ “,
“ntr” : “ “,
“pradr” : “ “
}
}
Table : Response Status Fields
SI# | Type | Description |
---|---|---|
1 | gstin | GSTIN of the Tax Payer |
2 | lgnm | Legal Name of Business |
3 | stj | State Jurisdiction |
4 | ctj | Centre Jurisdiction |
5 | rgdt | Date of Registration |
6 | ctb | Constitution of Business |
7 | dty | Taxpayer type |
8 | nba | Nature of Business Activity |
9 | sts | GSTN status |
10 | cxdt | Date Of Cancellation |
11 | lstupdt | Last Updated Date |
12 | stjCd | State Jurisdiction Code |
13 | ctjCd | Centre Jurisdiction Code |
14 | tradeNam | Trade Name |
15 | adadr | Additional Place of Business Fields |
16 | addr | Additional place of business address |
17 | bnm | Building Name |
18 | st | Street |
19 | loc | Location |
20 | bno | Door Number |
21 | stcd | state name |
22 | flno | floor nbr |
23 | lt | latitude |
24 | lg | longitude |
25 | pncd | pin code |
26 | ntr | Nature of Additional place of business |
27 | pradr | Principal Place of Business Address |
Table 6 :VerifyGSTIn - Verification Codes And Messages
Sl# | Verification Status | Verification Code | verified_data [Message] |
---|---|---|---|
1 | SUCCESS | 000 | Verification done Successfully. |
2 | FAIL | 400401 | Hash Validation Failed |
3 | FAIL | 400402 | Sorry, You have exceeded the consumption limit. Please contact customer.support@aadhaarbridge.com |
4 | FAIL | 400403 | request_id is mandatory |
5 | FAIL | 400404 | gstin field is mandatory |
6 | FAIL | 400405 | api_key is mandatory |
7 | FAIL | 400406 | hash is mandatory |
Refer Appendix E for hash calculation.
Appendix A: Request Header Field Details
Every APIs Request Payload has a custom “header” field, whose details are given below. Fields marked ( * ) are mandatory.
S.NO | Field Name | Mandatory | Description | Example |
---|---|---|---|---|
1 | client_code* | A unique code assigned to a client while onboarding. | client123 | |
2 | sub_client_code* | Unique code assigned to a sub client of a hosted client.In case not applicable, an EMPTY (“”) string can be passed. | client123 | |
3 | actor_type* | Type of person who is making the request.If not relevant, "DEFAULT" can also be used. | CUSTOMER/DEFAULT | |
4 | channel_code* | Channel code used by the client to initiate the request. | ANDROID_SDK | |
5 | stan* | System Trace Number - A unique number generated per request by the client. It is used to uniquely identify a request from a client. It can be used for troubleshooting. | 98321892319 | |
6 | user_handle_type* | Indicates the type of the user identifier, who has initiated the request. Eg: UUID, MSISDN, EMAIL. If not relevant, "DEFAULT" can also be used. | ||
7 | user_handle_value* | Value of user_handle_type.If not relevant, "DEFAULT" can also be used. | a@b.com/DEFAULT | |
8 | location | Specifies the geo location of the device that initiated the request. | ||
9 | transmission_datetime* | Time in System Milli Seconds at which the request was initiated by the client. | 155325508029 | |
10 | run_mode* | TRIAL - Indicates need for mock run of the transaction. No transaction posting will happen. REAL - Indicates the actual transaction posting request. If not relevant, "DEFAULT" can also be used. | DEFAULT/TRIAL/REAL/RETRY | |
11 | client_ip | IP Address of the client device.In case not applicable, an EMPTY ( "") string can be passed. | ||
12 | operation_mode* | The way in which the request is executed. SELF - aadhaar holder doing the transaction. ASSISTED - where auth/ekyc is done in operator assisted mode. SYSTEM- where transaction is automated by system (batch processes). If not relevant, "DEFAULT" can also be used. | DEFAULT/SELF/ASSISTED/SYSTEM | |
13 | channel_version* | The version of the channel application like ANDROID_SDK. | 3.1.7 | |
14 | function_code* | DEFAULT: Indicates default behavior for this API | DEFAULT | |
15 | function_sub_code | DEFAULT: Indicates default behavior for this API | DEFAULT | |
16 | request_id* | Client generated Id for referencing the transaction uniquely. | requestid123 | |
17 | hash* | Hash to be calculated by the client to verify the integrity of the request. Please refer APPENDIX B to see how to generate the hash. | ||
18 | api_key* | api_key shared with the client during onboarding. | samplekey123 |
Appendix B : Error Codes
Code | Scenario | Message |
---|---|---|
380024 | General | user_id is mandatory |
380025 | General | hash is mandatory |
380026 | General | api_key is mandatory |
380048 | General | Invalid api_key or client_code |
380048 | General | Invalid api_key or client_code |
380091 | General | Hash validation failed |
380076 | General | No such user-id exists |
333 | General | Unexpected Error Occurred |
410003 | verifyUserIdDoc | Invalid name. |
410004 | verifyUserIdDoc | Invalid DOB Format. Please use dd/MM/YYYY format. |
410005 | verifyUserIdDoc | Invalid PAN format. |
410006 | verifyUserIdDoc | Data extraction from the PAN card was unsuccessful. |
410008 | verifyUserIdDoc | Name is mandatory. |
410009 | verifyUserIdDoc | Date of Birth is mandatory. |
410010 | verifyUserIdDoc | PAN Number is mandatory. |
410011 | verifyUserIdDoc | Document is mandatory. |
410012 | verifyUserIdDoc | Operation Code Not Valid. |
410013 | verifyUserIdDoc | Epic number is mandatory |
410014 | verifyUserIdDoc | Epic number format is invalid. |
Appendix C: Input Image Specification
For better results, it is recommended to ensure that Input Image complies to the following specifications :
Images should not be blurry.
Images with skew of more than 45 degrees is not a good input.
Out of focus images are not recommended.
Damaged images are not recommended.
Images with some signature or stamp over text area or fingers covering images or MRZ in passports (not standard one) may not yield better results.
Recommended Image formats include JPEG, PNG.
For better results, it is recommended to have image size < 500 KB.
Images with less than 480 pixel width (horizontal shaped ids) or 480 pixel height (vertical shaped ids - voter). We don’t actually check for pixel size but should work for < 480 in cases where the image quality is good.
Images with bad exposure (very dark or very bright) will not yield good results.
300 DPI for best results
Appendix D: Important things to consider before uploading images
Place the camera right above the document and not sideways.
Take image of the document in front of a white background.
Make sure there is sufficient lighting in the room and no white light on the document while taking its photo.
Try to get a stable photo and not a shaky one.
Appendix E: Hash Generation
It is essential that there is a definitive protocol to verify the integrity of all the communication between Khosla Labs and Client.Hence for every request coming to KL Platform, client have to supply a hash which we will use as the first step of verification.
In return, all responses will also contain hash supplied by KL. You should not entertain any request at your callbackUrl if the hash does not match.
- Hash should be calculated using the below method : hash=SHA256(Hash-Sequence)
Hash Sequence is specified as follows(no space, no commas, no single/double quotes). Hash sequence is defined for each request and response.
- verifyGSTIN Request:
client_code
|request_id
|api_key
|salt
|gstin
Example(for _init request), If your
client_code=INFO9378,
api_key=abc,
requestId=abcd,
salt=abc,
gstin=29AAECK9415C1ZJ
then
Hash-Sequence=INFO9378|abcd|abc|abc|29AAECK9415C1ZJ
hash =SHA-256(Hash-Sequence)
hash=e3f10f1787428a75e5f0c9331c3bacde36df54e855744a3ccc1f0ff9c7b518fe
For validation:
- Receiving end should calculate hash based on request parameters and match it against the received hash.
- If receivedHash=calculatedHash, then only you should proceed with your application logic.
- api_key and salt are the key parameters here. It is known only to the client and Khosla Labs.
- One api_key is mapped to one salt. This allows us to have multiple salts active at a time.
- api_key and hash need to be passed in each API call. Salt is never transmitted in any API call.
sample link for calculating hash : https://www.tools4noobs.com/online_tools/hash/
Appendix F: FAQ
Q1. What should be value of stan?
Ans: stan should be mandatorily passed for every transaction. It should be unique for unique transaction.
Q2: What should be function_code?
Ans: Its value should mandatorily be passed as per the documentation eg VERIFY_PAN/VERIFY_AADHAAR etc.
Q3: What should be function_sub_code?
Ans: It should be mandatorily passed as per documentation. Its value can be DATA/DOCUMENT/NUMBER (in cse of PAN card) and DATA (in case of Aadhaar card).
Q4: What should the request body if I want to verify PAN details("function_sub_code": "DATA")?
Ans: Below is the requestbody for verifiction of PAN data-
Request Payload
{
"headers": // Please refer Appendix A for details.
{
"client_code": "<your_client_code>",
"sub_client_code": "<your_sub_client_code>",
"channel_code": "",
"channel_version": "",
"stan": "<a_unique_integer>",
"client_ip": "",
"transmission_datetime": "",
"operation_mode": "SELF",
"run_mode": "",
"actor_type": "",
"user_handle_type": "",
"user_handle_value": "",
"location": "NA",
"function_code": "VERIFY_PAN",
"function_sub_code": "DATA"
},
"request": {
"pan_details": {
"pan_number": "",
"name": "",
"dob": "dd/mm/yyyy",
"pan_type" : ""
},
"consent": "",
"consent_message": ""
}
}
Q5: How can I verify PAN details by uplaoding PAN image ("function_sub_code": "DOCUMENT")?
Ans: Below is the requestbody for verifiction using PAN image-
Request Payload
{
"headers": // Please refer Appendix A for details.
{
"client_code": "<your_client_code>",
"sub_client_code": "<your_sub_client_code>",
"channel_code": "",
"channel_version": "",
"stan": "<a_unique_integer>",
"client_ip": "",
"transmission_datetime": "",
"operation_mode": "SELF",
"run_mode": "",
"actor_type": "",
"user_handle_type": "",
"user_handle_value": "",
"location": "NA",
"function_code": "VERIFY_PAN",
"function_sub_code": "DOCUMENT"
},
"request": {
"pan_details": {
"document": "" // Base64 string of PAN card image
},
"consent": "",
"consent_message": ""
}
}
Q6: How can I fetch the PAN data linked with given PAN number?
Ans: Below is the requestbody for verifiction using PAN number-
Request Payload
{
"headers": // Please refer Appendix A for details.
{
"client_code": "<your_client_code>",
"sub_client_code": "<your_sub_client_code>",
"channel_code": "",
"channel_version": "",
"stan": "<a_unique_integer>",
"client_ip": "",
"transmission_datetime": "",
"operation_mode": "SELF",
"run_mode": "",
"actor_type": "",
"user_handle_type": "",
"user_handle_value": "",
"location": "NA",
"function_code": "VERIFY_PAN",
"function_sub_code": "NUMBER"
},
"request": {
"pan_details": {
"pan_number": "",
"pan_type" : "" // Please refer Table 1 for types of PANs
},
"consent": "",
"consent_message": ""
}
}
Q7: Can I get Aadhaar data linked with given Aadhaar number?
Ans: No, veri5 platform can verify Aadhaar number and response will be as below- { "verified_by":"UIDAI Portal", "response_status":{ "code":"", "message":"", "status":"<< SUCCESS | FAIL >>" }, "Verified_data": { “Age_band” : “ “, “Gender” : “ “, “State” : “”, “Mobile_number” : “ “ } "Verification_method":"", // VERIFY_AADHAAR_DATA "stan":"", "verification_status":"<< SUCCESS | FAIL >>", "Verified_using":"Database Check", “verification_code”: “” }