> ## 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.

# Bulk VPA Check

> Bulk check VPAs against blocklist

# 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

<ParamField body="vpas" type="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`)
</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/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"
      ]
    }'
  ```

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

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

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

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

  ```php PHP theme={null}
  <?php
  $vpas = [
      "user1@upi",
      "user2@paytm",
      "user3@gpay",
      "9876543210@ybl",
      "merchant@okicici"
  ];

  $ch = curl_init("https://api.txncheck.in/api/v1/bulk/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" => $vpas
  ]));
  $response = curl_exec($ch);
  curl_close($ch);
  echo $response;
  ```

  ```go Go theme={null}
  payload := map[string][]string{
      "vpas": {
          "user1@upi",
          "user2@paytm",
          "user3@gpay",
          "9876543210@ybl",
          "merchant@okicici",
      },
  }
  body, _ := json.Marshal(payload)

  req, _ := http.NewRequest("POST", "https://api.txncheck.in/api/v1/bulk/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/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
    }'
  ```

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

  const response = await axios.post(
    'https://api.txncheck.in/api/v1/bulk/vpa-chargeback-check',
    { vpas: ['user1@upi', 'user2@paytm', 'user3@gpay'], 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}
    {
      "requestId": "550e8400-e29b-41d4-a716-446655440000",
      "status": "QUEUED",
      "itemCount": 5,
      "message": "Bulk VPA chargeback check queued"
    }
    ```

    | Field       | Type   | Description                            |
    | ----------- | ------ | -------------------------------------- |
    | `requestId` | string | Unique request identifier for tracking |
    | `status`    | string | Initial status (`QUEUED`)              |
    | `itemCount` | number | Number of VPAs to be checked           |
    | `message`   | string | Confirmation message                   |
  </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",
      "status": "COMPLETED",
      "itemCount": 5,
      "result": {
        "blocklisted": [
          { "vpa": "user2@paytm", "isBlocklisted": true, "source": "provider" }
        ],
        "clean": [
          { "vpa": "user1@upi", "isBlocklisted": false },
          { "vpa": "user3@gpay", "isBlocklisted": false }
        ],
        "summary": { "total": 3, "blocklisted": 1, "clean": 2 }
      },
      "createdAt": "2025-01-11T10:30:00.000Z",
      "completedAt": "2025-01-11T10:30:05.000Z"
    }
    ```

    <Warning>
      Sync mode has a 30-second timeout. For large batches (50+ VPAs), consider using async mode.
    </Warning>
  </Tab>
</Tabs>

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

When the request completes successfully:

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

| 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": ["At least one VPA is required"],
  "error": "Bad Request"
}
```

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

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

```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. Bulk endpoints have a lower rate limit.

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

## Rate Limits

<Warning>
  Bulk endpoints have a lower rate limit of **10 requests per minute** to ensure fair usage.
</Warning>

## Use Cases

<AccordionGroup>
  <Accordion title="Periodic Customer Audit">
    Run daily or weekly checks on all customer VPAs to identify newly flagged accounts.
  </Accordion>

  <Accordion title="Batch Transaction Screening">
    Screen all VPAs in a batch of pending transactions before processing.
  </Accordion>

  <Accordion title="New Customer Import">
    Verify VPAs when importing customers from legacy systems or partner platforms.
  </Accordion>

  <Accordion title="Compliance Reporting">
    Generate periodic reports on blocklisted VPAs in your customer base.
  </Accordion>
</AccordionGroup>

## Best Practices

<CardGroup cols={2}>
  <Card title="Deduplicate VPAs" icon="copy">
    Remove duplicates before sending to avoid unnecessary checks
  </Card>

  <Card title="Batch Efficiently" icon="layer-group">
    Group VPAs into batches of 100 for optimal throughput
  </Card>

  <Card title="Handle Rate Limits" icon="clock">
    Implement delays between batch requests to stay within limits
  </Card>

  <Card title="Process Results" icon="check">
    Store blocklist status for quick reference in transaction flows
  </Card>
</CardGroup>

<Note>
  For real-time single VPA checks during transactions, use the [VPA Chargeback Check](/api-reference/vpa-chargeback-check) endpoint instead.
</Note>