Search and Download V2 vs V3

The Search and Download V2 vs V3 section explains the key differences between CKYC API versions, particularly focusing on the new OTP-based consent mechanism introduced in V3.

Note: The versions referred to as V2 and V3 in this documentation correspond to versions 1.2 and 1.3 respectively in the underlying CKYC gateway implementation.

Overview

CKYC has implemented significant changes in API version 3.0 (backend version 1.3), primarily introducing an OTP-based consent mechanism for downloading individual KYC records. This change ensures customer consent and enhances security.

Key Changes in V3

What Changed:

Customer Consent: Explicit permission required before data access
Enhanced Security: Two-factor authentication for data retrieval
Privacy Protection: Customer awareness of data access
Regulatory Compliance: Alignment with data protection laws

Effective Date: May 9, 2025

API Version Differences

Feature	V2 (Legacy)	V3 (Current)
Consent Required	No	Yes (OTP-based)
Authentication	SHA-1	SHA-256
Download Process	Single step	Two-step (initiate + verify)
Customer Involvement	None	OTP verification required
Security Level	Basic	Enhanced

V2 (Legacy) Process

Search and Download Process

API Call: Send a search request with customer details to find their CKYC record.
Response: Receive search results, including the CKYC number.
Download Call: Use the CKYC number and an authentication factor (like Date of Birth) to download the KYC data in a single step.

API Endpoints (V2)

Search:

POST /api/ckyc/search

Download:

POST /api/ckyc/v2

Response Format (V2)

{
  "status": "success",
  "ckyc_id": "12345678901234",
  "kyc_data": {
    "customer_details": {...},
    "identity_documents": [...],
    "address_details": {...}
  }
}

V3 (Current) Process

OTP-Based Search and Download Flow

Search API Call: Send a search request with customer details to find their CKYC record.
Search Response: Receive search results, including the CKYC number.
Initiate Download: Make a download request using the CKYC number and an authentication factor. This action triggers an OTP to the customer's registered mobile number.
OTP Verification: The customer provides the OTP, which is sent to the validation endpoint.
Data Release: Upon successful OTP verification, the KYC data is released.

API Endpoints (V3)

The V3 process involves three main endpoints in the underlying Java service, exposed via the Python gateway:

Search:

POST /api/ckyc/search

Note: The Python gateway uses a generic search endpoint that currently routes to the V2/v1.2 Java implementation. The V3/v1.3 search logic is available in the Java service at /v3/api/ckyc/search.

1. Initiate Download & Trigger OTP:

POST /v3/api/ckyc/download

2. Verify OTP & Download Data:

POST /v3/api/ckyc/validate-otp

Step 1: Initiate Download

This call starts the download process and triggers the OTP.

POST /v3/api/ckyc/download
Content-Type: application/json
Authorization: Bearer {token}

Request Body:

{
  "ckyc_no": "12345678901234",
  "auth_factor_type": "01", // e.g., '01' for Date of Birth
  "auth_factor": "18-08-1994"
}

Response: An OTP is sent to the customer's registered mobile number, and the API returns a confirmation message.

{
  "message": "OTP has been sent to the registered mobile number.",
  "status": 200
}

Step 2: Verify OTP and Download

This call verifies the OTP and, if successful, returns the customer's KYC data.

POST /v3/api/ckyc/validate-otp
Content-Type: application/json
Authorization: Bearer {token}

Request Body:

{
  "ckyc_no": "12345678901234",
  "otp": "123456",
  "validate": "Y"
}

Response: KYC data is returned upon successful OTP verification.

{
  "data": {
    "PID_DATA": {
      // ... complete KYC data ...
    }
  },
  "status": 200,
  "version": "1.3"
}

Migration Timeline

Important Dates

Test Environment: Available immediately
Production Go-Live: May 9, 2025
Legacy Support End: May 31, 2025 (8 PM)

Migration Steps

API Upgrade: Update to the V3 endpoints.
OTP Integration: Implement the OTP collection and verification flow in your application.
Testing: Validate the complete flow in the test environment.
Deployment: Go live before the May 31, 2025 deadline.

Implementation Changes

Authentication Updates

Hashing Algorithm: Upgrade from SHA-1 to SHA-256 for digital signatures.
Token Management: Ensure proper handling of API authentication tokens.
Error Handling: Implement logic for OTP-specific errors (e.g., invalid OTP, expired OTP).

User Experience Changes

OTP Collection: Add an interface for users to input the OTP.
Customer Communication: Clearly explain the purpose of the OTP to the end-user.
Fallback Options: Consider alternative verification methods if OTP delivery fails.

Error Handling

OTP Expired: Handle scenarios where the OTP has expired and needs to be resent.
Invalid OTP: Implement retry mechanisms for incorrect OTP entry.
Mobile Not Found: Manage cases where a mobile number is not available for the customer.

Benefits of V3

Enhanced Security

Customer Consent: Explicit permission is captured for data access.
Two-Factor Authentication: OTP adds a crucial layer of security.
Audit Trail: A complete record of customer consent is maintained.
Fraud Prevention: Reduces the risk of unauthorized data access.

Regulatory Compliance

Data Protection: Aligns with modern data privacy laws and regulations.
Customer Rights: Ensures customers are aware of when their data is being accessed.
Audit Requirements: Meets regulatory needs for auditable consent.

Business Value

Customer Trust: A transparent data access process builds customer confidence.
Risk Reduction: Lowers compliance and security risks for the institution.
Future-Proof: Aligns with the evolving regulatory landscape.