> ## Documentation Index
> Fetch the complete documentation index at: https://docs.txncheck.com/llms.txt
> Use this file to discover all available pages before exploring further.

# VPA Chargeback Check

> Check VPAs against blocklist

# 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

<ParamField body="vpas" type="string[]" required>
  Array of VPAs to check against the blocklist. Maximum 100 VPAs per request.

  Format: `username@bank` (e.g., `user@upi`, `9876543210@paytm`)
</ParamField>

<ParamField body="async" type="boolean" default="true">
  If `true` (default), request is queued and result delivered via webhook. If `false`, wait for result synchronously (up to 30 seconds).
</ParamField>

### Headers

| Header         | Value              | Required |
| -------------- | ------------------ | -------- |
| `X-API-Key`    | Your API key       | Yes      |
| `Content-Type` | `application/json` | Yes      |

### Example Request (Async Mode - Default)

<CodeGroup>
  ```bash cURL theme={null}
  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"]
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.txncheck.in/api/v1/vpa-chargeback-check",
      headers={
          "X-API-Key": "fb_your_api_key_here",
          "Content-Type": "application/json"
      },
      json={
          "vpas": ["user@upi", "9876543210@paytm"]
      }
  )
  print(response.json())
  ```

  ```javascript Node.js theme={null}
  const axios = require('axios');

  const response = await axios.post(
    'https://api.txncheck.in/api/v1/vpa-chargeback-check',
    { vpas: ['user@upi', '9876543210@paytm'] },
    {
      headers: {
        'X-API-Key': 'fb_your_api_key_here',
        'Content-Type': 'application/json'
      }
    }
  );
  console.log(response.data);
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init("https://api.txncheck.in/api/v1/vpa-chargeback-check");
  curl_setopt($ch, CURLOPT_POST, true);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      "X-API-Key: fb_your_api_key_here",
      "Content-Type: application/json"
  ]);
  curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
      "vpas" => ["user@upi", "9876543210@paytm"]
  ]));
  $response = curl_exec($ch);
  curl_close($ch);
  echo $response;
  ```

  ```go Go theme={null}
  payload := map[string][]string{
      "vpas": {"user@upi", "9876543210@paytm"},
  }
  body, _ := json.Marshal(payload)

  req, _ := http.NewRequest("POST", "https://api.txncheck.in/api/v1/vpa-chargeback-check", bytes.NewBuffer(body))
  req.Header.Set("X-API-Key", "fb_your_api_key_here")
  req.Header.Set("Content-Type", "application/json")

  client := &http.Client{}
  resp, _ := client.Do(req)
  ```
</CodeGroup>

### Example Request (Sync Mode)

<CodeGroup>
  ```bash cURL theme={null}
  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
    }'
  ```

  ```javascript Node.js theme={null}
  const axios = require('axios');

  const response = await axios.post(
    'https://api.txncheck.in/api/v1/vpa-chargeback-check',
    { vpas: ['user@upi', '9876543210@paytm'], async: false },
    {
      headers: {
        'X-API-Key': 'fb_your_api_key_here',
        'Content-Type': 'application/json'
      }
    }
  );
  console.log(response.data);
  ```
</CodeGroup>

## Response

<Tabs>
  <Tab title="Async Mode (202)">
    ### 202 Accepted

    Request accepted and queued for processing.

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

    ### Result Data (via webhook or polling)

    ```json theme={null}
    {
      "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"
    }
    ```
  </Tab>

  <Tab title="Sync Mode (200)">
    ### 200 OK

    Request completed synchronously with result in response.

    ```json theme={null}
    {
      "statusCode": 200,
      "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 }
      },
      "createdAt": "2025-01-11T10:30:00.000Z",
      "completedAt": "2025-01-11T10:30:05.000Z"
    }
    ```

    <Warning>
      Sync mode has a 30-second timeout. Use async mode for large VPA lists.
    </Warning>
  </Tab>
</Tabs>

### Result Fields

| Field                         | Type    | Description                        |
| ----------------------------- | ------- | ---------------------------------- |
| `blocklisted`                 | array   | VPAs found in the blocklist        |
| `blocklisted[].vpa`           | string  | The VPA address                    |
| `blocklisted[].isBlocklisted` | boolean | Always `true` for blocklisted VPAs |
| `blocklisted[].source`        | string  | Source of blocklist entry          |
| `clean`                       | array   | VPAs not found in the blocklist    |
| `clean[].vpa`                 | string  | The VPA address                    |
| `clean[].isBlocklisted`       | boolean | Always `false` for clean VPAs      |
| `summary.total`               | number  | Total VPAs checked                 |
| `summary.blocklisted`         | number  | Count of blocklisted VPAs          |
| `summary.clean`               | number  | Count of clean VPAs                |

## Error Responses

### 400 Bad Request

Invalid VPA format or array size.

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

```json theme={null}
{
  "statusCode": 400,
  "message": ["Maximum 100 VPAs allowed per request"],
  "error": "Bad Request"
}
```

### 401 Unauthorized

Invalid or missing API key.

```json theme={null}
{
  "statusCode": 401,
  "message": "Invalid API key",
  "error": "Unauthorized"
}
```

### 402 Payment Required

Insufficient account balance.

```json theme={null}
{
  "statusCode": 402,
  "message": "Insufficient wallet balance",
  "error": "Payment Required"
}
```

### 403 Forbidden

Method not enabled for your account.

```json theme={null}
{
  "statusCode": 403,
  "message": "Access to method 'vpa-chargeback-check' is not allowed",
  "error": "Forbidden"
}
```

### 408 Request Timeout (Sync Mode Only)

Request processing timed out.

```json theme={null}
{
  "statusCode": 408,
  "message": "Request processing timed out after 30 seconds",
  "error": "Request Timeout"
}
```

### 429 Too Many Requests

Rate limit exceeded.

```json theme={null}
{
  "statusCode": 429,
  "message": "Too Many Requests",
  "error": "Too Many Requests"
}
```

## Use Cases

<AccordionGroup>
  <Accordion title="Pre-Transaction Screening">
    Check the recipient's VPA before processing a payment to avoid sending money to fraudulent accounts.
  </Accordion>

  <Accordion title="Risk Assessment">
    Include blocklist status in your risk scoring model for transaction approval decisions.
  </Accordion>

  <Accordion title="Chargeback Prevention">
    Prevent chargebacks by blocking transactions to known fraudulent VPAs.
  </Accordion>

  <Accordion title="Batch Screening">
    Screen multiple VPAs in a single request for efficient bulk processing.
  </Accordion>
</AccordionGroup>

<Note>
  For checking more than 100 VPAs, use the [Bulk VPA Check](/api-reference/bulk-vpa-check) endpoint or make multiple requests.
</Note>