vignesh/documentverification
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: add comprehensive technical documentation and guides for Cashfree Secure ID

Browse source
This commit is contained in:
vickytechkey 2026-09-28 19:48:11 +05:30
commit 8359fa88dd
7 changed files with 725 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

65
cashfree/README.md Normal file
View file

@ -0,0 +1,65 @@
# Cashfree Secure ID - AI Knowledge Base & Technical Documentation
This directory contains comprehensive technical documentation, API specifications, workflows, and test data for **Cashfree Secure ID** (Cashfree Verification Suite / VRS). It is structured specifically to serve as context for AI models, developer assistants, and automated integration workflows.
---
## Document Index
1. [**Introduction & Setup (`secure_id_introduction.md`)**](file:///home/vignesh/github/documentverification/cashfree/secure_id_introduction.md)
- Core Architecture & Verification Suite Overview
- Environments & Base URLs (Sandbox vs Production)
- Authentication Credentials (`x-client-id`, `x-client-secret`)
- 2FA Signature Generation (RSA Encryption & Timestamping)
- IP Whitelisting & Security Controls
- Rate Limits & API Success Rate Alerts
2. [**KYC Stack & Verification (`kyc_stack.md`)**](file:///home/vignesh/github/documentverification/cashfree/kyc_stack.md)
- Bank Account Verification (Sync V2, Async V2, Bulk V2)
- Reverse Penny Drop & UPI Penny Drop
- IFSC Code Lookup & Branch Verification
- PAN Verification (PAN Lite, PAN 360, Sync V2, Bulk V2)
- Aadhaar Verification & Masking
- No-code KYC Links (Form Link & Static Link)
3. [**Biometric KYC & Smart OCR (`biometric_and_smart_ocr.md`)**](file:///home/vignesh/github/documentverification/cashfree/biometric_and_smart_ocr.md)
- **Biometric KYC**:
- Face Match (AI image similarity scoring)
- Name Match (Phonetic & Indian name variation algorithms)
- Face Liveness Detection (Anti-spoofing AI check)
- **Smart OCR**:
- Auto-extraction & forgery detection across 10+ document types (Aadhaar, PAN, Driving Licence, Voter ID, Passport, Vehicle RC, Cancelled Cheque, Invoice)
- Field schemas & verification results
4. [**Video KYC & 1-Click Onboarding (`video_kyc_and_1click_onboarding.md`)**](file:///home/vignesh/github/documentverification/cashfree/video_kyc_and_1click_onboarding.md)
- **Video KYC (VKYC)**:
- RBI vCIP Compliant Remote Onboarding
- End-User, Agent, Auditor & Merchant Journeys
- SDK vs API Integration Models & Notification Templates
- **1-Click Onboarding**:
- Mobile 360 (Identity & pre-fill from mobile number)
- Advanced Employment Verification (EPFO & PF history)
- OAuth Session & Access Token Flow
5. [**OVDs, KYB, Address Verification & E-Sign (`ovd_kyb_address_esign.md`)**](file:///home/vignesh/github/documentverification/cashfree/ovd_kyb_address_esign.md)
- **Officially Valid Documents (OVDs)**: Voter ID, Driving Licence, Passport, Vehicle RC
- **Know Your Business (KYB)**: GSTIN Verification, PAN-to-GSTIN, CIN Check, Udyam Verification, PAN-to-Udyam
- **Address Verification**: Geocoding (Address to Lat/Long) & Reverse Geocoding
- **E-Sign Suite**: Aadhaar-based digital document signing workflow
6. [**Webhooks & Sandbox Test Data (`webhooks_and_test_data.md`)**](file:///home/vignesh/github/documentverification/cashfree/webhooks_and_test_data.md)
- Webhook Setup, Payloads & `x-webhook-signature` HMAC Verification
- Complete Sandbox Test Credentials, Sample Document Numbers, Test Accounts, and Expected Statuses for every API
---
## Quick Reference Summary
| Parameter / Feature | Value / Details |
| :--- | :--- |
| **Sandbox Base URL** | `https://sandbox.cashfree.com/verification` |
| **Production Base URL** | `https://api.cashfree.com/verification` |
| **Authentication Headers** | `x-client-id`, `x-client-secret`, `x-api-version: 2024-01-01` (or `2022-09-01`) |
| **2FA Method Header** | `x-cf-signature` (RSA-encrypted `clientId.timestamp` using downloaded public key) |
| **Test Standard OTP** | `111000` (or `123456` for VKYC / `1234` for 1-Click Onboarding) |
| **Primary Doc Source** | [Cashfree Secure ID Docs](https://www.cashfree.com/docs/secure-id/introduction) |

102
cashfree/biometric_and_smart_ocr.md Normal file
View file

@ -0,0 +1,102 @@
# Cashfree Secure ID - Biometric KYC & Smart OCR
---
## Part 1: Biometric KYC Suite
The Biometric KYC suite provides AI-powered facial analysis, liveness verification, and Indian name matching algorithms.
### 1. Face Match API
Compares two face images (selfie vs document photo, or photo vs photo) and calculates a similarity score.
- **Endpoint**: `POST /v2/verification/face-match`
- **Request Format**: `multipart/form-data`
- `first_image`: Base64 string or image file
- `second_image`: Base64 string or image file
- **Response**:
```json
{
"status": "SUCCESS",
"score": 0.95,
"match_result": "MATCH",
"message": "Faces match successfully"
}
```
### 2. Name Match API
Designed specifically for Indian naming conventions, handling initials, reversed order (Surname first), spelling variants, and regional transliterations.
- **Endpoint**: `POST /v2/verification/name-match`
- **Request**:
```json
{
"name_1": "JOHN DOE",
"name_2": "JOHN DE"
}
```
- **Response**:
```json
{
"status": "SUCCESS",
"score": 0.93,
"reason": "GOOD_PARTIAL_MATCH"
}
```
| Match Reason | Typical Score Range | Description |
| :--- | :--- | :--- |
| `DIRECT_MATCH` | 1.00 (100%) | Exact string match |
| `GOOD_PARTIAL_MATCH` | 0.85 - 0.99 | Minor typo or single letter variation |
| `MODERATE_PARTIAL_MATCH` | 0.65 - 0.84 | Initial expansion (e.g. V. Vignesh vs Vignesh V) |
| `POOR_PARTIAL_MATCH` | 0.30 - 0.64 | Significant divergence |
| `NO_MATCH` | 0.00 | Completely different names |
### 3. Face Liveness API
Detects whether a submitted face photo/video frame is a live human face or a spoof attempt (screen presentation, printed photo, 3D mask).
- **Endpoint**: `POST /v2/verification/face-liveness`
- **Request**: Image payload
- **Response**: Returns liveness status (`LIVE`, `SPOOF_DETECTED`), confidence score, face count, and image quality metrics.
---
## Part 2: Smart OCR Suite
Cashfree **Smart OCR** parses, cleans, and extracts structured data from over 10 document types with integrated document quality checks and anti-forgery validation.
- **Endpoint**: `POST /v2/verification/smart-ocr`
- **Supported File Formats**: PNG, JPG, JPEG, PDF (max 10MB)
### Supported Document Types & Extracted Fields
| Document Type | Extracted Fields |
| :--- | :--- |
| **Aadhaar Card** | Name, DOB/Year of Birth, Gender, Aadhaar Number, Address, Pincode, Father/Husband Name |
| **PAN Card** | PAN Number, Full Name, Father's Name, Date of Birth, PAN Type (Individual/Business) |
| **Driving Licence (DL)** | DL Number, Holder Name, Date of Issue, Expiry Date, Vehicle Classes Allowed, Address, DOB |
| **Voter ID (EPIC)** | EPIC Number, Voter Name, Relative Name, Gender, State, Assembly Constituency, Address |
| **Passport** | Passport Number, Surname, Given Names, Nationality, Date of Birth, Place of Birth, Expiry Date |
| **Vehicle RC** | Registration Number, Owner Name, Vehicle Class, Fuel Type, Engine/Chassis Number, Registration Date |
| **Cancelled Cheque** | Account Number, IFSC Code, Bank Name, Account Holder Name, Cheque Number |
| **Invoice** | Invoice Number, Date, Vendor GSTIN, Buyer GSTIN, Line Items, Subtotal, Tax Amounts, Total |
### Fraud Checks & Quality Response Sample
```json
{
"status": "SUCCESS",
"document_type": "PAN",
"quality_checks": {
"blur_detected": false,
"cut_off_detected": false,
"glare_detected": false
},
"forgery_checks": {
"tampering_detected": false,
"font_mismatch": false,
"photo_overlap": false
},
"extracted_data": {
"pan_number": "ABCPV1234D",
"name": "JOHN DOE",
"father_name": "RICHARD DOE",
"dob": "1994-08-05"
}
}
```

132
cashfree/kyc_stack.md Normal file
View file

@ -0,0 +1,132 @@
# 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`

85
cashfree/ovd_kyb_address_esign.md Normal file
View file

@ -0,0 +1,85 @@
# Cashfree Secure ID - OVDs, KYB, Address Verification & E-Sign
---
## 1. Officially Valid Documents (OVDs)
OVD APIs validate document numbers against official Indian government databases (Elections Commission, MoRTH, RTOs, Passport Seva).
| Document Type | Endpoint | Input Parameters | Output Information |
| :--- | :--- | :--- | :--- |
| **Voter ID** | `POST /v2/verification/voter-id` | `epic_number` | Full Name, Relative Name, State, Constituency, Polling Station |
| **Driving Licence** | `POST /v2/verification/driving-licence` | `dl_number`, `dob` (YYYY-MM-DD) | Holder Name, Issue Date, Expiry Date, RTO Location, Vehicle Classes |
| **Passport** | `POST /v2/verification/passport` | `file_number`, `dob` | Passport File Status, Name, DOB, Given Name |
| **Vehicle RC** | `POST /v2/verification/vehicle-rc` | `vehicle_number` | Owner Name, Vehicle Class, Chassis No, Engine No, Fuel Type, Insurance Validity |
---
## 2. Know Your Business (KYB) Suite
Validate legal business entities, GST registrations, corporate filings, and MSME registrations.
### A. GSTIN Verification
- **Endpoint**: `POST /v2/verification/gstin`
- **Request**: `{ "gstin": "29AAICP2912R1ZR" }`
- **Response**: Legal Business Name, Trade Name, Registration Date, GSTIN Status (`ACTIVE`, `CANCELLED`), Taxpayer Type (Regular/Composition), Registered Principal Address.
### B. PAN to GSTIN
Fetch all active and inactive GSTIN numbers registered under a specific business PAN.
- **Endpoint**: `POST /v2/verification/pan-to-gstin`
- **Request**: `{ "pan": "DUMPY1001A" }`
- **Response**: List of GSTINs with state codes and status.
### C. CIN Verification (Corporate Identification Number)
Verify MCA registered companies (Pvt Ltd, Public Ltd, OPC).
- **Endpoint**: `POST /v2/verification/cin`
- **Request**: `{ "cin": "U72900KA2015PTC082989" }`
- **Response**: Company Name, Incorporation Date, Authorised Capital, Paid-up Capital, Directors List, MCA Status.
### D. Udyam Verification (MSME)
- **Verify Udyam**: `POST /v2/verification/udyam` with `udyam_registration_number` (e.g., `UDYAM-UP-43-1234567`).
- **Fetch Udyam with PAN**: `POST /v2/verification/pan-to-udyam` with `pan` (e.g., `AMJCL2021N`).
---
## 3. Address Verification Suite
Validate physical user addresses and geographic location parameters to meet RBI KYC requirements.
### A. Geocoding
Convert a physical street address into exact latitude and longitude coordinates.
- **Endpoint**: `POST /v2/verification/geocoding`
- **Request**: `{ "address": "Bangalore Karnataka" }`
- **Response**: `latitude: 12.9274915`, `longitude: 77.6326806`, accuracy score.
### B. Reverse Geocoding
Convert GPS coordinates (latitude/longitude) into structured human-readable addresses.
- **Endpoint**: `POST /v2/verification/reverse-geocoding`
- **Request**: `{ "latitude": 12.9274915, "longitude": 77.6326806 }`
- **Response**: Formatted address, Street Name, City, State, Country, Pincode.
---
## 4. E-Sign Suite (Aadhaar Digital Signing)
Collect legally binding electronic signatures on PDF documents (agreements, loan forms, contracts) using Aadhaar e-Sign authentication.
### E-Sign Workflow
1. **Upload Document**: `POST /v2/verification/esign/document` (Upload PDF file; returns `document_id`).
2. **Create E-Sign Request**: `POST /v2/verification/esign/request`
```json
{
"document_id": "doc_8849102",
"signers": [
{
"name": "John Doe",
"phone": "9876543210",
"email": "john.doe@example.com",
"sequence": 1
}
],
"redirect_url": "https://example.com/esign-complete"
}
```
3. **User Action**: Signer receives link, reviews document, enters Aadhaar number, inputs OTP sent by UIDAI.
4. **Get Status & Download**: `GET /v2/verification/esign/{verification_id}` (Returns status `SIGNED` and signed PDF download URL).

112
cashfree/secure_id_introduction.md Normal file
View file

@ -0,0 +1,112 @@
# Cashfree Secure ID - Introduction & Setup Guide
Cashfree Secure ID (also known as Verification Suite or VRS) is an end-to-end identity verification, KYC, document extraction, biometric analysis, and business entity validation solution engineered specifically for the Indian regulatory landscape (RBI, UIDAI, NPCI, DPDP Act compliance).
---
## 1. Environment & Base URLs
Cashfree provides two distinct environments for API integration:
| Environment | Base URL | Usage |
| :--- | :--- | :--- |
| **Sandbox / Test** | `https://sandbox.cashfree.com/verification` | Integration testing, mocked verification responses, sandbox credentials |
| **Production** | `https://api.cashfree.com/verification` | Live verification against official government databases & NPCI rails |
---
## 2. Authentication & Headers
Every request to Cashfree Secure ID APIs requires API key authentication and optional 2FA signature headers.
### Required HTTP Headers
```http
x-client-id: <YOUR_APP_ID>
x-client-secret: <YOUR_SECRET_KEY>
x-api-version: 2024-01-01
Content-Type: application/json
```
### Credentials Verification API
To test if your API credentials are active and valid:
- **Endpoint**: `POST /api/v1/credentials/verify`
- **Headers**: Include `x-client-id` and `x-client-secret`
---
## 3. Two-Factor Authentication (2FA) & Security
Cashfree enforces server-level security via either **IP Whitelisting** or **RSA Signature Generation**.
### A. IP Whitelisting
- Whitelist up to 25 public **IPv4** server addresses from the Cashfree Merchant Dashboard (**Developers** > **Secure ID** > **Two-Factor Authentication**).
- Incoming requests from unlisted IPs in Production will be rejected.
### B. RSA API Signature Generation (`x-cf-signature`)
For dynamic IP infrastructure or cloud deployments (Kubernetes, AWS Lambda, auto-scaling clusters), use the RSA Public Key signature method instead of static IP whitelisting.
#### Step-by-Step Signature Generation:
1. Obtain public key PEM file (`public_key.pem`) from Cashfree Merchant Dashboard.
2. Construct string: `<x-client-id>.<current_unix_timestamp_seconds>` (e.g., `CF123456.1727530000`).
3. Encrypt string using RSA/ECB/OAEPWithSHA-1AndMGF1Padding with Cashfree Public Key.
4. Base64-encode the resulting binary ciphertext.
5. Send encoded string in `x-cf-signature` header.
6. The generated signature is valid for 5 minutes.
#### Code Example (Java):
```java
public static String generateSignature(String clientId, String publicKeyPemPath) throws Exception {
long epochTimestamp = Instant.now().getEpochSecond();
String payload = clientId + "." + epochTimestamp;
byte[] keyBytes = Files.readAllBytes(Paths.get(publicKeyPemPath));
String publicKeyContent = new String(keyBytes)
.replace("-----BEGIN PUBLIC KEY-----", "")
.replace("-----END PUBLIC KEY-----", "")
.replaceAll("\\s+", "");
X509EncodedKeySpec keySpec = new X509EncodedKeySpec(Base64.getDecoder().decode(publicKeyContent));
KeyFactory kf = KeyFactory.getInstance("RSA");
PublicKey pubKey = kf.generatePublic(keySpec);
Cipher cipher = Cipher.getInstance("RSA/ECB/OAEPWithSHA-1AndMGF1Padding");
cipher.init(Cipher.ENCRYPT_MODE, pubKey);
byte[] encrypted = cipher.doFinal(payload.getBytes(StandardCharsets.UTF_8));
return Base64.getEncoder().encodeToString(encrypted);
}
```
---
## 4. Wallet Recharge & Funding
- All API calls incur verification charges deducted from your **Cashfree Secure ID Wallet**.
- Auto-recharge and low-balance alerts can be configured in the dashboard.
- Whitelist funding bank accounts in the dashboard before initiating wallet top-ups via IMPS/NEFT/RTGS.
---
## 5. Success Rate (SR) Alerts & Rate Limits
- **Rate Limits**: Configured per API endpoint (e.g., BAV, PAN, Aadhaar). Excessive requests return HTTP `429 Too Many Requests`.
- **SR Alerts**: Configure email notifications when API Success Rate drops below specified percentages in merchant settings (**Settings** > **Email Notifications** > **SR Alerts**).
---
## 6. General API Response & Error Structure
Cashfree APIs follow standard REST response formats with error sub-codes for granular tracking.
### Standard Error Response Format
```json
{
"type": "validation_error",
"code": "invalid_pan_number",
"message": "The PAN number provided is invalid or malformed",
"status": "FAILED"
}
```

54
cashfree/video_kyc_and_1click_onboarding.md Normal file
View file

@ -0,0 +1,54 @@
# Cashfree Secure ID - Video KYC & 1-Click Onboarding
---
## Part 1: Video KYC (VKYC)
Cashfree Video KYC enables regulated entities (Banks, NBFCs, REs, Fintechs) to perform real-time video verification compliant with RBI **vCIP (Video-based Customer Identification Process)** guidelines.
### Architecture & User Roles
```
[End User Web/App] <---> [Cashfree VKYC Session Engine] <---> [Agent Dashboard]
|
v
[Auditor Dashboard]
```
1. **End User**: Launches VKYC session on web browser or native mobile app (Android/iOS SDK). Consents to camera/mic/location access.
2. **Agent**: Live trained KYC operator conducts video interaction, captures photo, verifies PAN/Aadhaar OCR, captures geo-location, and executes geotagging.
3. **Auditor**: Senior compliance officer reviews recorded VKYC session, agent notes, geotag, and approves or rejects the case.
4. **Merchant Admin**: Manages agents/auditors, sets up queues, downloads compliance reports.
### Key Video KYC Endpoints
- **Add Secure ID User Profile**: `POST /v2/verification/video-kyc/user`
- **Initiate VKYC Request & Send Link**: `POST /v2/verification/video-kyc/initiate`
- Generates VKYC session link and dispatches via SMS, Email, or WhatsApp using configured templates.
- **Generate SDK Auth Token**: `POST /v2/verification/video-kyc/oauth-token`
- **Fetch VKYC Status**: `GET /v2/verification/video-kyc/status/{verification_id}`
- **Webhooks**: Subscribes to events like `SESSION_STARTED`, `AGENT_CONNECTED`, `COMPLETED`, `AUDIT_APPROVED`, `AUDIT_REJECTED`.
---
## Part 2: 1-Click Onboarding
1-Click Onboarding simplifies customer onboarding and consent management across Web, Android, and iOS apps using mobile-number-based data pre-fill.
### 1. Mobile 360
Retrieve user identity, financial signals, and KYC details using mobile number verification with consent.
- **Send OTP Request**: `POST /v2/verification/mobile-360/otp`
- Sends OTP via SMS or WhatsApp.
- Test OTP in Sandbox: `111000`
- **Verify OTP & Extract Identity**: `POST /v2/verification/mobile-360/verify`
- Extracts verified name, address, PAN, bank accounts linked, and risk signals.
### 2. Advanced Employment Verification (EPFO)
Verifies employee employment history and recent Provident Fund (PF) contributions.
- **Endpoint**: `POST /v2/verification/advanced-employment`
- **Request Parameters**: `phone`, `pan`, `uan` (Universal Account Number), `dob`, `employee_name`, `employer_name`
- **Response**: Returns employment history, UAN status, EPFO monthly contribution history, and employer verification status.
### 3. SDK Integration & Template Customization
- Configure brand logo, primary brand color, and consent disclaimer text in the Secure ID Dashboard (**1-Click Onboarding** > **Template**).
- Mobile SDKs (Android / iOS / React Native) launch pre-built consent screens, execute OTP / Silent Mobile Verification (SMV), and pass back session access tokens to the merchant app.

175
cashfree/webhooks_and_test_data.md Normal file
View file

@ -0,0 +1,175 @@
# Cashfree Secure ID - Webhooks & Comprehensive Sandbox Test Data
---
## Part 1: Webhook Integration & Security
Cashfree dispatches HTTP POST callbacks for async verification completion (BAV Async, Video KYC, DigiLocker, E-Sign, Reverse Penny Drop, KYC Links).
### Webhook Event Header & Signature Verification
Every webhook notification includes security headers to prevent spoofing.
```http
x-webhook-signature: <HMAC_SHA256_SIGNATURE>
x-webhook-timestamp: <UNIX_TIMESTAMP>
```
#### Verification Algorithm:
1. Extract raw request payload body string `raw_body`.
2. Extract timestamp value `timestamp` from `x-webhook-timestamp` header.
3. Form payload to sign: `timestamp + "." + raw_body`.
4. Calculate HMAC-SHA256 hash using your Cashfree Secret Key (`x-client-secret`).
5. Base64-encode the resulting digest.
6. Compare with incoming `x-webhook-signature` header string.
#### Code Example (Node.js):
```javascript
const crypto = require('crypto');
function verifyCashfreeWebhook(rawBody, timestamp, signatureHeader, clientSecret) {
const payloadToSign = timestamp + '.' + rawBody;
const computedSignature = crypto
.createHmac('sha256', clientSecret)
.update(payloadToSign)
.digest('base64');
return computedSignature === signatureHeader;
}
```
---
## Part 2: Complete Sandbox Test Data Reference
In the **Test / Sandbox environment** (`https://sandbox.cashfree.com/verification`), you **MUST** use the exact sample data below to simulate success and failure scenarios. Any unlisted values will be rejected.
### 1. General Test OTP
- **Standard Verification OTP**: `111000`
- **Video KYC Test OTP**: `123456`
- **1-Click Onboarding Test OTP**: `1234` (Phone number: `9999991234`)
---
### 2. Bank Account & Name Match Test Data
| Account Number | IFSC Code | Expected Result / Remarks |
| :--- | :--- | :--- |
| `026291800001191` | `YESB0000262` | `SUCCESS` (Name: JOHN DOE) |
| `00011020001772` | `HDFC0000001` | `SUCCESS` |
| `000890289871772` | `SCBL0036078` | `SUCCESS` |
| `1233943142` | `YESB0000262` | `SUCCESS` (Name: TOM WELLS) |
| `388108022658` | `YESB0000262` | `SUCCESS` (Name: BOB HOPE) |
| `000100289877623` | `SBIN0008752` | `FAILED_AT_BANK` |
| `2640101002729` | `CNRR0002640` | `INVALID_IFSC_CODE` |
| `026291800001190` | `YESB0000262` | `INVALID_ACCOUNT_NUMBER` |
| `02014457596969` | `CITI0000001` | `SUCCESS` (Transitions later to `REVERSED`) |
---
### 3. PAN Verification Test Data
| PAN | Type | Remarks |
| :--- | :--- | :--- |
| `ABCPV1234D` | Individual | `VALID` |
| `XYZPP4321W` | Individual | `VALID` |
| `AZJPG7110R` | Individual | `VALID` |
| `ABCCD8000T` | Business | `VALID` |
| `XYZHP2000L` | Business | `VALID` |
| `AAAHU4383C` | Business | `VALID` |
| `AMJCL2021N` | Business | `VALID` |
| `DEFPV0126D` | Individual | `INVALID` |
| `TUVPP5678W` | Individual | `INVALID` |
| `LMNCD8010T` | Business | `INVALID` |
---
### 4. Aadhaar Verification Test Data
| Aadhaar Number | Remarks |
| :--- | :--- |
| `655675523712` | `VALID` |
| `655675523711` | `VALID` |
| `655675523710` | `INVALID` |
| `655675523709` | `INVALID` |
---
### 5. GSTIN Verification Test Data
| GSTIN | Remarks |
| :--- | :--- |
| `29AAICP2912R1ZR` | `VALID` |
| `27ABCFGH5678D1Z` | `VALID` |
| `36JKLPQR9012E2Y` | `VALID` |
| `05BBICP2912R1ZR` | `VALID` |
| `29AAIZP2912R1ZR` | `INVALID` |
| `05BBICA2912R1ZR` | `INVALID` |
---
### 6. UPI Penny Drop Test Data (VPA)
| VPA / UPI ID | Remarks |
| :--- | :--- |
| `success@upi` | `VALID` |
| `valid@upi` | `VALID` |
| `valid@ybl` | `VALID` |
| `invalid@upi` | `INVALID` |
| `incorrect@upi` | `INVALID` |
| `expired@upi` | `EXPIRED` |
---
### 7. Officially Valid Documents (OVDs) Test Data
#### Driving Licence
- Valid: DL `KA0120198900984` (DOB: `1994-08-05`)
- Invalid: DL `KA2320238908787` (DOB: `1987-09-04`)
#### Voter ID (EPIC)
- Valid: `UAI4574761`
- Invalid: `UAI4574762`
#### Passport (File Number prefix)
- Valid: Prefix `PA1` (e.g., `PA1123456789012`)
- Invalid: Prefix `PA0`
#### Vehicle RC (Registration Number)
- Valid: `HJ01ME5678`
- Invalid: `HJ01ME5279`
---
### 8. Corporate & MSME Verification Test Data
#### CIN (Corporate Identification Number)
- Valid: `U72900KA2015PTC082989`, `U72900KA2015PTC082988`
- Invalid: `U72900KA2015PTC082981`
#### Udyam Registration
- Valid: `UDYAM-UP-43-1234567`
- Not Found: `UDYAM-MH-43-1234567`
- Cancelled: `UDYAM-KA-43-1234567`
#### PAN to Udyam
- Success: PAN `AMJCL2021N`
- Not Found: PAN `LMNCD8010T`
---
### 9. Face Liveness Test Prefix
| Verification ID Prefix | Simulated Result |
| :--- | :--- |
| `2222XXXXX` | `MULTIPLE_FACES_DETECTED` |
| `3333XXXXX` | `FACE_NOT_DETECTED` |
| `4444XXXXX` | `REAL_FACE_NOT_DETECTED` |
| Any other ID | `SUCCESS / LIVE` |
---
### 10. Geocoding & IP Verification
- **Geocoding Address**: `Bangalore Karnataka` (`VALID`), `AAA BBB CCC` (`INVALID`)
- **Reverse Geocoding Lat/Long**: `12.9274915`, `77.6326806` (`SUCCESS`)
- **IP Address**: `1.0.171.255` (`VALID`), `219.12.67.255` (`INVALID`)