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:
```bash
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:
```bash
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:
```bash
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:
```bash
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:
```bash
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:**
```json
{
  "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:**
```json
{
  "success": true,
  "data": {},
  "meta": {
    "request_id": "req_xxx",
    "credits_used": 1,
    "credits_remaining": 999
  }
}
```

**Error:**
```json
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Description"
  }
}
```