commit 8359fa88ddfa419af4d454e3c6acb6f513f4c59a Author: vickytechkey Date: Mon Sep 28 19:48:11 2026 +0530 docs: add comprehensive technical documentation and guides for Cashfree Secure ID diff --git a/cashfree/README.md b/cashfree/README.md new file mode 100644 index 0000000..f89d3e1 --- /dev/null +++ b/cashfree/README.md @@ -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) | diff --git a/cashfree/biometric_and_smart_ocr.md b/cashfree/biometric_and_smart_ocr.md new file mode 100644 index 0000000..2b6b086 --- /dev/null +++ b/cashfree/biometric_and_smart_ocr.md @@ -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" + } +} +``` diff --git a/cashfree/kyc_stack.md b/cashfree/kyc_stack.md new file mode 100644 index 0000000..783d566 --- /dev/null +++ b/cashfree/kyc_stack.md @@ -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` diff --git a/cashfree/ovd_kyb_address_esign.md b/cashfree/ovd_kyb_address_esign.md new file mode 100644 index 0000000..8d8606c --- /dev/null +++ b/cashfree/ovd_kyb_address_esign.md @@ -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). diff --git a/cashfree/secure_id_introduction.md b/cashfree/secure_id_introduction.md new file mode 100644 index 0000000..bf50a3a --- /dev/null +++ b/cashfree/secure_id_introduction.md @@ -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: +x-client-secret: +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: `.` (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" +} +``` diff --git a/cashfree/video_kyc_and_1click_onboarding.md b/cashfree/video_kyc_and_1click_onboarding.md new file mode 100644 index 0000000..0b53960 --- /dev/null +++ b/cashfree/video_kyc_and_1click_onboarding.md @@ -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. diff --git a/cashfree/webhooks_and_test_data.md b/cashfree/webhooks_and_test_data.md new file mode 100644 index 0000000..d55d20e --- /dev/null +++ b/cashfree/webhooks_and_test_data.md @@ -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: +x-webhook-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`)