Skip to main content
POST
/
api
/
v1
/
bulk
/
vpa-chargeback-check
Bulk VPA Check
curl --request POST \
  --url https://api.example.com/api/v1/bulk/vpa-chargeback-check \
  --header 'Content-Type: application/json' \
  --data '
{
  "vpas": [
    "<string>"
  ],
  "async": true
}
'

​
Bulk VPA Check

Check up to 100 VPA addresses against the blocklist in a single request. Ideal for batch processing and periodic fraud screening.

​
Overview

This endpoint is designed for:
  • Batch screening of multiple VPAs
  • Periodic audits of customer payment addresses
  • Large-scale fraud prevention operations
  • Efficient bulk verification workflows

​
Request

​
vpas
string[]
required
Array of VPAs to check against the blocklist.
  • Minimum: 1 VPA
  • Maximum: 100 VPAs
  • Format: username@bank (e.g., user@upi, 9876543210@paytm)
​
async
boolean
default:"true"
If true (default), request is queued and result delivered via webhook. If false, wait for result synchronously (up to 30 seconds).

​
Headers

HeaderValueRequired
X-API-KeyYour API keyYes
Content-Typeapplication/jsonYes

​
Example Request (Async Mode - Default)

curl -X POST "https://api.txncheck.in/api/v1/bulk/vpa-chargeback-check" \
  -H "X-API-Key: fb_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "vpas": [
      "user1@upi",
      "user2@paytm",
      "user3@gpay",
      "9876543210@ybl",
      "merchant@okicici"
    ]
  }'

​
Example Request (Sync Mode)

curl -X POST "https://api.txncheck.in/api/v1/bulk/vpa-chargeback-check" \
  -H "X-API-Key: fb_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "vpas": ["user1@upi", "user2@paytm", "user3@gpay"],
    "async": false
  }'

​
Response

​
202 Accepted

Request accepted and queued for processing.
{
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "QUEUED",
  "itemCount": 5,
  "message": "Bulk VPA chargeback check queued"
}
FieldTypeDescription
requestIdstringUnique request identifier for tracking
statusstringInitial status (QUEUED)
itemCountnumberNumber of VPAs to be checked
messagestringConfirmation message

​
Result Data (via webhook, polling, or sync response)

When the request completes successfully: 
{
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "method": "vpa-chargeback-check",
  "status": "COMPLETED",
  "result": {
    "blocklisted": [
      {
        "vpa": "user2@paytm",
        "isBlocklisted": true,
        "source": "provider"
      }
    ],
    "clean": [
      {"vpa": "user1@upi", "isBlocklisted": false},
      {"vpa": "user3@gpay", "isBlocklisted": false},
      {"vpa": "9876543210@ybl", "isBlocklisted": false},
      {"vpa": "merchant@okicici", "isBlocklisted": false}
    ],
    "summary": {
      "total": 5,
      "blocklisted": 1,
      "clean": 4
    }
  },
  "webhookStatus": "SENT",
  "createdAt": "2025-01-11T10:30:00.000Z",
  "completedAt": "2025-01-11T10:30:15.000Z"
}

​
Result Fields

FieldTypeDescription
blocklistedarrayVPAs found in the blocklist
blocklisted[].vpastringThe VPA address
blocklisted[].isBlocklistedbooleanAlways true for blocklisted VPAs
blocklisted[].sourcestringSource of blocklist entry
cleanarrayVPAs not found in the blocklist
clean[].vpastringThe VPA address
clean[].isBlocklistedbooleanAlways false for clean VPAs
summary.totalnumberTotal VPAs checked
summary.blocklistednumberCount of blocklisted VPAs
summary.cleannumberCount of clean VPAs

​
Error Responses

​
400 Bad Request

Invalid VPA format or array size. 
{
  "statusCode": 400,
  "message": ["At least one VPA is required"],
  "error": "Bad Request"
}

{
  "statusCode": 400,
  "message": ["Maximum 100 VPAs allowed per request"],
  "error": "Bad Request"
}

{
  "statusCode": 400,
  "message": ["Each VPA must be in format username@bank (e.g., user@upi)"],
  "error": "Bad Request"
}

​
401 Unauthorized

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

​
402 Payment Required

Insufficient account balance. 
{
  "statusCode": 402,
  "message": "Insufficient wallet balance",
  "error": "Payment Required"
}

​
403 Forbidden

Method not enabled for your account. 
{
  "statusCode": 403,
  "message": "Access to method 'vpa-chargeback-check' is not allowed",
  "error": "Forbidden"
}

​
408 Request Timeout (Sync Mode Only)

Request processing timed out. 
{
  "statusCode": 408,
  "message": "Request processing timed out after 30 seconds",
  "error": "Request Timeout"
}

​
429 Too Many Requests

Rate limit exceeded. Bulk endpoints have a lower rate limit. 
{
  "statusCode": 429,
  "message": "Too Many Requests",
  "error": "Too Many Requests"
}

​
Rate Limits

Bulk endpoints have a lower rate limit of 10 requests per minute to ensure fair usage.

​
Use Cases

Run daily or weekly checks on all customer VPAs to identify newly flagged accounts.
Screen all VPAs in a batch of pending transactions before processing.
Verify VPAs when importing customers from legacy systems or partner platforms.
Generate periodic reports on blocklisted VPAs in your customer base.

​
Best Practices

Deduplicate VPAs

Remove duplicates before sending to avoid unnecessary checks

Batch Efficiently

Group VPAs into batches of 100 for optimal throughput

Handle Rate Limits

Implement delays between batch requests to stay within limits

Process Results

Store blocklist status for quick reference in transaction flows
For real-time single VPA checks during transactions, use the VPA Chargeback Check endpoint instead.