Skip to main content
GET
/
api
/
v1
/
requests
/
{id}
Request Status
curl --request GET \
  --url https://api.example.com/api/v1/requests/{id}

​
Request Status

Retrieve the status and results of a verification request by its ID. Use this endpoint to poll for results if you’re not using webhooks.

​
Overview

After submitting a verification request, you receive a request ID. Use this endpoint to:
  • Check the current status of a request
  • Retrieve verification results when completed
  • Get error details if the request failed
  • Verify webhook delivery status

​
Request

​
Path Parameters

​
id
string
required
The unique request ID (UUID) returned when the verification request was submitted.

​
Headers

HeaderValueRequired
X-API-KeyYour API keyYes

​
Example Request

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

​
Response

​
200 OK - Queued

Request is waiting for processing. 
{
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "method": "upi-by-mobile",
  "status": "QUEUED",
  "webhookStatus": "PENDING",
  "createdAt": "2025-01-11T10:30:00.000Z"
}

​
200 OK - Processing

Request is currently being processed. 
{
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "method": "upi-by-mobile",
  "status": "PROCESSING",
  "webhookStatus": "PENDING",
  "createdAt": "2025-01-11T10:30:00.000Z"
}

​
200 OK - Completed

Request completed successfully with results. 
{
  "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"
}

​
200 OK - Failed

Request failed with error details. 
{
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "method": "upi-by-mobile",
  "status": "FAILED",
  "error": {
    "class": "PROVIDER_BUSINESS_ERROR",
    "message": "Mobile number not found in UPI system"
  },
  "webhookStatus": "SENT",
  "createdAt": "2025-01-11T10:30:00.000Z",
  "completedAt": "2025-01-11T10:30:05.000Z"
}

​
200 OK - Partial (Full Check)

Some steps completed, others failed. 
{
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "method": "full-check",
  "status": "PARTIAL",
  "stepStatuses": {
    "upiByMobile": "ok",
    "kycByMobile": "failed",
    "vpaChargebackCheck": "ok"
  },
  "result": {
    "upiByMobile": { ... },
    "vpaChargebackCheck": { ... }
  },
  "error": {
    "kycByMobile": {
      "class": "PROVIDER_TEMPORARY",
      "message": "Service temporarily unavailable"
    }
  },
  "webhookStatus": "SENT",
  "createdAt": "2025-01-11T10:30:00.000Z",
  "completedAt": "2025-01-11T10:30:10.000Z"
}

​
Response Fields

FieldTypeDescription
requestIdstringUnique request identifier
methodstringVerification method used
statusstringCurrent status (see below)
resultobjectVerification results (if completed)
errorobjectError details (if failed)
stepStatusesobjectIndividual step statuses (for full-check)
webhookStatusstringWebhook delivery status
createdAtstringRequest creation timestamp
completedAtstringRequest completion timestamp

​
Request Statuses

StatusDescription
QUEUEDRequest received and waiting for processing
PROCESSINGRequest is being processed
COMPLETEDRequest completed successfully
FAILEDRequest failed (check error details)
PARTIALRequest partially completed (some steps failed)

​
Webhook Statuses

StatusDescription
PENDINGWebhook not yet sent
SENTWebhook delivered successfully
RETRYINGWebhook delivery failed, retrying
FAILEDWebhook delivery failed after all retries

​
Error Responses

​
401 Unauthorized

Invalid or missing API key. 
{
  "statusCode": 401,
  "message": "Invalid API key",
  "error": "Unauthorized"
}

​
404 Not Found

Request not found or doesn’t belong to your merchant. 
{
  "statusCode": 404,
  "message": "Request not found",
  "error": "Not Found"
}

​
Polling Best Practices

When polling for results:

Use Exponential Backoff

Start with 1-2 seconds, increase delay progressively

Set a Timeout

Don’t poll indefinitely - set a maximum duration

Prefer Webhooks

Webhooks are more efficient than polling

Check Terminal States

Stop polling when status is COMPLETED, FAILED, or PARTIAL

​
Example Polling Implementation

async function pollForResult(requestId, maxAttempts = 30, initialDelay = 1000) {
  let attempt = 0;
  let delay = initialDelay;
  
  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();
    
    // Check for terminal states
    if (['COMPLETED', 'FAILED', 'PARTIAL'].includes(data.status)) {
      return data;
    }
    
    // Wait before next attempt
    await new Promise(resolve => setTimeout(resolve, delay));
    
    // Increase delay (max 10 seconds)
    delay = Math.min(delay * 1.5, 10000);
    attempt++;
  }
  
  throw new Error('Polling timeout - request still processing');
}

// Usage
try {
  const result = await pollForResult('550e8400-e29b-41d4-a716-446655440000');
  console.log('Verification result:', result);
} catch (error) {
  console.error('Polling failed:', error.message);
}