# 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`