vignesh/documentverification
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
documentverification/CODEPLUS_API_DOCUMENTATION.md
vickytechkey 0291bd6195
All checks were successful
Deploy Beta (NATIVE) / deploy (push) Successful in 39s
Details
feat: add core verifier engine, serializers, tests, vendor client, and test portal template
2026-10-17 13:34:43 +05:30

17 KiB
Raw Permalink Blame History

Codeplus (apihub.services) Document Verification Engine Documentation

This document covers all active verification functions implemented in the Multi-Vendor Verification Engine using the Codeplus (apihub.services) adapter.

1. Architecture & Failover Waterfall

The verification engine provides seamless waterfall cascading across onboarded vendors:

  • Every request is dispatched to the highest-priority active vendor.
  • If the vendor encounters an error (e.g. HTTP 5xx, timeout, network failure, or API failure status), the engine logs the failure and automatically cascades to the next vendor.
  • Every attempt, raw vendor response, final normalized data, latency, and client response are permanently recorded in PostgreSQL.

Database Storage Architecture

  1. VerificationTransaction (verifier_verificationtransaction):

    • reference_id: Unique UUID generated for each client request.
    • document_type: Type of document requested (pan, bank_account, gstin, etc.).
    • status: Final outcome (SUCCESS, FAILED, ERROR).
    • successful_vendor: Name of the vendor that resolved the verification (e.g. codeplus).
    • input_payload: Masked, audit-safe input data.
    • final_data: Normalized result payload.
    • response_payload: Complete response payload returned to the client.
    • attempts_count: Total number of vendors attempted in the waterfall.
    • total_latency_ms: Total execution time in milliseconds.
    • created_at / updated_at: Timestamps.

  2. VendorAttemptLog (verifier_vendorattemptlog):

    • transaction: Foreign key to VerificationTransaction.
    • attempt_number: Sequential attempt sequence (1, 2, ...).
    • vendor_name: Vendor adapter invoked (codeplus).
    • status: Vendor status (SUCCESS, FAILED, ERROR, SKIPPED).
    • is_success: Boolean indicator.
    • data: Extracted vendor data block.
    • raw_response: Full unaltered JSON/HTTP response returned by the upstream API.
    • error_code & error_message: Upstream failure codes and diagnostics.
    • latency_ms: Execution latency for this specific vendor hit.

2. Global Authentication & Configuration

The Codeplus adapter uses the following headers for all upstream calls:

X-Client-Api-ID: CAPI-YYR0YJIE0VMTDENY
X-Client-Api-Secret: s24Ts9wFsgl64mFzA61OqG0RDLRs2HFCpmOZBmqs
Content-Type: application/json

Environment variables configured in docverify/settings.py / .env:

  • CODEPLUS_BASE_URL: https://apihub.services
  • CODEPLUS_CLIENT_API_ID: CAPI-YYR0YJIE0VMTDENY
  • CODEPLUS_CLIENT_API_SECRET: s24Ts9wFsgl64mFzA61OqG0RDLRs2HFCpmOZBmqs

3. Summary of Available Functions

Function Name Upstream Endpoint Internal document_type Description
Pan Verification (v5 Recommended) POST /v5/pan-verify pan, pan_v5, pan_verify Full PAN holder details with name, DOB, gender, masked Aadhaar & address.
Detailed PAN API POST /v4/pan-detailed pan_detailed Comprehensive PAN data including address, contact info, and profile.
PAN Advanced API POST /v4/pan-advanced pan_advanced Standard government database verification for PAN validity and taxpayer status.
Bank Verify (Penny Drop - v5) POST /v5/bank-verify-pd bank_verify_pd, bank_verify_v5, bank_account Verifies bank account using account number and IFSC via Penny Drop; returns validity and account holder name.
Bank Verification (Full Details - v4) POST /v4/bank-verify bank_account (with mode: 'v4') Penny drop routing for account holder name, MICR, IFSC, and branch details.
Fetch GST By PAN POST /v4/fetch-gst gst_by_pan, fetch_gst Retrieves all registered GSTIN entities associated with a business PAN.
Fetch MSME By PAN POST /v4/msme-pan msme, msme_by_pan, udyam Retrieves Udyam registration number and enterprise details linked to a PAN.
GST Verification (v5) POST /v5/gst-verify gstin, gst, gst_verify Verifies single GSTIN and returns legal business name and active status.

