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

# Reward Distribution Notification

> After all sub-orders in a reward distribution batch are paid successfully, GatePay sends a webhook with `bizType` `PAY_BATCH`.

Verify the signature and return `{"returnCode":"SUCCESS","returnMessage":""}` after successful processing. On delivery failure, GatePay retries at the intervals documented in Notifications Overview.

## Overview

This page documents asynchronous order-status notifications for reward distribution, corresponding to `webhook batchTransferWebhook`.

GatePay sends this notification to the merchant callback URL **after all sub-orders in the batch are paid successfully**.

The notification uses the standard notification envelope:

* `bizType` is always `PAY_BATCH`
* `bizId` is the batch order ID
* `bizStatus` is the batch order status; it is `PAID` when the payout succeeds
* `data` is a **JSON string**

## Notes

* Signature verification, retries, and success response: [Notifications Overview](https://docs.gate.com/global/api-reference/version/100/en/common/asyncNotification.md).
* Signing rules: [Security and Signature](https://docs.gate.com/global/api-reference/version/100/en/common/securityAndSignature.md).
* Prefer idempotency on `merchant_batch_no` + `reward_id`.
* If a notification is delayed, call [Merchant batch transfer order query](https://docs.gate.com/global/api-reference/version/100/en/endpoint/withdraw/reward-distribution/query.md) for reconciliation.

## Trigger scenarios

Reward-distribution notifications are sent only when **the entire batch is paid successfully**. In this case, `bizStatus` and each sub-order `status` are `PAID`.

## Message structure

| Field | Type | Description |
| - | - | - |
| `bizType` | string | Always `PAY_BATCH` |
| `bizId` | string | Batch order ID |
| `bizStatus` | string | Batch order status; `PAID` when the payout succeeds |
| `data` | string | Business payload as a JSON string; parse it as JSON first |

### Example message

```json theme={null}
{
  "bizType": "PAY_BATCH",
  "bizId": "79553020665790540",
  "bizStatus": "PAID",
  "data": "{\"batchItemList\":[{\"amount\":\"0.12300000\",\"channel_id\":\"\",\"create_time\":1780017207390,\"currency\":\"USDT\",\"receiver_id\":22112573,\"reward_id\":\"50888456789213330\",\"status\":\"PAID\"}],\"merchant_batch_no\":\"K4t1ijqX1LYRYmlp\"}"
}
```

## `data` fields

After parsing `data`, the object fields are:

| Field | Type | Description |
| - | - | - |
| `merchant_batch_no` | string | Merchant batch number |
| `batchItemList` | array | Reward-distribution sub-order list |

### `batchItemList` item fields

| Field | Type | Description |
| - | - | - |
| `amount` | string | Reward amount |
| `channel_id` | string | Customer name / channel ID; omitted when not set |
| `create_time` | int64 | Create time in milliseconds |
| `currency` | string | Currency |
| `receiver_id` | int64 | Receiver UID |
| `reward_id` | string | Reward / business sub-order ID; omitted when not set |
| `status` | string | Sub-order status; `PAID` when the payout succeeds |

## Callback example

### Reward distribution batch success

```json theme={null}
{
  "bizType": "PAY_BATCH",
  "bizId": "79553020665790540",
  "bizStatus": "PAID",
  "data": "{\"batchItemList\":[{\"amount\":\"0.12300000\",\"channel_id\":\"\",\"create_time\":1780017207390,\"currency\":\"USDT\",\"receiver_id\":22112573,\"reward_id\":\"50888456789213330\",\"status\":\"PAID\"}],\"merchant_batch_no\":\"K4t1ijqX1LYRYmlp\"}"
}
```

## Integration tips

1. Verify the signature before parsing the body.
2. Deserialize `data` as JSON, then read `merchant_batch_no` and `batchItemList`.
3. Identify the batch with `merchant_batch_no` and each reward with `reward_id`.
4. Treat each item's `status` as the actual payout result.
5. After successful handling, return HTTP 200 with the standard success body:

```json theme={null}
{
  "returnCode": "SUCCESS",
  "returnMessage": ""
}
```


## OpenAPI

````yaml global/api-reference/version/100/en/openapi/batch-transfer-callback-openapi.json webhook batchTransferWebhook
openapi: 3.1.0
info:
  title: GatePay Batch Transfer Callback API
  version: 1.0.0
  description: >-
    Asynchronous notifications for batch transfer (reward distribution) orders.
    GatePay sends the notification to the merchant callback URL after all
    sub-orders in the batch are paid successfully; `data` is a JSON string.
servers:
  - url: https://openplatform.gateapi.io
    description: Production
security: []
paths: {}

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.