CKYC PreUpload API

The following document highlights the details of the CKYC PreUpload API.

API Description

Objective

The CKYC PreUpload API is a prerequisite for the CKYC Upload API. It enables HyperVerge to connect with CERSAI on behalf of your organization by setting up required configurations and webhook endpoints.

Input	Output
Organization details, CKYC credentials, webhook URL, and SFTP host configuration	Confirmation that the configuration was successfully created or updated

API URL

The following URLs are available for CKYC PreUpload API calls in testbed and production environments:

Testbed URL

https://ind-ckyc.dev.hyperverge.co/api/v1/config/upload

Production URL

https://ind-ckyc.hyperverge.co/api/v1/config/upload

API Endpoint

config/upload

Overview

The CKYC PreUpload API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format.

Methods - POST / PUT

POST vs PUT

Use POST to create a new CKYC configuration, and PUT to update an existing one.

In PUT requests, all fields are optional. Only the fields that require updates need to be included. For POST requests, refer to the Inputs table for mandatory fields.

Authentication

You need a unique pair of application ID (appId) and application key (appKey) from HyperVerge to verify your identity for accessing the CKYC PreUpload API.

Headers

Include the following headers in every request for successful authentication and tracking:

Header	Mandatory / Optional	Description	Input Format
content-type	Mandatory	This parameter defines the media type for the request payload	application/json
appId	Mandatory	The application ID shared by HyperVerge. You can find the details in the dashboard's credentials tab	This should be a unique value
appKey	Mandatory	The application key shared by HyperVerge. You can find the details in the dashboard's credentials tab	This should be a unique value
transactionId	Mandatory	A unique identifier for tracking a user journey	This should be both unique and easily associated with the user's journey in your application(s)

Inputs

Provide the following request body parameters based on your configuration requirements:

Parameter	Mandatory / Optional	Type	Description	Input Format	Default Value
organisationName	Mandatory	string	Name of the organization as registered in CKYC	Not Applicable	Not Applicable
fiCode	Mandatory	string	FI code assigned by CKYC	Length must be 1–7 characters	Not Applicable
regionCode	Mandatory	string	Unique code of the geographical region registered in CKYC	Length must be 1–10 characters	Not Applicable
webhookUrl	Mandatory	string	The URL to receive webhooks containing final CKYC upload responses from CERSAI	Not Applicable	Not Applicable
username	Mandatory	string	'Maker' username for CKYC portal	Not Applicable	Not Applicable
password	Mandatory	string	'Maker' password for CKYC portal	Not Applicable	Not Applicable
host	Mandatory	string	IP address provided by HyperVerge for CKYC uploads; separate IPs are used for Testbed and Production environments	Not Applicable	Not Applicable
retentionDays	Optional	string	Number of days for which upload data should be retained. It is recommended to set retention of 28 days to avoid losing any upload records.	Allowed values: 1, 14, 28, 45, 90, 180	14
returnCKYCRefIdSeparately	Optional	string	If enabled, a separate field ckyc_ref_id will be included in the webhook response for short and long confirmed match cases	yes or no	Not Applicable
email	Optional	string	Email address to which SFTP connection failure notifications will be sent	Not Applicable	Not Applicable

Request

The following cURL samples show how to call the CKYC PreUpload API in both environments:

Testbed

POST Request

curl --location --request POST 'https://ind-ckyc.dev.hyperverge.co/api/v1/config/upload' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_App_ID>' \
--header 'appKey: <Enter_the_App_Key>' \
--header 'transactionId: <Enter_the_Transaction_ID>' \
--data '{
		"organisationName": "<Enter_the_Organisation_Name>",
		"fiCode": "<Enter_the_FI_Code>",
		"regionCode": "<Enter_the_Region_Code>",
		"webhookUrl": "<Enter_the_URL>",
		"username": "<Enter_the_username>",
		"password": "<Enter_the_password>",
		"host": "<Enter_the_IP_Address>",
		"retentionDays" : "<Enter_the_number_of_retention_days>",
		"returnCKYCRefIdSeparately" : "<yes/no>",
		"email" : "<Enter_the_Email_Address>"
}'

PUT Request

curl --location --request PUT 'https://ind-ckyc.dev.hyperverge.co/api/v1/config/upload' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_App_ID>' \
--header 'appKey: <Enter_the_App_Key>' \
--header 'transactionId: <Enter_the_Transaction_ID>' \
--data '{
		"organisationName": "<Enter_the_Organisation_Name>",
		"fiCode": "<Enter_the_FI_Code>",
		"regionCode": "<Enter_the_Region_Code>",
		"webhookUrl": "<Enter_the_URL>",
		"username": "<Enter_the_username>",
		"password": "<Enter_the_password>",
		"host": "<Enter_the_IP_Address>",
		"retentionDays" : "<Enter_the_number_of_retention_days>",
		"returnCKYCRefIdSeparately" : "<yes/no>",
		"email" : "<Enter_the_Email_Address>"
}'

