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
```json
{
  "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
```json
{
  "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:
```env
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:**
```json
{
  "pan": "ABCDE1234A",
  "reason": "KYC verification" // optional
}
```

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

## Getting Your API Key

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

```bash
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:
```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 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):**
   ```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:

```bash
npm run migrate
```

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