4. API Reference & Sample Requests

Function 1: Pan Verification (v5 Recommended)

  • Engine Request:
curl -X POST http://localhost:8092/api/verify/ \
  -H "Content-Type: application/json" \
  -d '{
    "document_type": "pan",
    "data": {
      "pan": "ABCDE1234F"
    }
  }'
  • Direct Upstream cURL:
curl --location 'https://apihub.services/v5/pan-verify' \
  --header 'X-Client-Api-ID: CAPI-YYR0YJIE0VMTDENY' \
  --header 'X-Client-Api-Secret: s24Ts9wFsgl64mFzA61OqG0RDLRs2HFCpmOZBmqs' \
  --header 'Content-Type: application/json' \
  --data '{"pan": "ABCDE1234F"}'
  • Sample Engine Response (HTTP 200):
{
  "reference_id": "8a7c29e1-2244-48f1-9c6a-4933a1e94b21",
  "is_success": true,
  "status": "SUCCESS",
  "document_type": "pan",
  "successful_vendor": "codeplus",
  "data": {
    "document_type": "PAN",
    "pan": "ABCDE1234F",
    "pan_type": "Individual",
    "full_name": "RAHUL KUMAR",
    "first_name": "RAHUL",
    "middle_name": null,
    "last_name": "KUMAR",
    "gender": "male",
    "dob": "15/06/1995",
    "aadhaar_number": "XXXXXXXX1234",
    "aadhaar_linked": true,
    "address_details": {
      "building_name": "12/45",
      "locality": "Central Area",
      "street_name": "MG Road",
      "pincode": "641001",
      "city": "COIMBATORE",
      "state": "Tamil Nadu",
      "country": "India"
    },
    "service": "PAN_VERIFICATION",
    "result_code": 101,
    "client_ref_num": "REQ_1787136465034_demo12345",
    "provider_transaction_id": "TXN_1787136465045_demo12345",
    "transaction_id": "TXN_1787136465045_demo12345",
    "request_id": "REQ_1787136465034_demo12345",
    "timestamp": "2026-08-19T10:47:45.735Z"
  },
  "attempts_count": 1,
  "attempts": [
    {
      "attempt_number": 1,
      "vendor_name": "codeplus",
      "is_success": true,
      "status": "SUCCESS",
      "latency_ms": 310.2
    }
  ],
  "error_message": null,
  "total_latency_ms": 315.4
}

Function 2: Detailed PAN API

  • Engine Request:
curl -X POST http://localhost:8092/api/verify/ \
  -H "Content-Type: application/json" \
  -d '{
    "document_type": "pan_detailed",
    "data": {
      "pan_number": "ABCDE1234F"
    }
  }'
  • Direct Upstream cURL:
curl --location 'https://apihub.services/v4/pan-detailed' \
  --header 'X-Client-Api-ID: CAPI-YYR0YJIE0VMTDENY' \
  --header 'X-Client-Api-Secret: s24Ts9wFsgl64mFzA61OqG0RDLRs2HFCpmOZBmqs' \
  --header 'Content-Type: application/json' \
  --data '{"pan_number": "ABCDE1234F"}'
  • Sample Upstream Response:
{
  "request_id": "7f3a1c92-5b84-4d21-a7e6-91c2f0d84b56",
  "transaction_id": "b6e8d4a1-2c73-49f5-9a10-5f7c3e821d64",
  "status": 200,
  "data": {
    "code": "1000",
    "message": "Valid PAN.",
    "pan_data": {
      "document_type": "PAN",
      "document_id": "ABCDE1234F",
      "name": "RAHUL KUMAR",
      "first_name": "RAHUL",
      "last_name": "KUMAR",
      "category": "P",
      "date_of_birth": "1995-06-15",
      "masked_aadhaar_number": "XXXXXXXX1234",
      "address_data": {
        "line_1": "12/45",
        "line_2": "MG Road",
        "street": "Central Area",
        "city": "COIMBATORE",
        "state": "TAMIL NADU",
        "pincode": "641001"
      },
      "email": "ra******@example.com",
      "phone": "98XXXXXX10",
      "gender": "MALE",
      "aadhaar_linked": true,
      "taxpayer_profile": true
    }
  }
}

