132 lines
5 KiB
Markdown
132 lines
5 KiB
Markdown
# 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**:
|
|
```json
|
|
{
|
|
"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**:
|
|
```json
|
|
{
|
|
"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
|
|
```json
|
|
// 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`
|