paymentservice/documentation/cashfree/09_secureid_and_kyc_verification.md

Cashfree Secure ID & KYC Verification APIs

1. Overview

Cashfree Secure ID provides API-driven identity, bank account, and compliance verification against authoritative Indian databases (NPCI, NSDL, UIDAI, GSTN).

Common use cases for Tradhox:

• Verifying vendor / seller bank accounts before onboarding.
• Verifying PAN & GSTIN for marketplace merchant compliance.
• Verifying customer UPI IDs to prevent payment failures and fraud.

---

2. Bank Account Verification (Penny Drop)

Deposits ₹1.00 into the target bank account via IMPS to verify that the account is active and retrieve the exact registered name.

Endpoint

GET /verification/bank-account/sync?name={name}&phone={phone}&bankAccount={account}&ifsc={ifsc}

Or via POST:

POST /verification/bank-account/sync

Request Payload

{
  "bankAccount": "50100234567890",
  "ifsc": "HDFC0001234",
  "name": "Vignesh Tech",
  "phone": "9876543210"
}

Response (200 OK)

{
  "status": "SUCCESS",
  "subCode": "200",
  "message": "Bank account verified successfully",
  "accountStatus": "VALID",
  "accountStatusCode": "ACCOUNT_IS_VALID",
  "data": {
    "nameAtBank": "VIGNESH TECH PRIVATE LIMITED",
    "refId": "1948571029",
    "bankName": "HDFC BANK",
    "branch": "INDIRANAGAR",
    "city": "BANGALORE",
    "micr": "560240012",
    "nameMatchScore": 95,
    "nameMatchResult": "SUCCESS"
  }
}

Tip

The nameMatchScore provides a 0-100 fuzzy matching score comparing the provided name with the official nameAtBank.

---

3. UPI VPA Verification

Checks whether a UPI ID exists without deducting or transferring money.

Endpoint

POST /verification/vpa

Request Payload

{
  "vpa": "vignesh@okhdfcbank",
  "name": "Vignesh"
}

Response (200 OK)

{
  "status": "SUCCESS",
  "subCode": "200",
  "message": "VPA verified successfully",
  "vpa": "vignesh@okhdfcbank",
  "accountExists": "YES",
  "nameAtBank": "Vignesh Tech",
  "nameMatchScore": 100
}

---

4. PAN Verification

Validates PAN against the Income Tax Department / NSDL database.

Endpoint

POST /verification/pan

Request Payload

{
  "pan": "ABCDE1234F",
  "name": "Vignesh Tech"
}

Response (200 OK)

{
  "status": "VALID",
  "pan": "ABCDE1234F",
  "type": "Individual",
  "registered_name": "VIGNESH TECH",
  "name_match_score": 100,
  "aadhaar_seeding_status": "LINKED"
}

---

5. GSTIN Verification

Validates Goods and Services Tax Identification Number.

Endpoint

POST /verification/gstin

Request Payload

{
  "gstin": "29ABCDE1234F1Z5"
}

Response (200 OK)

{
  "status": "VALID",
  "gstin": "29ABCDE1234F1Z5",
  "legal_name": "TRADHOX TECHNOLOGIES PRIVATE LIMITED",
  "trade_name": "TRADHOX",
  "registration_date": "2024-01-15",
  "gstin_status": "Active",
  "taxpayer_type": "Regular",
  "principal_place_of_business": {
    "address": "Tech Park, Outer Ring Road",
    "state": "Karnataka",
    "pincode": "560103"
  }
}