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 | /upi-by-mobile | Get UPI VPAs linked to a mobile number |
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 |
Request Status
| Method | Endpoint | Description |
|---|
GET | /requests/{id} | Get request status and results |
| 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). |
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.
+919876543210
VPA (Virtual Payment Address) must follow the format:
Examples:
johndoe@upi9876543210@paytmuser.name@okicici
Endpoint Details
