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:

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):

{
  "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:

{
  "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:

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

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

Rate limits are applied per API key. If you exceed the limit, you’ll receive a 429 Too Many Requests response.

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

UPI by Mobile

Get UPI VPAs linked to a mobile number

KYC by Mobile

Get KYC data by mobile number

VPA Chargeback Check

Check VPAs against blocklist

Full Check

Comprehensive verification

Bulk VPA Check

Bulk blocklist check

Request Status

Get request status

​API Reference

​Base URL

​Authentication

​Endpoints

​Verification Endpoints

​Request Status

​Request Format

​Common Parameters

​Response Format

​Async Mode - Accepted Response (202)

​Sync Mode - Success Response (200)

​Status Polling Response (200)

​Error Response

​HTTP Status Codes

​Request Statuses

​Webhook Statuses

​Rate Limits

​Mobile Number Format

​VPA Format

​Endpoint Details

UPI by Mobile

KYC by Mobile

VPA Chargeback Check

Full Check

Bulk VPA Check

Request Status

API Reference

Base URL

Authentication

Endpoints

Verification Endpoints

Request Status

Request Format

Common Parameters

Response Format

Async Mode - Accepted Response (202)

Sync Mode - Success Response (200)

Status Polling Response (200)

Error Response

HTTP Status Codes

Request Statuses

Webhook Statuses

Rate Limits

Mobile Number Format

VPA Format

Endpoint Details