Payout Callback

Payout callbacks use the same signature headers and retry mechanism as pay-in callbacks.

The platform calls back only when a payout reaches the confirmed or failed final state.

POSTnotifyUrl from the create payout order request body

Request Headers

Field	Type	Required	Description
content-type	application/json	Yes	Always application/json.
x-callback-timestamp	string	Yes	Callback timestamp in milliseconds.
x-callback-nonce	string	Yes	Callback nonce.
x-callback-signature	string	Yes	HMAC-SHA256(apiKey, timestamp + "." + nonce + "." + rawBody)。
x-callback-signature-algorithm	string	Yes	Always HMAC-SHA256.
x-callback-signature-version	string	Yes	Always v1.

Request Parameters

Field	Type	Required	Description
merchantUid	string	Yes	Merchant UID.
orderNo	string	Yes	Platform payout order number.
merchantOrderNo	string \| null	Yes	Merchant order number.
chainCode	string	Yes	Chain code.
tokenSymbol	string	Yes	Token symbol.
fromAddress	string \| null	Yes	Sender address.
toAddress	string	Yes	Receiving address.
txHash	string \| null	No	On-chain hash.
amount	string	Yes	Payout amount.
status	string	Yes	Final payout state: confirmed or failed.
failedStage	string	No	Returned only when status=failed.

Request Example

{
  "merchantUid": "880001",
  "orderNo": "PO1776193200A1B2C3D4",
  "merchantOrderNo": "PO202604150001",
  "chainCode": "TRON",
  "tokenSymbol": "USDT",
  "fromAddress": "TNjBrNq2a9FK2vwu4W9C1QdLKSZ42Yx5YY",
  "toAddress": "TS7b7iD8G2PaPqK1TqSmLJ9nrrYH4oKX1S",
  "txHash": "b3d4fb0cb11eb86bb906d1e0ee3b84e17f40d5441d1e4c651ea46920a48a9a01",
  "amount": "35.500000",
  "status": "confirmed"
}

Response Fields

Field	Type	Required	Description
HTTP Status	200-299	Yes	Any 2xx response is treated as success.
Response Body	string \| json	No	The response body can be customized.

Response Example

HTTP/1.1 200 OK
Content-Type: text/plain

success

Code Examples

Express Handler Example

app.post('/merchant/callback', (req, res) => {
  if (req.body.status === 'confirmed') {
    // 代付成功
  }

  if (req.body.status === 'failed') {
    // 代付失败
  }

  return res.status(200).send('success');
});

Notes

Handle callbacks idempotently by orderNo; only confirmed or failed final states are sent automatically.