Reward Distribution Notification

{
  "bizType": "PAY_BATCH",
  "bizId": "79553020665790540",
  "bizStatus": "PAID",
  "data": "{\"batchItemList\":[{\"amount\":\"0.12300000\",\"channel_id\":\"\",\"create_time\":1780017207390,\"currency\":\"USDC\",\"receiver_id\":22112573,\"status\":\"PAID\"}],\"merchant_batch_no\":\"K4t1ijqX1LYRYmlp\"}"
}

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

WEBHOOK

batchTransferWebhook

{
  "bizType": "PAY_BATCH",
  "bizId": "79553020665790540",
  "bizStatus": "PAID",
  "data": "{\"batchItemList\":[{\"amount\":\"0.12300000\",\"channel_id\":\"\",\"create_time\":1780017207390,\"currency\":\"USDC\",\"receiver_id\":22112573,\"status\":\"PAID\"}],\"merchant_batch_no\":\"K4t1ijqX1LYRYmlp\"}"
}

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

Overview

This page documents asynchronous order-status notifications for reward distribution, corresponding to webhook batchTransferWebhook. Based on the current implementation, this notification is sent by the batch processing task after all sub-orders succeed:

Call site: BatchTransferProcessTask (line 187)
Send method: BatchNotifyService.batchNotify(...)

The notification uses the standard notification envelope:

bizType is always PAY_BATCH
bizId is the batch order ID (batchTransferModel.getBatchId())
bizStatus is the batch order status (on this send path it is PAID)
data is a JSON string from JSON.toJSONString(batchOrderNotify)

Notes

Signature verification, retries, and success response: Notifications Overview.
Signing rules: Security and Signature.
Prefer idempotency on merchant_batch_no + reward_id.
If a notification is delayed, call Merchant batch transfer order query for reconciliation.

Trigger scenarios

In the current code, reward-distribution notifications are sent only when the entire batch succeeds:

BatchTransferProcessTask first checks batch processing status
When the status is BatchTransferProcessStatusEnum.AllPaid
It calls batchNotifyService.batchNotify(batchTransferModel.getMerchantBatchNo(), batchTransferModel, batchTransferProcessStatus.getTransferOrderModels())

Therefore, bizStatus and each sub-order status in examples on this path should match the success scenario.

Message structure

Field	Type	Description
`bizType`	string	Always `PAY_BATCH`
`bizId`	string	Batch order ID
`bizStatus`	string	Batch order status; on the current send path the example is `PAID`
`client_id`	string	Merchant `client_id` that created the order
`data`	string	Business payload as a JSON string; parse with `JSON.parse` first

Example message

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

`data` fields

After parsing data, the object fields are:

Field	Type	Description
`currency`	string	Batch currency (`BatchOrderNotify.currency`)
`merchant_batch_no`	string	Merchant batch number (`batchTransferModel.getMerchantBatchNo()`)
`batchItemList`	array	Reward-distribution sub-order list

`batchItemList` item fields

Field	Type	Description
`receiver_id`	int64	Receiver UID (`transferOrderModel.getReceive()`)
`amount`	string	Reward amount (`transferOrderModel.getAmount().toPlainString()`)
`currency`	string	Currency (`transferOrderModel.getCurrency()`)
`status`	string	Sub-order status (`transferOrderModel.getStatus()`); success callback example is `PAID`
`reward_id`	string	Reward / business sub-order ID (`transferOrderModel.getRewardId()`)
`create_time`	int64	Create time in milliseconds (`transferOrderModel.getCreateTime()`)
`channel_id`	string	Customer name / channel ID (`transferOrderModel.getChannelId()`)

Code mapping

The payload is built by BatchNotifyService.batchNotify(...):

Top-level notification fields:
- bizType = BizTypeEnum.PAY_BATCH.getType()
- bizId = batchTransferModel.getBatchId()
- bizStatus = batchTransferModel.getStatus()
- data = JSON.toJSONString(batchOrderNotify)
Inner batchOrderNotify fields in data:
- currency
- merchant_batch_no
- batchItemList
batchItemList item fields:
- receiver_id
- amount
- currency
- status
- reward_id
- create_time
- channel_id

Callback example

Reward distribution batch success

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

Integration tips

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

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

Body

application/json

bizType

enum<string>

required

Business type; always PAY_BATCH.

Available options:

PAY_BATCH

bizId

string

required

Batch order ID.

bizStatus

enum<string>

required

Batch order status; commonly PAID when transfer/reward completes.

Available options:

PAID

data

string

required

Business data as a JSON string; parsed structure see batchTransferData.

client_id

string

Merchant client_id that created the order.

batchTransferData

object

Parsed batch transfer details from data.

Show child attributes

description

any

Response

200 - application/json

HTTP 200 indicates the merchant successfully received the notification.

Response body returned by the merchant after receiving the notification.

returnCode

string

required

Return status code; SUCCESS indicates success.

returnMessage

string | null

Return message; may be empty on success.

Common

Balance

Payment

Convert

Payout

Reconciliation

Notifications

Reward Distribution Notification

Overview

Notes

Trigger scenarios

Message structure

Example message

`data` fields

`batchItemList` item fields

Code mapping

Callback example

Reward distribution batch success

Integration tips

Body

Response

​Overview

​Notes

​Trigger scenarios

​Message structure

​Example message

​data fields

​batchItemList item fields

​Code mapping

​Callback example

​Reward distribution batch success

​Integration tips

Body

Response

Overview

Notes

Trigger scenarios

Message structure

Example message

`data` fields

`batchItemList` item fields

Code mapping

Callback example

Reward distribution batch success

Integration tips