CKYC OTP Generation API

Endpoint Overview

POST /api/v1/ckyc-v2/generate-otp

Description

The CKYC OTP Generation API is a secure endpoint that initiates the verification process for Central KYC (CKYC) document downloads by sending a One-Time Password (OTP) to the user's registered mobile number. This API serves as the first step in the two-factor authentication process for accessing CKYC records, ensuring that only authorized users can download sensitive KYC documents.

The API validates the provided client ID and mobile number, then generates and sends an OTP via SMS to the specified mobile number. Upon successful OTP dispatch, it returns a new download-specific client ID that must be used in subsequent verification steps. This workflow ensures secure access to CKYC data while maintaining compliance with regulatory requirements for identity verification.

Key Benefits

Enhanced Security: Two-factor authentication with mobile OTP verification

Regulatory Compliance: Meets CKYC regulatory requirements for secure document access

Seamless Integration: Simple REST API design for easy implementation

Real-time Verification: Instant OTP generation and delivery confirmation

Use Cases

Financial Services

Fintech & NBFCs

Enterprise & B2B

Digital Banking Onboarding: Verify customer identity during account opening process

Loan Application Processing: Authenticate applicants before accessing CKYC records

Investment Account Setup: Validate investor credentials for KYC compliance

Credit Card Issuance: Confirm applicant identity before card approval

Technical Implementation

Authentication

All API requests require authentication using a JWT Bearer token. Authentication follows these steps:

Obtain API Credentials: Register with Surepass to receive your API key.

Generate JWT Token: Use your API key to generate a JWT token.

Include in Requests: Add the token to the Authorization header as Bearer TOKEN.

Different authentication tokens are used for sandbox and production environments:

Sandbox: https://sandbox.surepass.io

Production: https://kyc-api.surepass.io

Request Parameters

Request Headers

Header	Required	Description
Authorization	Yes	JWT Bearer token for API authentication
Content-Type	Yes	Must be set to `application/json`

Request Body

Parameter	Type	Required	Description
client_id	String	Yes	Unique identifier for the CKYC request session
mobile_number	String	Yes	10-digit mobile number registered with CKYC (without country code)

Example Request

{
  "client_id": "ckyc_EklilHGggwPXenefi",
  "mobile_number": "8939809876"
}

Process Response

Response Parameters

Parameter	Type	Description
data	Object	Container for response data
data.client_id	String	New client ID to be used for OTP verification
data.otp_sent	Boolean	Indicates whether OTP was successfully sent
status_code	Integer	HTTP status code (200 for success)
success	Boolean	Overall operation success indicator
message	String	Human-readable response message
message_code	String	Machine-readable message identifier

Example Successful Response

{
    "data": {
        "client_id": "ckyc_download_nNfWARdhysddWFiXddXF",
        "otp_sent": true
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Invalid Mobile Number

Client ID Not Found

Mobile Number Not Matched with Ckyc

Server Error

{

    "status_code": 422,
    "success": false,
    "message": "Mobile Number not matched with CKYC.",
    "message_code": "mobile_number_not_matched"
}

e /ckyc-v2/generate-otp

Occur when Mobile Number is invalid.

Integration Best Practices

Security Recommendations

Store JWT tokens securely and implement token rotation policies

Validate mobile numbers on the client side before API calls

Implement rate limiting to prevent OTP spam and abuse

Log all API interactions for audit and monitoring purposes

Use HTTPS only for all API communications

User Experience Guidelines

Provide clear feedback when OTP is being sent

Include estimated delivery time (typically 30-60 seconds)

Offer resend OTP functionality with appropriate cooldown periods

Display mobile number in masked format for privacy

Implement proper error handling with user-friendly messages

Code Samples

cURL

Python

Node.js

Related APIs

CKYC OTP Verification API - Validates the OTP received by the user and completes the authentication process for CKYC document download

CKYC Document Download API - Downloads the actual CKYC document after successful OTP verification

CKYC Status Check API - Checks the current status of a CKYC verification request

Compliance and Legal Considerations

This API handles sensitive personal information and must comply with:

Reserve Bank of India (RBI) guidelines for CKYC processing

Prevention of Money Laundering Act (PMLA) requirements

Information Technology Act data protection provisions

Aadhaar Act regulations for identity verification

Ensure proper data encryption, audit trails, and secure storage of all KYC-related information

curl --location --request POST 'https://kyc-api.surepass.app/api/v1/ckyc-v2/generate-otp' \ --header 'Content-Type: application/json' \ --data-raw '{ "client_id": "ckyc_EklilHGggwPXenefi", "mobile_number": "8939809876" }'

{ "data": { "client_id": "ckyc_download_nNfWARdhysddWFiXddXF", "otp_sent": true }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

CKYC Generate OTP

CKYC OTP Generation API#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Example Request#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses