CKYC Search and Download API

Module ID

module_ind_ckyc_search

info

What do these terms mean?

Module Description

CKYC search and download API can be used to check if the user details are present on the CKYC (CERSAI) repository. If details are present, those documents can be used to do perform full-KYC of the user.

CKYC Search and download can be performed using one of the IDs mentioned below:

• PAN
• Aadhaar
• Passport
• Voter ID
• Driving License
• CKYC number

Pre-requisites:

• Financial institutions should whitelist HyperVerge static IP in CKYC portal to allow HyperVerge to access CERSAI repository on behalf of FI.
• Financial institutions should share the privateKey shared with CERSAI and the fiCode with HyperVerge.
  • (Please Note - FI Code will be different for Live and Testbed Portal. HyperVerge only needs Live Fi Code.)
  • Refer API to map keys section to understand how to map the keys with HyperVerge

Module Inputs

**idType: **

• The ID Type used for fetching the CKYC records. Possible values are one among following:
  • Passport = A
  • Voter_id = B
  • Pan = C
  • Driving_license = D
  • Aadhaar = E
  • ckyc_identifier = Z

**idNo: **

• id number based on id type. Refer below table(Id Number format) to understand the format.

**mobileNo: **

• mobile number (optional)

**dob: **

• date of birth in dd-mm-yyyy format (optional) (recommended)

**pincode: **

• pincode (optional)

info

Request must have either of mobileNo, dob or (pincode +dob) present in its body

idNum Format

Id Type	ID Number
Pan (C)	10 digit PAN number of that customer
Aadhaar (E)	A combination of 4 details. '4 digits of AADHAAR', 'Name as on AADHAAR', 'Date of birth as on AADHAAR in dd-mm-yyyy format' and Gender: Male 'M', Female 'F' or Other 'T'. Example: 9906
Passport (A)	A valid passport number of the customer
Voter_id (B)	A valid voter id number of the customer
Driving_license (D)	A valid driving licence number of the customer
CKYC_identifier (Z)	CKYC number corresponding to serial number in request file

Module Configurations

No configurations are supported currently

Module Outputs

The following information is returned in the Results API

Success Scenario

{
    "module": "KYC Verification - Cersai",
    "moduleId": "module_ind_ckyc_search_api",
    "<imageCode>ImageUrl": "" // Signed Temporary URL of the file received from CERSAI
    "apiResponse": {
        "status": "success",
        "statusCode": "200",
        "result": {
            "constituitonType": "Individual",
            "accountType": "normal",
            "ckycNo": "XXXXXXXXX",
            "preFix": "Mr",
            "firstName": "firstName",
            "middleName": "middleName",
            "lastName": "lastName",
            "fullName": "Mr firstName middleName lastName",
            "fatherOrSpouse": "father",
            "fatherPrefix": "Mr",
            "fatherFname": "fatherFirstName",
            "fatherMname": "fatherMiddleName",
            "fatherLname": "fatherLastName",
            "fatherFullName": "Mr fatherFirstName  fatherMiddleName fatherLastName",
            "motherPrefix": "Mrs",
            "motherFname": "motherFirstName",
            "motherMname": "motherMiddleName",
            "motherLname": "motherLastName",
            "motherFullName": "Mrs motherFirstName  motherMiddleName motherLastName",
            "gender": "M/F",
            "dob": "dd-mm-yyyy",
            "age": "",
            "address1": "address line 1",
            "address2": "address line 2",
            "address3": "address line 3",
            "city": "AMBARNATH WEST",
            "district": "Thane",
            "state": "MH",
            "country": "IN",
            "pincode": "421505",
            "permAndCorresAddSame": "Y",
            "corresAddress1": "correspondence address line 1",
            "corresAddress2": "correspondence address line 2",
            "corresAddress3": "correspondence address line 3",
            "corresCity": "correspondence city",
            "corresDist": "correspondence district",
            "corresState": "correspondence state",
            "corresCountry": "correspondence country",
            "corresPin": "correspondence pincode",
            "resiStdCode": "+91",
            "resiTelNo": "8888888888",
            "mobileCode": "+91",
            "mobileNumber": "8888888888",
            "email": "test@test.com",
            "decDate": "dd-mm-yyyy",
            "decPlace": "SELF",
            "kycDate": "********",
            "updatedDate": "",
            "idList": "",
            "DocSub": "01",
            "kycName": "********",
            "kycDesignation": "********",
            "kycBranch": "********",
            "kycEmpCode": "********",
            "numIdentity": "3",
            "numRelated": "0",
            "numImages": "5",
            "aadhaar": "XXXXXXXX1234",
            "pan": "ABCDE1234F",
            "voterId": "",
            "passport": "",
            "drivingLicense": "",
            "nregaJobCard": "",
            "nationalPopulationReg": "",
            "imageDetails": [
                {
                    "code": "04", // "03" = "pan", "04" = "aadhaar", "05" = "passport", "06" = "driving_license", "07" = "voterid", "36" = "ekyc_authentication"
                    "type": "", // pdf/jpg/tif/png,
                    "imageUrl": "<temp signed URL(deprecated, will be removed soon. Refer to <imageCode>ImageUrl)>"
                }
            ]
        }
    },
    "attempts": "1",
    "previousAttempts": []
}