Production

POST Request

curl --location --request POST 'https://ind-ckyc.hyperverge.co/api/v1/config/upload' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_App_ID>' \
--header 'appKey: <Enter_the_App_Key>' \
--header 'transactionId: <Enter_the_Transaction_ID>' \
--data '{
		"organisationName": "<Enter_the_Organisation_Name>",
		"fiCode": "<Enter_the_FI_Code>",
		"regionCode": "<Enter_the_Region_Code>",
		"webhookUrl": "<Enter_the_URL>",
		"username": "<Enter_the_username>",
		"password": "<Enter_the_password>",
		"host": "<Enter_the_IP_Address>",
		"retentionDays" : "<Enter_the_number_of_retention_days>",
		"returnCKYCRefIdSeparately" : "<yes/no>",
		"email" : "<Enter_the_Email_Address>"
}'

PUT Request

curl --location --request PUT 'https://ind-ckyc.hyperverge.co/api/v1/config/upload' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_App_ID>' \
--header 'appKey: <Enter_the_App_Key>' \
--header 'transactionId: <Enter_the_Transaction_ID>' \
--data '{
		"organisationName": "<Enter_the_Organisation_Name>",
		"fiCode": "<Enter_the_FI_Code>",
		"regionCode": "<Enter_the_Region_Code>",
		"webhookUrl": "<Enter_the_URL>",
		"username": "<Enter_the_username>",
		"password": "<Enter_the_password>",
		"host": "<Enter_the_IP_Address>",
		"retentionDays" : "<Enter_the_number_of_retention_days>",
		"returnCKYCRefIdSeparately" : "<yes/no>",
		"email" : "<Enter_the_Email_Address>"
}'

Success Response

The following example shows a successful response returned by the CKYC PreUpload API:

{
  "status": "success",
  "statusCode": "200",
  "result": true
}

Success Response Details

The following table outlines the details of the success response from the CKYC PreUpload API:

Parameter	Type	Description
status	string	The status of the request. Returns success on a successful call.
statusCode	string	The HTTP status code for the response.
result	boolean	Returns true when the configuration was successfully created or updated.

Error Responses

The following examples show common error responses returned by the CKYC PreUpload API for invalid input scenarios:

Invalid FI Code

{
  "status": "failure",
  "statusCode": "400",
  "error": {
    "code": "ER_REQ_VALIDATE",
    "message": "fiCode should not be null or undefined"
  },
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Invalid Region Code

{
  "status": "failure",
  "statusCode": "400",
  "error": {
    "code": "ER_REQ_VALIDATE",
    "message": "regionCode should not be null or undefined"
  },
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Invalid Webhook URL

{
  "status": "failure",
  "statusCode": "400",
  "error": {
    "code": "ER_REQ_VALIDATE",
    "message": "webhookUrl should not be empty"
  },
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Invalid Username

{
  "status": "failure",
  "statusCode": "400",
  "error": {
    "code": "ER_REQ_VALIDATE",
    "message": "username should not be empty"
  },
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Invalid Password

{
  "status": "failure",
  "statusCode": "400",
  "error": {
    "code": "ER_REQ_VALIDATE",
    "message": "password should not be empty"
  },
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Invalid SFTP Host

{
  "status": "failure",
  "statusCode": "400",
  "error": {
    "code": "ER_REQ_VALIDATE",
    "message": "host should not be empty"
  },
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Missing/Invalid Credentials

{
  "status": "failure",
  "statusCode": "401",
  "error": {
    "code": "ER_AUTH",
    "message": "Missing/Invalid credentials"
  }
}

Internal Server Error

{
  "status": "failure",
  "statusCode": "500",
  "error": {
    "code": "ER_SERVER",
    "message": "internal server error"
  },
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Error Response Details

A failure or error response contains a failure status with a relevant status code and error message. The following table lists the error responses for the CKYC PreUpload API:

Status Code	Error Message	Error Description	Error Resolution
400	fiCode should not be null or undefined	The FI code is missing or not provided in the request	Provide a valid fiCode value in the request body
400	regionCode should not be null or undefined	The region code is missing or not provided in the request	Provide a valid regionCode value in the request body
400	webhookUrl should not be empty	The webhook URL is missing or empty in the request	Provide a valid webhookUrl value in the request body
400	username should not be empty	The CKYC portal username is missing or empty in the request	Provide a valid username value in the request body
400	password should not be empty	The CKYC portal password is missing or empty in the request	Provide a valid password value in the request body
400	host should not be empty	The SFTP host address is missing or empty in the request	Provide the IP address supplied by HyperVerge in the host field
401	Missing/Invalid credentials	The request is missing the mandatory appId and appKey combination or has invalid values	Verify and provide valid credentials
500	internal server error	Kindly check the request headers or contact the HyperVerge team for resolution	Check the request headers or contact the HyperVerge team for resolution