> ## Documentation Index
> Fetch the complete documentation index at: https://docs.txncheck.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference Overview

> Complete reference for all TxnCheck API endpoints

# API Reference

This section provides detailed documentation for all TxnCheck API endpoints.

## Base URL

```
https://api.txncheck.in/api/v1
```

## Authentication

All endpoints require an API key in the `X-API-Key` header:

```bash theme={null}
curl -H "X-API-Key: fb_your_api_key" https://api.txncheck.in/api/v1/requests/{id}
```

## Endpoints

### Verification Endpoints

| Method | Endpoint                       | Description                                    |
| ------ | ------------------------------ | ---------------------------------------------- |
| `POST` | `/bank-verification-pennyless` | **NEW** Instant bank account verification (V2) |
| `POST` | `/kyc-by-mobile`               | Get KYC data by mobile number                  |
| `POST` | `/vpa-chargeback-check`        | Check VPAs against blocklist                   |
| `POST` | `/full-check`                  | Full verification (UPI + KYC + Chargeback)     |
| `POST` | `/bulk/vpa-chargeback-check`   | Bulk check VPAs against blocklist              |
| `POST` | `/upi-by-mobile`               | ~~Get UPI VPAs~~ (Deprecated)                  |

### Request Status

| Method | Endpoint         | Description                    |
| ------ | ---------------- | ------------------------------ |
| `GET`  | `/requests/{id}` | Get request status and results |

## Request Format

All POST requests should include:

| Header         | Value                 | Required           |
| -------------- | --------------------- | ------------------ |
| `X-API-Key`    | Your API key          | Yes                |
| `Content-Type` | `application/json`    | Yes                |
| `X-Timestamp`  | Unix timestamp (ms)   | If signing enabled |
| `X-Signature`  | HMAC-SHA256 signature | If signing enabled |

### Common Parameters

All verification endpoints support the following optional parameter:

| Parameter | Type    | Default | Description                                                                                                       |
| --------- | ------- | ------- | ----------------------------------------------------------------------------------------------------------------- |
| `async`   | boolean | `true`  | If `true`, request is queued and result delivered via webhook. If `false`, wait synchronously (up to 30 seconds). |

## Response Format

### Async Mode - Accepted Response (202)

When a verification request is accepted in async mode (default):

```json theme={null}
{
  "statusCode": 202,
  "message": "Request accepted and queued for processing",
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "QUEUED"
}
```

### Sync Mode - Success Response (200)

When using `async: false`, results are returned directly:

```json theme={null}
{
  "statusCode": 200,
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "method": "upi-by-mobile",
  "status": "COMPLETED",
  "result": { ... },
  "createdAt": "2025-01-11T10:30:00.000Z",
  "completedAt": "2025-01-11T10:30:05.000Z"
}
```

### Status Polling Response (200)

When retrieving request status via GET:

```json theme={null}
{
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "method": "upi-by-mobile",
  "status": "COMPLETED",
  "result": { ... },
  "webhookStatus": "SENT",
  "createdAt": "2025-01-11T10:30:00.000Z",
  "completedAt": "2025-01-11T10:30:05.000Z"
}
```

### Error Response

```json theme={null}
{
  "statusCode": 400,
  "message": "Validation error message",
  "error": "Bad Request"
}
```

## HTTP Status Codes

| Status | Description                                               |
| ------ | --------------------------------------------------------- |
| `200`  | Success - Request completed (sync mode or status polling) |
| `202`  | Accepted - Request queued for processing (async mode)     |
| `400`  | Bad Request - Invalid parameters                          |
| `401`  | Unauthorized - Invalid or missing API key                 |
| `402`  | Payment Required - Insufficient balance                   |
| `403`  | Forbidden - Method not allowed for this merchant          |
| `404`  | Not Found - Request not found                             |
| `408`  | Request Timeout - Sync request exceeded 30-second timeout |
| `429`  | Too Many Requests - Rate limit exceeded                   |
| `500`  | Internal Server Error                                     |

## Request Statuses

| Status       | Description                                     |
| ------------ | ----------------------------------------------- |
| `QUEUED`     | Request received and waiting for processing     |
| `PROCESSING` | Request is being processed                      |
| `COMPLETED`  | Request completed successfully                  |
| `FAILED`     | Request failed (check error details)            |
| `PARTIAL`    | Request partially completed (some steps failed) |

## Webhook Statuses

| Status     | Description                               |
| ---------- | ----------------------------------------- |
| `PENDING`  | Webhook not yet sent                      |
| `SENT`     | Webhook delivered successfully            |
| `RETRYING` | Webhook delivery failed, retrying         |
| `FAILED`   | Webhook delivery failed after all retries |

## Rate Limits

API requests are rate-limited to ensure fair usage:

| Endpoint Type          | Limit               |
| ---------------------- | ------------------- |
| Verification endpoints | 100 requests/minute |
| Status endpoints       | 300 requests/minute |
| Bulk endpoints         | 10 requests/minute  |

<Note>
  Rate limits are applied per API key. If you exceed the limit, you'll receive a `429 Too Many Requests` response.
</Note>

## Mobile Number Format

All mobile numbers must be in Indian international format:

```
+91XXXXXXXXXX
```

Example: `+919876543210`

## VPA Format

VPA (Virtual Payment Address) must follow the format:

```
username@bank
```

Examples:

* `johndoe@upi`
* `9876543210@paytm`
* `user.name@okicici`

## Endpoint Details

<CardGroup cols={2}>
  <Card title="UPI by Mobile" icon="mobile" href="/api-reference/upi-by-mobile">
    Get UPI VPAs linked to a mobile number
  </Card>

  <Card title="KYC by Mobile" icon="id-card" href="/api-reference/kyc-by-mobile">
    Get KYC data by mobile number
  </Card>

  <Card title="VPA Chargeback Check" icon="shield" href="/api-reference/vpa-chargeback-check">
    Check VPAs against blocklist
  </Card>

  <Card title="Full Check" icon="check-double" href="/api-reference/full-check">
    Comprehensive verification
  </Card>

  <Card title="Bulk VPA Check" icon="layer-group" href="/api-reference/bulk-vpa-check">
    Bulk blocklist check
  </Card>

  <Card title="Request Status" icon="clock" href="/api-reference/request-status">
    Get request status
  </Card>
</CardGroup>