跳转到主要内容
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)

​
说明

​
触发情形

当前代码中，奖励分发通知只在批次全部成功时发送：
  • BatchTransferProcessTask 先判断批次处理状态
  • 当状态为 BatchTransferProcessStatusEnum.AllPaid 时
  • 调用 batchNotifyService.batchNotify(batchTransferModel.getMerchantBatchNo(), batchTransferModel, batchTransferProcessStatus.getTransferOrderModels())
因此，当前这条通知链路下的 bizStatus 与子单 status 示例应与成功场景保持一致。

​
消息结构

字段名类型说明
bizTypestring固定为 PAY_BATCH
bizIdstring批量订单 ID
bizStatusstring批量订单状态；按当前代码发送链路，示例为 PAID
client_idstring创建订单的商户 client_id
datastring业务数据 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 解析后为一个对象，字段如下：
字段名类型说明
currencystring批次币种，对应 BatchOrderNotify.currency
merchant_batch_nostring商户批次号，对应 batchTransferModel.getMerchantBatchNo()
batchItemListarray奖励分发子单列表

​
batchItemList 子项字段

字段名类型说明
receiver_idint64接收方 UID，对应 transferOrderModel.getReceive()
amountstring奖励金额，对应 transferOrderModel.getAmount().toPlainString()
currencystring币种，对应 transferOrderModel.getCurrency()
statusstring子单状态，对应 transferOrderModel.getStatus()；当前成功回调示例为 PAID
reward_idstring奖励单号 / 业务子单标识，对应 transferOrderModel.getRewardId()
create_timeint64创建时间（毫秒），对应 transferOrderModel.getCreateTime()
channel_idstring客户名称 / 渠道标识，对应 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\":\"\"}]}"
}

​
接入建议

  1. 先校验签名，再解析通知体。
  2. 对 data 先做 JSON 反序列化，再读取 merchant_batch_no 与 batchItemList。
  3. 以 merchant_batch_no 识别批次，以 reward_id 识别单笔奖励。
  4. 以每个子项的 status 作为实际奖励发放结果依据。
  5. 处理成功后返回 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 解析后的奖励分发批量通知内容。

​
description
any

响应

200 - application/json

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

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

​
returnCode
string
必填

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

​
returnMessage
string | null

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