Function 3: PAN Advanced API

  • Engine Request:
curl -X POST http://localhost:8092/api/verify/ \
  -H "Content-Type: application/json" \
  -d '{
    "document_type": "pan_advanced",
    "data": {
      "pan": "ABCDE1234F"
    }
  }'
  • Direct Upstream cURL:
curl --location 'https://apihub.services/v4/pan-advanced' \
  --header 'X-Client-Api-ID: CAPI-YYR0YJIE0VMTDENY' \
  --header 'X-Client-Api-Secret: s24Ts9wFsgl64mFzA61OqG0RDLRs2HFCpmOZBmqs' \
  --header 'Content-Type: application/json' \
  --data '{"pan": "ABCDE1234F"}'
  • Sample Upstream Response:
{
  "request_id": "8a42f1c7-63d9-4e15-b820-7c91a5d34628",
  "transaction_id": "d5b73e91-2a46-4c08-9f61-83e2b7a51439",
  "status": 200,
  "data": {
    "code": "1000",
    "message": "Valid PAN.",
    "pan_data": {
      "document_type": "PAN",
      "document_id": "ABCDE1234F",
      "name": "RAHUL KUMAR",
      "first_name": "RAHUL",
      "last_name": "KUMAR",
      "category": "P",
      "category_type": "Individual",
      "is_individual": true,
      "individual_tax_compliance_status": "Operative",
      "aadhaar_linked": true
    }
  }
}

Function 4: Bank Verify (Penny Drop - v5 Recommended)

The Bank Account Verification – PD API verifies a bank account using the account number and IFSC code via automated penny drop routing. It checks whether the account is valid and active, and returns the account holder name and verified bank account details.

  • Engine Request:
curl -X POST http://localhost:8092/api/verify/ \
  -H "Content-Type: application/json" \
  -d '{
    "document_type": "bank_verify_pd",
    "data": {
      "account_number": "123456787270",
      "ifsc": "UTIB0000373"
    }
  }'

(Note: You can also use document_type: "bank_account", which automatically defaults to v5 Penny Drop with fallback to v4).

  • Direct Upstream cURL:
curl --location 'https://apihub.services/v5/bank-verify-pd' \
  --header 'X-Client-Api-ID: CAPI-YYR0YJIE0VMTDENY' \
  --header 'X-Client-Api-Secret: your_client_api_secret' \
  --header 'Content-Type: application/json' \
  --data '{
    "account_number": "123456787270",
    "ifsc": "UTIB0000373"
  }'
  • Client Input Parameters:
Parameter Type Description
account_number String Bank account number to be verified.
ifsc String 11-character IFSC code of the bank branch.
  • Upstream Success Response (HTTP 200):
{
  "status": "success",
  "result": {
    "failure_reason": null,
    "account_number": "********7270",
    "user": null,
    "is_valid": true,
    "account_holder_name": "MANOJ PRASAD",
    "account_ifsc": "UTIB0000373",
    "npci_error_code": null
  },
  "tranx_id": "9eeb9d58-04f8-4f8b-9608-99731850993f",
  "timestamp": "2026-05-22T05:10:43.561554+00:00",
  "chargeble": "true",
  "user_consent": "true"
}
  • Engine Unified Response (HTTP 200):
{
  "reference_id": "9eeb9d58-04f8-4f8b-9608-99731850993f",
  "is_success": true,
  "status": "SUCCESS",
  "document_type": "bank_verify_pd",
  "successful_vendor": "codeplus",
  "data": {
    "document_type": "BANK_ACCOUNT",
    "verification_mode": "penny_drop_v5",
    "account_number": "123456787270",
    "masked_account_number": "********7270",
    "ifsc": "UTIB0000373",
    "account_ifsc": "UTIB0000373",
    "beneficiary_name": "MANOJ PRASAD",
    "account_holder_name": "MANOJ PRASAD",
    "is_valid": true,
    "account_exists": true,
    "failure_reason": null,
    "npci_error_code": null,
    "tranx_id": "9eeb9d58-04f8-4f8b-9608-99731850993f",
    "timestamp": "2026-05-22T05:10:43.561554+00:00",
    "chargeble": "true",
    "user_consent": "true"
  },
  "attempts_count": 1,
  "attempts": [
    {
      "attempt_number": 1,
      "vendor_name": "codeplus",
      "is_success": true,
      "status": "SUCCESS",
      "latency_ms": 380.2
    }
  ]
}