Understanding the Response

Key	Description	Values Possible
moduleId	ID of the module	module_ind_ckyc_search_api
module	Name of the module that was setup in your workflow config	KYC Verification - Cersai
<imageCode>ImageUrl	Temporary Signed URL of the images returned by CERSAI. imageCode will be the numeric image code mentioned within the imageDetails array of the apiResponse. More details on the same below	String
apiResponse	The API results provided by HyperVerge's backend. If there were multiple attempts made by the user, this key will contain the latest attempt	JSON
previousAttempts	If there were multiple attempts made by the users, this array will contain the older attempts, sorted from latest to oldest	JSON Array

Understanding apiResponse

Key	Description	Values Possible
result	Contains the fields returned by Cersai as part of Search and Download API	JSON
imageDetails	Array of objects containing the imageURL along with the corresponding code returned by CERAI. The imageUrl within imageDetails has been deprecated and will be removed soon	JSON

Understanding imageCode and imageCodeImageUrl

CERSAI returns an image/file code along with each file that's saved in its DB. Following is the mapping of the same

imageCode	Description	Key Name for imageCodeImageUrl
02	Photograph	02ImageUrl
03	PAN	03ImageUrl
04	Aadhaar	04ImageUrl
05	Passport	05ImageUrl
06	Driving License	06ImageUrl
07	VoterId	07ImageUrl
09	Signature	09ImageUrl
36	eKYC Auth	36ImageUrl
98	Others	98ImageUrl

Failure Scenarios

Below is the response in Results API for a typical error scenario.

{
    "module": "KYC Verification - Cersai",
    "moduleId": "module_ind_ckyc_search_api",
    "apiResponse": {
        "status": "failure",
        "statusCode": "400",
        "error": {
            "code": "ER_REQ_VALIDATE",
            "message": "idNo should not be null or undefined"
        }
    },
    "attempts": "1",
    "previousAttempts": []
}

List of Errors Possible

Below are all the errors possible in this module. The 'statusCode' is present under apiResponse

StatusCode	ErrorCode	Summary	Description
400	ER_REQ_VALIDATE	Bad Request	The required request parameters are either not sent or are sent in incorrect format. Request body needs to be verified
404	ER_CKYC_SEARCH_AND_DOWNLOAD	CKYC Record Not Found	The record associated with the API input was not found in the CERSAI Database
429	-	Rate limit error	When the number of requests per minute has crossed the set limit for your credentials
5xx	-	Server Error	Please reachout to HyperVerge