NAV Navbar
cURL JSON CodeSnippet

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.

The list of core APIs include :

2. Prerequisite

For a client to get access to APIs, client registration is mandatory. Khoslalabs provide two environments :

The client has to obtain the following values for the following params :

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 number of the user against Income Tax Database and also provide the name of the PAN Holder.

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": "<<NUMBER>>"
    },
    "request": {
            "pan_details": {
            "pan_number": "",
            "pan_type" : "" // Please refer Table 1 below for types of PANs
            },
    "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.

{
    "verified_by": "Income tax Database",
    "response_status": {
        "code": "000",
        "message": "",// Refer to Table 2 below for details.
        "status": "SUCCESS"
    },
    "verified_data": "{\"name\":\"\"}",
    "verification_method": "VERIFY_PAN_NUMBER",
    "stan": "",
    "verification_status": "<< SUCCESS | FAIL >>",
    "verification_code": "000",
    "verified_using": "Database check"
}

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 400103 Invalid PAN
3 FAIL 410007 Verification Service Not Available.
4 FAIL 400099 Unknown Error Occurred.Please try after some time.

3.2 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 :

Method : POST

Url : https://hostname/service/api/1.0/verifyUserIdDoc

### 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": "",
            "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.2.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 3 : 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.3 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://hostname/verification-service/api/bankVerification Authorization :Basic Auth Header :X-IBM-Client-Id :X-IBM-Client-Secret

### 3.3.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.3.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 4 : 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.4 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.4.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.4.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.

Frequently Asked Questions (FAQs) :

Q1. What should be the hostname in url for the different environments used ?

Ans: We use 2 environments sandbox and production environment. In sandbox environment, hostname : sandbox.veri5digital.com In production environment, hostname : prod.veri5digital.com

Q2. What to do if error says “transaction limit exceeded” ?

Ans: For sandbox environment the client gets up-to 20 transactions for free, to exceed the limit of free transactions please contact at hello@veri5digital.com.

Q3. What to do if error says “Duplicate request found” ?

Ans: Make sure to enter a unique Stan for every request you make.

Q4. What should be the ‘function_code’ VerifyUserIdDoc [PAN] API?

Ans: For PAN API ‘function_code’ should be “VERIFY_PAN"

Q5. What should be the ‘function_sub_code’ for VerifyUserIdDoc [PAN] API ?

Ans: function_sub_code’ should be “NUMBER”.

Q6. What should be the ‘function_code’ and ‘function_sub_code’ for AADHAAR API?

Ans: For AADHAAR API ‘function_code’ should be “VERIFY_AADHAAR" and ‘function_sub_code’ should be “DATA”.

Q7. What should be the ‘function_code’ and ‘function_sub_code’ for verifyGSTIN (GST Details) API?

Ans: Both should have the value “DEFAULT”.

Q8. What to do if error says “502 Bad Gateway error” ?

Ans: Check whether your URL is correct or not. If the error still persists feel free to contact to Veri5digital team.

Q9. What to do if I am getting an error to upload any base 64 encoded image in Verification API’s?

Ans: Make sure image size is less than 500 KB.

Q10. What should be the value of Authorization in bankVerfication API?

Ans: Authorization should have the value ‘Basic’.

Q11. What should be the value of Auth Header in bankVerfication API?

Ans: It should have the value ‘:X-IBM-Client-Id :X-IBM-Client-Secret’.

Q12. How to calculate hash for GSTIN verify API ?

Ans: Hash is calculated using SHA256. Format = client_code|request_id|api_key|salt|gstin Make sure you do not enter any spaces in between. To calculate hash you can use this link : https://xorbin.com/tools/sha256-hash-calculator

Q13. What should be value of stan?

Ans: Stan should be mandatorily passed for every transaction. It should be unique for unique transaction.

Q14. What should be function_code?

Ans: Its value should mandatorily be passed as per the documentation eg VERIFY_PAN/VERIFY_AADHAAR etc.

Q15. What should be function_sub_code?

Ans: It should be mandatorily passed as per documentation. Its value can be DATA/DOCUMENT/NUMBER (in case of PAN card) and DATA (in case of Aadhaar card).

Q16. 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”: “” }

Q17. What should be the value of request_id ?

Ans: request_id is a unique value for every transaction made. It is generated for referencing the transaction uniquely.

Q18. What to do if error says “333 Unexpected error” ?

Ans: Check if you are entering the correct credentials. If the error still persists contact at hello@veri5digital.com

Q19. Q13. How to convert an image into base 64 string ?

Ans: Before encoding make sure your image size is <500 KB. Use any online image to base64 encoder, you will get a base 64 string. Pass that string value in document. You can use any online base64 image encoder like : https://codebeautify.org/base64-to-image-converter

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. EMAIL
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 :

Appendix D: Important things to consider before uploading images

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 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
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:

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”: “” }