Function 4B: Bank Verification (Full Details - v4 Legacy)

curl -X POST http://localhost:8092/api/verify/ \
  -H "Content-Type: application/json" \
  -d '{
    "document_type": "bank_account",
    "data": {
      "account_number": "123456789012",
      "ifsc": "HDFC0001234"
    }
  }'
  • Direct Upstream cURL:
curl --location 'https://apihub.services/v4/bank-verify' \
  --header 'X-Client-Api-ID: CAPI-YYR0YJIE0VMTDENY' \
  --header 'X-Client-Api-Secret: s24Ts9wFsgl64mFzA61OqG0RDLRs2HFCpmOZBmqs' \
  --header 'Content-Type: application/json' \
  --data '{
    "account_number": "123456789012",
    "ifsc": "HDFC0001234"
  }'
  • Sample Engine Response (HTTP 200):
{
  "reference_id": "4b5d21a9-9941-4198-89c0-e74bf1a998bc",
  "is_success": true,
  "status": "SUCCESS",
  "document_type": "bank_account",
  "successful_vendor": "codeplus",
  "data": {
    "document_type": "BANK_ACCOUNT",
    "account_number": "123456789012",
    "ifsc": "HDFC0001234",
    "beneficiary_name": "PRIYA SHARMA",
    "micr": "641240002",
    "bank_name": "HDFC BANK",
    "branch": "MAIN BRANCH",
    "city": "COIMBATORE",
    "state": "TAMIL NADU",
    "pincode": "641001",
    "account_exists": true
  },
  "attempts_count": 1,
  "attempts": [
    {
      "attempt_number": 1,
      "vendor_name": "codeplus",
      "is_success": true,
      "status": "SUCCESS",
      "latency_ms": 420.5
    }
  ]
}

Function 5: Fetch GST By PAN

  • Engine Request:
curl -X POST http://localhost:8092/api/verify/ \
  -H "Content-Type: application/json" \
  -d '{
    "document_type": "gst_by_pan",
    "data": {
      "pan": "ABCDE1234F"
    }
  }'
  • Direct Upstream cURL:
curl --location 'https://apihub.services/v4/fetch-gst' \
  --header 'X-Client-Api-ID: CAPI-YYR0YJIE0VMTDENY' \
  --header 'X-Client-Api-Secret: s24Ts9wFsgl64mFzA61OqG0RDLRs2HFCpmOZBmqs' \
  --header 'Content-Type: application/json' \
  --data '{"pan": "ABCDE1234F"}'
  • Sample Upstream Response:
{
  "request_id": "b27c9087-f061-4d38-b7aa-96498f8e667e",
  "status": 200,
  "data": {
    "code": "1002",
    "message": "Found 3 records",
    "results": [
      {
        "document_type": "GSTIN",
        "document_id": "20AXXXXXXXXXXX",
        "status": "Active",
        "state": "Jharkhand",
        "state_code": "20"
      },
      {
        "document_type": "GSTIN",
        "document_id": "27AXXXXXXXXXXX",
        "status": "Active",
        "state": "Maharashtra",
        "state_code": "27"
      },
      {
        "document_type": "GSTIN",
        "document_id": "29AXXXXXXXXXXX",
        "status": "Active",
        "state": "Karnataka",
        "state_code": "29"
      }
    ]
  }
}

