Skip to main content

CKYC Validation

Module ID​

Name of the ModuleDocuments Supported
module_ckyc_validationCKYC record (XML file, a selfie image and officially valid documents)

Description​

This module extracts an end user's KYC details from the CKYC database and evaluates their identity.

The CKYC data extraction has the following two major steps:

  1. Search and download the CKYC record with PAN and Aadhaar inputs.
  2. Extract the end user's KYC details from the CKYC record to help you to evaluate the user's identity.

HyperVerge CKYC extractor API is used to act on part 2. The extractor API verifies the user's personally identifiable information (PII) against the data from the PDF files and classifies the response into three buckets based on an internal scoring mechanism summarized in the following sections.

  1. Approve
  2. Review
  3. Reject

Each CKYC record consists of user information in an XML file, selfie (photograph) and officially valid documents such as Aadhaar, voter ID, passport and driving licence in a PDF format. HyperVerge accepts any four of the officially valid documents types stated here. All other documents such as a rent agreement will be discarded.

You should parse the XML and send the data to the extractor API along with the selfie and the officially valid documents. The photograph of the applicant is matched against the photographs present in each of the documents in the request.

Module Inputs​

The following table provides the details of the parameter required for the module:

Parameter Mandatory or Optional Description
sample Mandatory The sample description.
action- approve, reject, manual_review
  • approve - Minimum weighted score is less than 2.
  • reject - Minimum weighted score is greater than 3.
  • manual_review - Minimum weighted score is equal to. For more details on the score calculation refer to Weightage table.
validPOA- passport, driving_license, voter_id, aadhaar Lists all the documents that have succeeded address validation.
validPOI- passport, driving_license, voter_id, aadhaar Lists all the documents that have succeeded identity validation such as name match and face match.
invalidDocs- Contains a map of the document with the mismatch codes. Valid documents include Aadhaar, passport, driving_license and voter_id.
details

Object document, Object field, matchFound: boolean, score: number.
  • Contains a map of document with individual field status and the match score. Valid documents include aadhaar, passport, driving_license and voter_id.
  • Valid Field names include first_name, middle_name, last_name, address1, address2, address3, city, district, state, country, pincode, dob, voter_id, aadhaar, passport, driving_license
  • Contains an array of URLs with Aadhaar
masked_aadhaar_url String[] images masked. First 8 digits will be masked. Valid for 15 mins.

Module Configurations​

This module does not support any additional configurations.

Module Outputs​

The following section provides the sample and the corresponding details of the various responses you can expect from the module:

A success response indicates that the validation process has completed. This includes when all the documents are valid, all documents are invalid or some of the documents has no face match.
You will receive a success response in a format similar to the following sample code if the API request is correct. The sample responses for the different types of success scenarios are provided further below. 
   {
   "status": "success",
   "statusCode": 200,
   "result": {
      "action": String,
      "validPOA": String[],
      "validPOI": String[],
      "invalidDocs": Object<document,error[]>,
      "details": Object<document, Object<field,
      {
         matchFound:boolean, 
         score: number
      }>>,
      "masked_aadhaar_url": String[]
   }
}

Samples of Success Responses

When all fields are validated and the total score is less than 2, we approve the record.
 {
 "status":"success",
 "statusCode":"200",
 "result":{
    "action":"approve",
    "validPOA":[
       "aadhaar"
    ],
    "validPOI":[
       "aadhaar"
    ],
    "invalidDocs":{
       
    },
    "details":{
       "aadhaar":{
          "first_name":{
             "matchFound":true,
             "score":90
          },
          "last_name":{
             "matchFound":true,
             "score":100
          },
          "address1":{
             "matchFound":true,
             "score":95
          },
          "address2":{
             "matchFound":true,
             "score":96
          },
          "address3":{
             "matchFound":true,
             "score":100
          },
          "city":{
             "matchFound":true,
             "score":100
          },
          "dob":{
             "matchFound":true,
             "score":100
          },
          "aadhaar":{
             "matchFound":true,
             "score":100
          },
          "faceMatch":{
             "matchFound":true,
             "score":90
          },
       }
    },
    "aadhaar_type":"STANDARD"
 }
}

Success Response Details

You have to create a webhook to receive the response from CERSAI.


FieldDescription
short_rejectCERSAI rejects a few cases immediately (short response) owing to basic errors. Such cases are categorised under the short_reject type.
short_confirmed_matchCERSAI rejects (short response) a few cases which are already present in Cersai database. These cases are categorised as the short_confirmed type. You will also receive the CKYC number of the matched record.
insufficient_balanceYour CERSAI wallet balance is not sufficient for the upload.
long_rejectBesides the immediate short response, CERSAI also provides a long response with more details after 1-2 days of upload. Such cases are categorised under the long_reject type.
probable_matchIn the long response, Cersai will match all the data you have uploaded with its own database and return the possible match where probability of matching is higher. You will also get CKYC number of the matched record.
long_confirmed_matchFor the probable match cases where the probability is 100%, CERSAI will reject such cases stating a confirmed match. You will also receive CKYC number of the matched record.
successThe record has been uploaded successfully. You receive the CKYC number of the uploaded record.

Error Response Details

Code property from error objectCategoryDescription
ER_BAD_DOCBad documentDocument is not readable
ER_FACE_NO_MATCHFace mismatchFace Match not found
ER_FACE_MISSINGFace missing
ER_NAMEField mismatchThe name is a mismatch.
ER _ADDRESSThe address is a mismatch.
ER_DOBThe date of birth is a mismatch.
ER_IDThe ID is a mismatch.
ER_PINCODEThe pin code does not match.
ER_SERVERFile size exceeds the limitFile size exceeds 6MB.
ER_SERVERDocument length exceeds the limitThe document exceeds 5 pages.
Status CodeError MessageDescription
401Missing/Invalid credentials You have either missed to include the appid and appkey credentials in the request header or you have provided incorrect values.
400first_name should not be null or undefined You have missed to send the mandatory parameters in the request.
400Selfie image not sent as part of the payload You have missed to send the selfie image in the request.
400pages exceeded the supported length of 5 The number of pages in the request document exceeds 5 pages.
413File too large This status code is returned for requests with a file size exceeding 6MB.
5xxInternal server errorThis status code is returned for server errors. Kindly reach out to HyperVerge.
The following are other sample error responses for your reference.
{
  "status": "fail",
  "statusCode": "400",
  "error": {
      "code": "ER_REQ_VALIDATE",
      "message": "first_name should not be null or undefined"
   }
}
Last updated on
Was this helpful?
ON THIS PAGE
Ask AIBeta
Hi! How can I help?
Ask me anything about HyperVerge products, APIs, and SDKs.
Try asking: