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

# 批量转账状态通知

> 奖励分发批量转账订单状态变更时，GatePay 发送 `bizType` 为 `PAY_BATCH` 的 webhook 通知。根据当前代码实现，该通知在批次全部成功后由 `BatchTransferProcessTask` 调用 `BatchNotifyService.batchNotify(...)` 发送。

商户须校验签名，处理成功后返回 `{'returnCode':'SUCCESS','returnMessage':''}`。通知失败时按 [通知概览](/api-reference/version/100/cn/common/asyncNotification) 中的间隔重试。

## 概述

本页说明 `webhook batchTransferNotify`。完整的参数、响应结构与示例由上方关联的 OpenAPI 或 webhook 定义渲染。

批量转账订单状态变更时，GatePay 向商户配置的 callback URL 发送异步通知（`bizType` 为 `PAY_BATCH`）。

## 说明

* 建议基于 `merchant_batch_no` 或 `bizId` 做幂等处理。
* 验签、重试、`data` 解析与成功应答见 [通知概览](/api-reference/version/100/cn/common/asyncNotification)；签名规则见 [安全与签名](/api-reference/version/100/cn/common/securityAndSignature)。

## 触发情形

* 批量转账订单状态发生改变时，GatePay 向商户注册时配置的 **callback URL** 发送通知
* 若通知投递失败，重试规则见 [通知概览](/api-reference/version/100/cn/common/asyncNotification)。

**适用范围**：批量转账 / 批量奖励类订单（`bizType` 为 `PAY_BATCH`）。

## 消息结构

| 字段名         | 类型     | 说明                     |
| ----------- | ------ | ---------------------- |
| `bizType`   | string | 固定为 `PAY_BATCH`        |
| `bizId`     | string | 批量订单 ID（可能为空字符串，以实际为准） |
| `bizStatus` | string | 批量订单状态，见下表             |
| `client_id` | string | 创建订单的商户 `client_id`    |
| `data`      | string | 业务数据 JSON 字符串          |

### 消息结构示例

```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,\"status\":\"PAID\"}],\"merchant_batch_no\":\"K4t1ijqX1LYRYmlp\"}"
}
```

## bizStatus 枚举值

| 值      | 说明            |
| ------ | ------------- |
| `PAID` | 批量转账/奖励订单处理完成 |

## data 字段说明

| 字段名                 | 类型     | 说明       |
| ------------------- | ------ | -------- |
| `merchant_batch_no` | string | 商户批量单号   |
| `batchItemList`     | array  | 批量转账子项列表 |

### batchItemList 子项字段

| 字段名           | 类型     | 说明             |
| ------------- | ------ | -------------- |
| `amount`      | string | 子项金额           |
| `channel_id`  | string | 客户名称 / 渠道标识    |
| `create_time` | int64  | 创建时间（毫秒）       |
| `currency`    | string | 币种             |
| `receiver_id` | int64  | 接收方 UID        |
| `status`      | string | 子项状态，例如 `PAID` |

## 回调示例

### 批量转账完成（`bizStatus=PAID`）

```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,\"status\":\"PAID\"}],\"merchant_batch_no\":\"K4t1ijqX1LYRYmlp\"}"
}
```


## OpenAPI

````yaml api-reference/version/100/cn/openapi/batch-transfer-callback-openapi.json webhook batchTransferNotify
openapi: 3.1.0
info:
  title: GatePay 批量转账回调 API
  version: 1.0.0
  description: 批量转账（奖励分发）订单状态异步通知。根据当前代码实现，该通知在批次全部成功后发送；`data` 为 JSON 字符串。
servers:
  - url: https://openplatform.gateapi.io
    description: 生产环境
security: []
paths: {}

````