Verify_India_API/SETU_PAN_INTEGRATION.md

Setu PAN Verification Integration Guide

Overview

This document explains how the Setu PAN verification API integration works and how it's implemented in this codebase.

How Setu API Works

1. API Endpoint

• URL: https://dg-sandbox.setu.co/api/verify/pan
• Method: POST
• Content-Type: application/json

2. Authentication Headers

Setu API requires three custom headers for authentication:

• x-client-id: Your Setu client ID (UUID format)
• x-client-secret: Your Setu client secret
• x-product-instance-id: Your Setu product instance ID (UUID format)

3. Request Body

{
  "pan": "ABCDE1234A",
  "consent": "Y",
  "reason": "Reason for verifying PAN set by the developer"
}

Fields:

• pan (required): 10-character PAN number (format: 5 letters + 4 digits + 1 letter)
• consent (required): Must be "Y" to indicate user consent
• reason (required): Reason for verification

4. Response Format

{
  "id": "0e370877-f860-4b5c-858b-42aebfea4879",
  "message": "PAN is valid.",
  "data": {
    "full_name": "Kumar Gaurav Rathod",
    "first_name": "Gaurav",
    "middle_name": "Kumar",
    "last_name": "Rathod",
    "category": "Individual or Person",
    "aadhaar_seeding_status": "LINKED"
  },
  "traceId": "1-69437d63-75ac46a51036ab2233854e23"
}

Implementation Details

1. Environment Variables

Add these to your .env file:

PAN_PROVIDER_URL=https://dg-sandbox.setu.co/api/verify/pan
PAN_CLIENT_ID=292c6e76-dabf-49c4-8e48-90fba2916673
PAN_CLIENT_SECRET=7IZMe9zvoBBuBukLiCP7n4KLwSOy11oP
PAN_PRODUCT_INSTANCE_ID=439244ff-114e-41a8-ae74-a783f160622d

2. Service Layer (src/services/panService.js)

The service:

• Validates PAN format (10 characters: 5 letters, 4 digits, 1 letter)
• Checks Redis cache first to avoid duplicate API calls
• Calls Setu API with proper headers and request body
• Formats the response data
• Stores the result in PostgreSQL database
• Caches the result for 24 hours

3. Database Storage

All PAN verifications are stored in the pan_verifications table with the following fields:

• pan: The PAN number
• full_name, first_name, middle_name, last_name: Name components
• category: PAN category (Individual, Company, etc.)
• aadhaar_seeding_status: Aadhaar linking status
• status: VALID or INVALID
• setu_response_id: Setu's response ID
• setu_trace_id: Setu's trace ID for debugging
• setu_message: Message from Setu API
• requested_by: User ID who made the request
• requested_at: Timestamp of the request

4. API Endpoint

POST /v1/pan/verify

Headers:

Content-Type: application/json
X-API-Key: your-api-key-here

Request Body:

{
  "pan": "ABCDE1234A",
  "reason": "KYC verification" // optional
}

Response:

{
  "success": true,
  "data": {
    "pan": "ABCDE1234A",
    "full_name": "Kumar Gaurav Rathod",
    "first_name": "Gaurav",
    "middle_name": "Kumar",
    "last_name": "Rathod",
    "category": "Individual or Person",
    "aadhaar_seeding_status": "LINKED",
    "status": "VALID",
    "setu_response_id": "0e370877-f860-4b5c-858b-42aebfea4879",
    "setu_trace_id": "1-69437d63-75ac46a51036ab2233854e23",
    "setu_message": "PAN is valid."
  },
  "meta": {
    "request_id": "req_pan_1234567890",
    "credits_used": 1,
    "credits_remaining": 999,
    "source": "setu-pan"
  },
  "timestamp": "2024-01-01T00:00:00.000Z"
}

Getting Your API Key

Before testing, you need an API key. The easiest way is to run:

cd verify-india-api
npm run create-test-key

This will create and display a test API key. Copy it and use it in your requests.

Alternative: Sign up for a new account:

curl -X POST http://localhost:3000/v1/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "your-email@example.com",
    "password": "your-password-123",
    "company_name": "Your Company"
  }'

The response includes your api_key - save it immediately!

See HOW_TO_GET_API_KEY.md for detailed instructions.

Testing with Postman

1. Set up the request:

   • Method: POST
   • URL: http://localhost:3000/v1/pan/verify
   • Headers:
     • Content-Type: application/json
     • X-API-Key: your-api-key (get it using the method above)

2. Request Body (JSON):

   {
     "pan": "ABCDE1234A",
     "reason": "Testing PAN verification"
   }
   

3. Expected Response:

   • Status: 200 OK
   • Body: JSON with PAN verification details

Error Handling

The implementation handles various error scenarios:

• Invalid PAN format: Returns 400 with INVALID_PAN_FORMAT error
• Missing credentials: Returns 500 with CONFIGURATION_ERROR
• Setu API errors: Returns the status code from Setu with appropriate error message
• Timeout errors: Returns 504 with PROVIDER_TIMEOUT
• Network errors: Returns 500 with VERIFICATION_FAILED

Key Features

1. Caching: Results are cached in Redis for 24 hours to reduce API calls
2. Database Persistence: All verifications are stored in PostgreSQL
3. Error Handling: Comprehensive error handling with proper status codes
4. Validation: PAN format validation before making API calls
5. Logging: API calls are logged for analytics

Migration

After updating the code, run the database migration to update the pan_verifications table:

npm run migrate

This will add the new fields to store all Setu response data.