奖励分发通知

{
  "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\":\"\"}]}"
}

{
  "returnCode": "SUCCESS",
  "returnMessage": ""
}

WEBHOOK

batchTransferNotify

{
  "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\":\"\"}]}"
}

{
  "returnCode": "SUCCESS",
  "returnMessage": ""
}

概述

本页说明奖励分发场景下的订单状态异步通知，对应 webhook batchTransferNotify。根据当前代码实现，该通知由批量处理任务在全部子单处理成功后触发发送：

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

通知使用标准通知信封：

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

说明

验签、重试、成功应答规则见通知概览。
签名规则见安全与签名。
建议基于 merchant_batch_no + reward_id 做幂等处理。
若长时间未收到通知，可调用商户批量转账订单查询做补偿查询。

触发情形

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

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`

消息结构示例

{
  "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

回调示例

奖励分发批量成功通知

{
  "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 先做 JSON 反序列化，再读取 merchant_batch_no 与 batchItemList。
以 merchant_batch_no 识别批次，以 reward_id 识别单笔奖励。
以每个子项的 status 作为实际奖励发放结果依据。
处理成功后返回 HTTP 200 与标准成功应答：

{
  "returnCode": "SUCCESS",
  "returnMessage": ""
}

请求体

application/json

bizType

enum<string>

必填

业务类型，固定为 PAY_BATCH。

可用选项:

PAY_BATCH

bizId

string

必填

批量订单 ID，对应 batchTransferModel.getBatchId()。

bizStatus

enum<string>

必填

批量订单状态，对应 batchTransferModel.getStatus()。按当前发送链路，示例值为 PAID。

可用选项:

PAID

data

string

必填

业务数据 JSON 字符串，值来自 JSON.toJSONString(batchOrderNotify)，解析后结构见 batchTransferData。

client_id

string

创建订单的商户 client_id。

batchTransferData

object

data 解析后的奖励分发批量通知内容。

Show child attributes

description

any

响应

200 - application/json

返回 HTTP 200 表示商户已成功接收通知。

商户接收通知后的响应体。

returnCode

string

必填

返回状态码，SUCCESS 表示成功。

returnMessage

string | null

返回说明，成功时可为空。

提现回调通知

订阅订单状态更新消息通知

⌘I

公共

余额

机构

支付

OTC

闪兑

出金

礼品卡

订阅

对账

通知

概述

说明

触发情形

消息结构

消息结构示例

data 字段说明

batchItemList 子项字段

代码实现对应关系

回调示例

奖励分发批量成功通知

接入建议

请求体

响应

​概述

​说明

​触发情形

​消息结构

​消息结构示例

​data 字段说明

​batchItemList 子项字段

​代码实现对应关系

​回调示例

​奖励分发批量成功通知

​接入建议

请求体

响应

概述

说明

触发情形

消息结构

消息结构示例

data 字段说明

batchItemList 子项字段

代码实现对应关系

回调示例

奖励分发批量成功通知

接入建议