Function 6: Fetch MSME By PAN

  • Engine Request:
curl -X POST http://localhost:8092/api/verify/ \
  -H "Content-Type: application/json" \
  -d '{
    "document_type": "msme",
    "data": {
      "pan": "ABCDE1234F",
      "detailed_response": true
    }
  }'
  • Direct Upstream cURL:
curl --location 'https://apihub.services/v4/msme-pan' \
  --header 'X-Client-Api-ID: CAPI-YYR0YJIE0VMTDENY' \
  --header 'X-Client-Api-Secret: s24Ts9wFsgl64mFzA61OqG0RDLRs2HFCpmOZBmqs' \
  --header 'Content-Type: application/json' \
  --data '{"pan": "ABCDE1234F", "detailed_response": true}'
  • Sample Engine Response (No Record Found):
{
  "reference_id": "c19b38fa-0123-4567-89ab-cdef01234567",
  "is_success": true,
  "status": "SUCCESS",
  "document_type": "msme",
  "successful_vendor": "codeplus",
  "data": {
    "document_type": "MSME",
    "pan": "ABCDE1234F",
    "has_msme": false,
    "code": "1011",
    "message": "No record found.",
    "udyam_data": {
      "code": "1011",
      "message": "No record found."
    }
  }
}

Function 7: GST Verification (v5)

  • Engine Request:
curl -X POST http://localhost:8092/api/verify/ \
  -H "Content-Type: application/json" \
  -d '{
    "document_type": "gstin",
    "data": {
      "gst_number": "27ABCDE1234F1Z5"
    }
  }'
  • Direct Upstream cURL:
curl --location 'https://apihub.services/v5/gst-verify' \
  --header 'X-Client-Api-ID: CAPI-YYR0YJIE0VMTDENY' \
  --header 'X-Client-Api-Secret: s24Ts9wFsgl64mFzA61OqG0RDLRs2HFCpmOZBmqs' \
  --header 'Content-Type: application/json' \
  --data '{"gst_number": "27ABCDE1234F1Z5"}'
  • Sample Engine Response (HTTP 200):
{
  "reference_id": "5f6e7d8c-9b0a-1122-3344-556677889900",
  "is_success": true,
  "status": "SUCCESS",
  "document_type": "gstin",
  "successful_vendor": "codeplus",
  "data": {
    "document_type": "GSTIN",
    "gst_number": "27ABCDE1234F1Z5",
    "legal_name": "ABCDE PRIVATE LIMITED",
    "registration_status": "ACTIVE",
    "service": "GST_VERIFICATION",
    "message": "GST verification completed"
  },
  "attempts_count": 1,
  "attempts": [
    {
      "attempt_number": 1,
      "vendor_name": "codeplus",
      "is_success": true,
      "status": "SUCCESS",
      "latency_ms": 285.6
    }
  ]
}

5. Transaction Audit API

Retrieve the complete historical audit log, raw responses, and latency for any transaction:

  • Endpoint: GET /api/transactions/<uuid:reference_id>/

  • cURL:

curl -X GET http://localhost:8092/api/transactions/8a7c29e1-2244-48f1-9c6a-4933a1e94b21/
  • Response:
{
  "reference_id": "8a7c29e1-2244-48f1-9c6a-4933a1e94b21",
  "document_type": "pan",
  "status": "SUCCESS",
  "successful_vendor": "codeplus",
  "final_data": { ... },
  "response_payload": { ... },
  "attempts_count": 1,
  "total_latency_ms": 315.4,
  "created_at": "2026-10-15T19:58:00Z",
  "attempts": [
    {
      "attempt_number": 1,
      "vendor_name": "codeplus",
      "status": "SUCCESS",
      "is_success": true,
      "error_code": null,
      "error_message": null,
      "latency_ms": 310.2,
      "created_at": "2026-10-15T19:58:00Z"
    }
  ]
}