Cashfree Secure ID - KYC Stack & Identity Verification

The KYC Stack module enables real-time verification of individuals' primary identity credentials against Indian government databases (UIDAI, NSDL/ITD, NPCI, DigiLocker).

1. Bank Account Verification (BAV)

Cashfree BAV confirms account active status, registered account holder name, and IFSC details using NPCI / IMPS penny-drop validation rails.

A. BAV Synchronous V2

Endpoint: POST /v2/verification/bank-account/sync
Use Case: Immediate account validation during user checkout or onboarding.

Request Payload:

{
  "bank_account": "026291800001191",
  "ifsc": "YESB0000262",
  "name": "John Doe",
  "phone": "9876543210"
}

Response Fields:
- account_status: VALID, INVALID, SUSPECTED
- account_name: Account holder name registered at bank
- name_match_score: Fuzzy score (0-100) comparing provided name vs registered name
- name_match_result: DIRECT_MATCH, GOOD_PARTIAL_MATCH, MODERATE_PARTIAL_MATCH, POOR_PARTIAL_MATCH

B. BAV Asynchronous V2

Initiate Request: POST /v2/verification/bank-account/async
Fetch Status: GET /v2/verification/bank-account/async/{reference_id}
Use Case: Batch processing or async workflows to avoid UI blocking.

C. Bulk BAV V2

Initiate Request: POST /v2/verification/bank-account/bulk
Fetch Status: GET /v2/verification/bank-account/bulk/{bulk_verification_id}
Limit: Up to 10,000 account verifications per batch.

2. Reverse Penny Drop (RPD)

Eliminates the need for users to type account numbers and IFSC manually.

Workflow:
1. Merchant backend creates RPD request: POST /v2/verification/reverse-penny-drop
2. Cashfree generates a unique UPI payment link or QR code.
3. User completes a ₹1 payment from their banking app.
4. Cashfree retrieves account holder name, bank account number, and IFSC from NPCI callback.
5. Status Polling: GET /v2/verification/reverse-penny-drop/{reference_id} or webhook notification.

3. UPI Penny Drop

Validate bank account details by transferring ₹1 via a Virtual Payment Address (VPA / UPI ID).

Endpoint: POST /v2/verification/upi-penny-drop

Request:

{
  "vpa": "success@upi",
  "name": "John Doe"
}

Response: Returns VPA validity, registered account holder name, and associated bank account metadata.

4. IFSC Code Verification

Verify IFSC validity, bank branch name, address, MICR code, and supported transfer modes (IMPS, NEFT, RTGS, UPI).

Endpoint: POST /v2/verification/ifsc
Request: { "ifsc": "YESB0000262" }

5. PAN Verification (Permanent Account Number)

Supports individual and corporate/business PAN checks across multiple modes.

API Mode	Endpoint	Description
PAN Sync V2	`POST /v2/verification/pan`	Instant check for PAN existence, registered name, and PAN type (Individual/Business)
PAN Lite	`POST /v2/verification/pan/lite`	Validates PAN, DOB, and registered name against ITD database
PAN 360	`POST /v2/verification/pan/360`	Advanced check returning name, masked Aadhaar, masked mobile, masked email, and address info
PAN Bulk V2	`POST /v2/verification/pan/bulk`	Bulk PAN validation endpoint for processing lists of PAN numbers

Sample PAN Verification Request & Response

// POST /v2/verification/pan
{
  "pan": "ABCPV1234D",
  "name": "John Doe"
}

// Response
{
  "reference_id": 123456,
  "pan": "ABCPV1234D",
  "registered_name": "JOHN DOE",
  "type": "INDIVIDUAL",
  "valid": true,
  "name_match_score": 100.0,
  "name_match_result": "DIRECT_MATCH"
}

6. Aadhaar Verification & Masking

A. DigiLocker-based Aadhaar OTP Flow

Step 1: Check DigiLocker registration status via POST /v2/verification/digilocker/verify-account.
Step 2: Create DigiLocker Consent URL via POST /v2/verification/digilocker/url.
Step 3: User completes Aadhaar OTP authentication on DigiLocker hosted page.
Step 4: Fetch verified document fields via GET /v2/verification/digilocker/document.

B. Aadhaar Masking API

Per UIDAI regulations, businesses must obscure the first 8 digits of Aadhaar before storage.

Endpoint: POST /v2/verification/aadhaar/masking
Input: Image file / PDF of Aadhaar card.
Output: Masked image/PDF with first 8 digits redacted and QR code redacted.

7. KYC Links (Hosted No-Code Forms)

Send shareable hosted web links via SMS, WhatsApp, or Email to let customers upload documents and verify identity without code integration.

Dynamic Link Generation: POST /v2/verification/kyc-link (Single-use link for specific customer)
Static Link Generation: POST /v2/verification/kyc-link/static (Multi-use link sharing a standard KYC workflow)
Check Status: GET /v2/verification/kyc-link/{verification_id}
Deactivate Static Link: POST /v2/verification/kyc-link/static/deactivate

5 KiB Raw Blame History