Verify_India_API/README.md

VerifyIndia API

REST APIs for Indian data verification:

• IFSC Lookup
• Pincode Lookup
• GST Verification
• PAN Verification
• Bank Account Verification

Tech Stack

• Runtime: Node.js v20+
• Framework: Express.js
• Database: PostgreSQL
• Cache: Redis
• Auth: API Keys + JWT

Setup

1. Install dependencies:

npm install

2. Create a .env file with your settings (replace <PASSWORD>):

PORT=3000
NODE_ENV=development
DATABASE_URL=postgres://india_api_2025:<PASSWORD>@localhost:5434/india-api-tech4biz

# Setu API Credentials for PAN Verification
PAN_PROVIDER_URL=https://dg-sandbox.setu.co/api/verify/pan
PAN_CLIENT_ID=your-client-id-here
PAN_CLIENT_SECRET=your-client-secret-here
PAN_PRODUCT_INSTANCE_ID=your-product-instance-id-here

# optional: JWT_SECRET, REDIS_URL, etc.

3. Start the server:

npm run dev

Project Structure

verify-india-api/
├── src/
│   ├── index.js
│   ├── routes/
│   ├── middleware/
│   ├── services/
│   ├── database/
│   └── cache/
├── data/
├── package.json
├── .env.example
└── README.md

Getting Your API Key

Quick Method (For Testing)

Run the test API key creation script:

npm run create-test-key

This will create a test API key and display it in the console.

Sign Up Method (For Production)

Create an account to get an API key:

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 will include your api_key - save it immediately as it's only shown once!

API Key Format

API keys start with vf_live_ or vf_test_:

vf_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
vf_test_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Using API Key

Send it in the request header:

X-API-Key: vf_live_xxx

or

x-api-key: vf_live_xxx

See HOW_TO_GET_API_KEY.md for detailed instructions.

PAN Verification (Setu Integration)

PAN verification is powered by Setu API. To use this feature:

1. Get your Setu API credentials:

   • PAN_PROVIDER_URL: Setu API endpoint (default: https://dg-sandbox.setu.co/api/verify/pan)
   • PAN_CLIENT_ID: Your Setu client ID (UUID format)
   • PAN_CLIENT_SECRET: Your Setu client secret
   • PAN_PRODUCT_INSTANCE_ID: Your Setu product instance ID (UUID format)

2. Add them to your .env file (see Setup section above)

3. Verify a PAN:

curl -X POST http://localhost:3000/v1/pan/verify \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "pan": "ABCDE1234A",
    "reason": "KYC verification for account opening"
  }'

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"
}

Response Format

Success:

{
  "success": true,
  "data": {},
  "meta": {
    "request_id": "req_xxx",
    "credits_used": 1,
    "credits_remaining": 999
  }
}

Error:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Description"
  }
}