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

Aspect	Test	Production
API Endpoint	Same (`api.txncheck.in`)	Same
API Keys	Test keys provided	Production keys
Data	Simulated responses	Real verification data
Billing	No charges	Per-request billing
Webhooks	Delivered normally	Delivered normally

Integration Checklist

Before going live, verify your integration handles these scenarios:

API Authentication

API key is stored securely (environment variables)
Requests include X-API-Key header
Request signing works (if enabled)
Handle 401 Unauthorized errors gracefully

Request Submission

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

Result Retrieval

Poll request status correctly
Handle all status types (QUEUED, PROCESSING, COMPLETED, FAILED, PARTIAL)
Parse result data correctly
Handle error responses

Webhooks

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

Error Handling

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

Install ngrok: npm install -g ngrok
Start your local server on port 3000
Create a tunnel: ngrok http 3000
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:

Visit webhook.site and copy your unique URL
Configure this URL as your webhook endpoint (contact support)
Submit a verification request
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

Complete Testing

Ensure all checklist items pass in test mode

Request Production Keys

Contact your account manager to request production API credentials

Update Configuration

Replace test API key with production key in your production environment

Verify Webhook URL

Ensure your webhook endpoint points to your production server

Top Up Balance

Ensure your merchant account has sufficient balance for API calls

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

Webhooks Guide Python SDK

Getting Started

Guides

SDKs

Use Cases

Security

API Reference

Reference

Testing Guide

Testing Guide

Test Environment

Test vs Production

Integration Checklist

Testing Request Flow

1. Submit a Verification Request

2. Poll for Results

3. Verify Webhook Receipt

Testing Error Scenarios

Invalid Mobile Number

Invalid API Key

Method Not Allowed

Testing Webhooks Locally

Using ngrok

Using Webhook.site

Polling Best Practices

Going Live

Common Testing Mistakes

Hardcoding API Keys

Skipping Webhook Verification

Not Testing Errors

Ignoring Timeouts

Need Help?

Developer Support

​Testing Guide

​Test Environment

​Test vs Production

​Integration Checklist

​Testing Request Flow

​1. Submit a Verification Request

​2. Poll for Results

​3. Verify Webhook Receipt

​Testing Error Scenarios

​Invalid Mobile Number

​Invalid API Key

​Method Not Allowed

​Testing Webhooks Locally

​Using ngrok

​Using Webhook.site

​Polling Best Practices

​Going Live

​Common Testing Mistakes

Hardcoding API Keys

Skipping Webhook Verification

Not Testing Errors

Ignoring Timeouts

​Need Help?

Developer Support

Testing Guide

Test Environment

Test vs Production

Integration Checklist

Testing Request Flow

1. Submit a Verification Request

2. Poll for Results

3. Verify Webhook Receipt

Testing Error Scenarios

Invalid Mobile Number

Invalid API Key

Method Not Allowed

Testing Webhooks Locally

Using ngrok

Using Webhook.site

Polling Best Practices

Going Live

Common Testing Mistakes

Need Help?