Skip to main content

​
Testing Guide

This guide covers how to test your TxnCheck API integration effectively before deploying to production.

​
Test Environment

TxnCheck provides a test environment for development and testing. Contact your account manager to obtain test API credentials.

​
Test vs Production

AspectTestProduction
API EndpointSame (api.txncheck.in)Same
API KeysTest keys providedProduction keys
DataSimulated responsesReal verification data
BillingNo chargesPer-request billing
WebhooksDelivered normallyDelivered normally

​
Integration Checklist

Before going live, verify your integration handles these scenarios:
  • API key is stored securely (environment variables)
  • Requests include X-API-Key header
  • Request signing works (if enabled)
  • Handle 401 Unauthorized errors gracefully
  • Submit UPI by Mobile requests successfully
  • Submit KYC by Mobile requests successfully
  • Submit VPA Chargeback Check requests successfully
  • Submit Full Check requests successfully
  • Handle validation errors (400 Bad Request)
  • Store request IDs for tracking
  • Poll request status correctly
  • Handle all status types (QUEUED, PROCESSING, COMPLETED, FAILED, PARTIAL)
  • Parse result data correctly
  • Handle error responses
  • Webhook endpoint is HTTPS and publicly accessible
  • Verify webhook signatures
  • Handle request.completed events
  • Handle request.failed events
  • Handle request.partial events
  • Process events idempotently (handle duplicates)
  • Return 2xx response quickly
  • Handle network timeouts gracefully
  • Implement retry logic with backoff
  • Handle rate limit errors (429)
  • Handle insufficient balance errors (402)
  • Log errors for debugging

​
Testing Request Flow

​
1. Submit a Verification Request

curl -X POST "https://api.txncheck.in/api/v1/upi-by-mobile" \
  -H "X-API-Key: fb_test_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"mobile": "+919876543210"}'
Expected response: 
{
  "statusCode": 202,
  "message": "Request accepted and queued for processing",
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "QUEUED"
}

​
2. Poll for Results

curl -X GET "https://api.txncheck.in/api/v1/requests/550e8400-e29b-41d4-a716-446655440000" \
  -H "X-API-Key: fb_test_your_api_key"
Expected response (processing): 
{
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "method": "upi-by-mobile",
  "status": "PROCESSING",
  "webhookStatus": "PENDING",
  "createdAt": "2025-01-11T10:30:00.000Z"
}
Expected response (completed): 
{
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "method": "upi-by-mobile",
  "status": "COMPLETED",
  "result": {
    "name": "JOHN DOE",
    "upi": ["johndoe@upi", "9876543210@paytm"],
    "status": "1"
  },
  "webhookStatus": "SENT",
  "createdAt": "2025-01-11T10:30:00.000Z",
  "completedAt": "2025-01-11T10:30:05.000Z"
}

​
3. Verify Webhook Receipt

Check that your webhook endpoint received the notification: 
{
  "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"],
      "status": "1"
    },
    "completedAt": "2025-01-11T10:30:05.000Z"
  }
}

​
Testing Error Scenarios

​
Invalid Mobile Number

curl -X POST "https://api.txncheck.in/api/v1/upi-by-mobile" \
  -H "X-API-Key: fb_test_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"mobile": "invalid"}'
Expected error: 
{
  "statusCode": 400,
  "message": ["Mobile must be in format +91XXXXXXXXXX (Indian number)"],
  "error": "Bad Request"
}

​
Invalid API Key

curl -X POST "https://api.txncheck.in/api/v1/upi-by-mobile" \
  -H "X-API-Key: invalid_key" \
  -H "Content-Type: application/json" \
  -d '{"mobile": "+919876543210"}'
Expected error: 
{
  "statusCode": 401,
  "message": "Invalid API key",
  "error": "Unauthorized"
}

​
Method Not Allowed

curl -X POST "https://api.txncheck.in/api/v1/full-check" \
  -H "X-API-Key: fb_test_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"mobile": "+919876543210"}'
Expected error (if method not enabled): 
{
  "statusCode": 403,
  "message": "Access to method 'full-check' is not allowed",
  "error": "Forbidden"
}

​
Testing Webhooks Locally

​
Using ngrok

  1. Install ngrok: npm install -g ngrok
  2. Start your local server on port 3000
  3. Create a tunnel: ngrok http 3000
  4. Use the ngrok URL as your webhook endpoint
ngrok http 3000
# Output: https://abc123.ngrok.io -> http://localhost:3000

​
Using Webhook.site

For quick testing, use webhook.site:
  1. Visit webhook.site and copy your unique URL
  2. Configure this URL as your webhook endpoint (contact support)
  3. Submit a verification request
  4. View the webhook payload on webhook.site

​
Polling Best Practices

When polling for results, implement exponential backoff: 
async function pollForResult(requestId, maxAttempts = 10) {
  let attempt = 0;
  let delay = 1000; // Start with 1 second

  while (attempt < maxAttempts) {
    const response = await fetch(
      `https://api.txncheck.in/api/v1/requests/${requestId}`,
      { headers: { 'X-API-Key': API_KEY } }
    );
    
    const data = await response.json();
    
    if (data.status === 'COMPLETED' || data.status === 'FAILED' || data.status === 'PARTIAL') {
      return data;
    }
    
    // Wait before next attempt
    await new Promise(resolve => setTimeout(resolve, delay));
    
    // Increase delay (max 30 seconds)
    delay = Math.min(delay * 1.5, 30000);
    attempt++;
  }
  
  throw new Error('Polling timeout');
}

​
Going Live

1

Complete Testing

Ensure all checklist items pass in test mode
2

Request Production Keys

Contact your account manager to request production API credentials
3

Update Configuration

Replace test API key with production key in your production environment
4

Verify Webhook URL

Ensure your webhook endpoint points to your production server
5

Top Up Balance

Ensure your merchant account has sufficient balance for API calls
6

Monitor

Watch the dashboard for your first live verifications
Never use production API keys in development or testing environments. Always keep test and production credentials separate.

​
Common Testing Mistakes

Hardcoding API Keys

Always use environment variables for API credentials

Skipping Webhook Verification

Always verify signatures, even in test mode

Not Testing Errors

Test error scenarios, not just happy paths

Ignoring Timeouts

Implement proper timeout handling and retries

​
Need Help?

Developer Support

Contact our support team if you have questions about testing