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

​
VPA Chargeback Check

Check VPA (Virtual Payment Address) against a comprehensive blocklist of flagged accounts. Identify potentially fraudulent UPI addresses before processing transactions.

​
Overview

This endpoint helps businesses:
  • Screen VPAs against known fraud blocklists
  • Prevent transactions with flagged accounts
  • Reduce chargeback rates
  • Protect against UPI fraud

​
Request

​
vpas
string[]
required
Array of VPAs to check against the blocklist. Maximum 100 VPAs per request.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/vpa-chargeback-check" \
  -H "X-API-Key: fb_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "vpas": ["user@upi", "9876543210@paytm"]
  }'

​
Example Request (Sync Mode)

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

​
Response

​
202 Accepted

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

​
Result Data (via webhook or polling)

{
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "method": "vpa-chargeback-check",
  "status": "COMPLETED",
  "result": {
    "blocklisted": [
      { "vpa": "user@upi", "isBlocklisted": true, "source": "provider" }
    ],
    "clean": [
      { "vpa": "9876543210@paytm", "isBlocklisted": false }
    ],
    "summary": { "total": 2, "blocklisted": 1, "clean": 1 }
  },
  "webhookStatus": "SENT",
  "createdAt": "2025-01-11T10:30:00.000Z",
  "completedAt": "2025-01-11T10:30:05.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": ["Each VPA must be in format username@bank (e.g., user@upi)"],
  "error": "Bad Request"
}

{
  "statusCode": 400,
  "message": ["Maximum 100 VPAs allowed per request"],
  "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. 
{
  "statusCode": 429,
  "message": "Too Many Requests",
  "error": "Too Many Requests"
}

​
Use Cases

Check the recipient’s VPA before processing a payment to avoid sending money to fraudulent accounts.
Include blocklist status in your risk scoring model for transaction approval decisions.
Prevent chargebacks by blocking transactions to known fraudulent VPAs.
Screen multiple VPAs in a single request for efficient bulk processing.
For checking more than 100 VPAs, use the Bulk VPA Check endpoint or make multiple requests.