> ## 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`。

根据当前代码实现，该通知由批量处理任务在**全部子单处理成功**后触发发送：

* 调用位置：`BatchTransferProcessTask` 第 187 行
* 发送方法：`BatchNotifyService.batchNotify(...)`

通知使用标准通知信封：

* `bizType` 固定为 `PAY_BATCH`
* `bizId` 为批量订单 ID（`batchTransferModel.getBatchId()`）
* `bizStatus` 为批量订单状态（当前这条发送链路下实际为 `PAID`）
* `data` 为 **JSON 字符串**，值来自 `JSON.toJSONString(batchOrderNotify)`

## 说明

* 验签、重试、成功应答规则见 [通知概览](/api-reference/version/100/cn/common/asyncNotification)。
* 签名规则见 [安全与签名](/api-reference/version/100/cn/common/securityAndSignature)。
* 建议基于 `merchant_batch_no` + `reward_id` 做幂等处理。
* 若长时间未收到通知，可调用 [商户批量转账订单查询](/api-reference/version/100/cn/endpoint/withdraw/reward-distribution/query) 做补偿查询。

## 触发情形

当前代码中，奖励分发通知只在**批次全部成功**时发送：

* `BatchTransferProcessTask` 先判断批次处理状态
* 当状态为 `BatchTransferProcessStatusEnum.AllPaid` 时
* 调用 `batchNotifyService.batchNotify(batchTransferModel.getMerchantBatchNo(), batchTransferModel, batchTransferProcessStatus.getTransferOrderModels())`

因此，当前这条通知链路下的 `bizStatus` 与子单 `status` 示例应与成功场景保持一致。

## 消息结构

| 字段名         | 类型     | 说明                            |
| ----------- | ------ | ----------------------------- |
| `bizType`   | string | 固定为 `PAY_BATCH`               |
| `bizId`     | string | 批量订单 ID                       |
| `bizStatus` | string | 批量订单状态；按当前代码发送链路，示例为 `PAID`   |
| `client_id` | string | 创建订单的商户 `client_id`           |
| `data`      | string | 业务数据 JSON 字符串，需先 `JSON.parse` |

### 消息结构示例

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

## data 字段说明

`data` 解析后为一个对象，字段如下：

| 字段名                 | 类型     | 说明                                                 |
| ------------------- | ------ | -------------------------------------------------- |
| `currency`          | string | 批次币种，对应 `BatchOrderNotify.currency`                |
| `merchant_batch_no` | string | 商户批次号，对应 `batchTransferModel.getMerchantBatchNo()` |
| `batchItemList`     | array  | 奖励分发子单列表                                           |

### batchItemList 子项字段

| 字段名           | 类型     | 说明                                                        |
| ------------- | ------ | --------------------------------------------------------- |
| `receiver_id` | int64  | 接收方 UID，对应 `transferOrderModel.getReceive()`              |
| `amount`      | string | 奖励金额，对应 `transferOrderModel.getAmount().toPlainString()`  |
| `currency`    | string | 币种，对应 `transferOrderModel.getCurrency()`                  |
| `status`      | string | 子单状态，对应 `transferOrderModel.getStatus()`；当前成功回调示例为 `PAID` |
| `reward_id`   | string | 奖励单号 / 业务子单标识，对应 `transferOrderModel.getRewardId()`       |
| `create_time` | int64  | 创建时间（毫秒），对应 `transferOrderModel.getCreateTime()`          |
| `channel_id`  | string | 客户名称 / 渠道标识，对应 `transferOrderModel.getChannelId()`        |

## 代码实现对应关系

根据代码，通知体由 `BatchNotifyService.batchNotify(...)` 构造：

* 顶层通知字段：
  * `bizType = BizTypeEnum.PAY_BATCH.getType()`
  * `bizId = batchTransferModel.getBatchId()`
  * `bizStatus = batchTransferModel.getStatus()`
  * `data = JSON.toJSONString(batchOrderNotify)`
* `data` 内部对象 `batchOrderNotify` 字段：
  * `currency`
  * `merchant_batch_no`
  * `batchItemList`
* `batchItemList` 子项字段：
  * `receiver_id`
  * `amount`
  * `currency`
  * `status`
  * `reward_id`
  * `create_time`
  * `channel_id`

## 回调示例

### 奖励分发批量成功通知

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

## 接入建议

1. 先校验签名，再解析通知体。
2. 对 `data` 先做 JSON 反序列化，再读取 `merchant_batch_no` 与 `batchItemList`。
3. 以 `merchant_batch_no` 识别批次，以 `reward_id` 识别单笔奖励。
4. 以每个子项的 `status` 作为实际奖励发放结果依据。
5. 处理成功后返回 HTTP 200 与标准成功应答：

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


## 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: {}

````