Quick Start

This guide will help you make your first verification request using the TxnCheck API.

Prerequisites

Obtain your API key

API keys are provided by the TxnCheck team during merchant onboarding. Contact your account manager or visit your dashboard to request access.

Choose your execution mode

TxnCheck supports two modes:

Async mode (default): Requests are queued, results delivered via webhooks or polling
Sync mode: Wait for results directly in the response (up to 30 seconds)

Merchant accounts and API keys are created by the TxnCheck team. Self-registration is not available.

Make Your First Request

Let’s verify a mobile number to get associated UPI VPAs. You can choose between async and sync modes.

Async Mode (Default)
Sync Mode

Async mode queues your request and delivers results via webhooks or polling.

curl -X POST "https://api.txncheck.in/api/v1/upi-by-mobile" \
  -H "X-API-Key: fb_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "mobile": "+919876543210"
  }'

import requests

response = requests.post(
    "https://api.txncheck.in/api/v1/upi-by-mobile",
    headers={
        "X-API-Key": "fb_your_api_key_here",
        "Content-Type": "application/json"
    },
    json={"mobile": "+919876543210"}
)
print(response.json())

const axios = require('axios');

const response = await axios.post(
  'https://api.txncheck.in/api/v1/upi-by-mobile',
  { mobile: '+919876543210' },
  {
    headers: {
      'X-API-Key': 'fb_your_api_key_here',
      'Content-Type': 'application/json'
    }
  }
);
console.log(response.data);

Response (202 Accepted)

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

Sync mode waits for the result and returns it directly in the response. Set async: false in your request.

curl -X POST "https://api.txncheck.in/api/v1/upi-by-mobile" \
  -H "X-API-Key: fb_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "mobile": "+919876543210",
    "async": false
  }'

import requests

response = requests.post(
    "https://api.txncheck.in/api/v1/upi-by-mobile",
    headers={
        "X-API-Key": "fb_your_api_key_here",
        "Content-Type": "application/json"
    },
    json={"mobile": "+919876543210", "async": False}
)
print(response.json())

const axios = require('axios');

const response = await axios.post(
  'https://api.txncheck.in/api/v1/upi-by-mobile',
  { mobile: '+919876543210', async: false },
  {
    headers: {
      'X-API-Key': 'fb_your_api_key_here',
      'Content-Type': 'application/json'
    }
  }
);
console.log(response.data);

Response (200 OK)

{
  "statusCode": 200,
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "method": "upi-by-mobile",
  "status": "COMPLETED",
  "result": {
    "name": "JOHN DOE",
    "upi": ["johndoe@upi", "9876543210@paytm"],
    "status": "1"
  },
  "createdAt": "2025-01-11T10:30:00.000Z",
  "completedAt": "2025-01-11T10:30:05.000Z"
}

Sync mode has a 30-second timeout. If processing takes longer, you’ll receive a 408 Request Timeout error.

Get Results (Async Mode Only)

If you used async mode, results are delivered via webhooks (recommended) or by polling the status endpoint.

Option 1: Webhooks (Recommended)

If you have a webhook configured, you’ll receive the results automatically:

{
  "event": "request.completed",
  "timestamp": "2025-01-11T10:30:05.000Z",
  "data": {
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "method": "upi-by-mobile",
    "status": "COMPLETED",
    "result": {
      "name": "JOHN DOE",
      "upi": [
        "johndoe@upi",
        "9876543210@paytm",
        "9876543210@ybl"
      ],
      "status": "1"
    },
    "completedAt": "2025-01-11T10:30:05.000Z"
  }
}

Option 2: Polling

Poll the request status endpoint until the status is COMPLETED, FAILED, or PARTIAL:

curl -X GET "https://api.txncheck.in/api/v1/requests/550e8400-e29b-41d4-a716-446655440000" \
  -H "X-API-Key: fb_your_api_key_here"

import time
import requests

request_id = "550e8400-e29b-41d4-a716-446655440000"
headers = {"X-API-Key": "fb_your_api_key_here"}

while True:
    response = requests.get(
        f"https://api.txncheck.in/api/v1/requests/{request_id}",
        headers=headers
    )
    data = response.json()
    
    if data["status"] in ["COMPLETED", "FAILED", "PARTIAL"]:
        print(data)
        break
    
    time.sleep(2)  # Wait 2 seconds before next poll

async function pollForResult(requestId) {
  const headers = { 'X-API-Key': 'fb_your_api_key_here' };
  
  while (true) {
    const response = await axios.get(
      `https://api.txncheck.in/api/v1/requests/${requestId}`,
      { headers }
    );
    
    if (['COMPLETED', 'FAILED', 'PARTIAL'].includes(response.data.status)) {
      return response.data;
    }
    
    await new Promise(resolve => setTimeout(resolve, 2000));
  }
}

const result = await pollForResult('550e8400-e29b-41d4-a716-446655440000');
console.log(result);

Completed Response

{
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "method": "upi-by-mobile",
  "status": "COMPLETED",
  "result": {
    "name": "JOHN DOE",
    "upi": [
      "johndoe@upi",
      "9876543210@paytm",
      "9876543210@ybl"
    ],
    "status": "1"
  },
  "webhookStatus": "SENT",
  "createdAt": "2025-01-11T10:30:00.000Z",
  "completedAt": "2025-01-11T10:30:05.000Z"
}

Understanding the Response

Field	Description
`requestId`	Unique identifier for tracking the request
`status`	Current status: `QUEUED`, `PROCESSING`, `COMPLETED`, `FAILED`, `PARTIAL`
`result`	Verification result data (when completed)
`result.name`	Name associated with the mobile number
`result.upi`	Array of UPI VPAs linked to the mobile number
`result.status`	`"1"` indicates data was found

What’s Next?

Set up Webhooks

Receive real-time notifications when verifications complete

Explore All Methods

Learn about KYC verification, VPA checks, and more

Test Your Integration

Use test mode to validate your implementation

Error Handling

Learn how to handle API errors

Common Issues

401 Unauthorized

Make sure you’re including the X-API-Key header with a valid API key.

400 Bad Request - Invalid mobile format

Mobile numbers must be in Indian international format: +91 followed by 10 digits.Correct: +919876543210Incorrect: 9876543210, +1-987-654-3210

403 Forbidden - Method not allowed

Your API key may not have access to this verification method. Contact your account manager to enable it.

402 Payment Required

Your account balance is insufficient. Top up your balance in the merchant dashboard.

​Quick Start

​Prerequisites

​Make Your First Request

​Response (202 Accepted)

​Response (200 OK)

​Get Results (Async Mode Only)

​Option 1: Webhooks (Recommended)

​Option 2: Polling

​Completed Response

​Understanding the Response

​What’s Next?

Set up Webhooks

Explore All Methods

Test Your Integration

Error Handling

​Common Issues

Quick Start

Prerequisites

Make Your First Request

Response (202 Accepted)

Response (200 OK)

Get Results (Async Mode Only)

Option 1: Webhooks (Recommended)

Option 2: Polling

Completed Response

Understanding the Response

What’s Next?

Common Issues