订单Webhook
介绍
订单状态Webhook
Webhook会在订单支付成功/失败/超时/超时支付成功时调用商户。
说明
支付完成后,相关支付结果及用户信息会以JSON格式发送给商户,商户需要接收并处理,并按照文档规范进行响应。
- 同样的通知可能会多次发送给商户。商户必须能够正确处理重复的通知。
- 如果商户的 http 应答码不是 200 或响应内容未包含 success,会判定本次通知失败。后续会重新通知,通知频率为 10 分钟内订单每 2 分钟请求一次,1 小时内订单每 10 分钟请求一次,12 小时内订单每 1 小时请求一次。
- 商户在处理通知时,应先检查相应业务数据的状态,判断该通知是否已处理,若未处理,则继续处理,若已处理,则直接返回成功响应。
- 所有字段值为 null 或者 ””不参与签名
商户系统必须对支付结果通知进行签名验证,并检查返回的订单金额是否与商户端金额相符。防止数据泄露导致“误报”,造成经济损失。
Webhook 参数
参数名 | 验证 | 类型 | 长度 | 详情 |
---|---|---|---|---|
orderNo | Y | string | 64 | 订单号 |
orderStatus | Y | string | 32 | 订单状态 (COMPLETED, CLOSE, TIMEOUT, FAILED, DELAY_SUCCESS, DELAY_FAILED) |
userId | Y | string | 128 | 用户ID (邮箱或手机号码) |
merchantOrderNo | Y | string | 64 | 用户交易编号 |
orderCurrency | Y | string | 32 | 订单的法定货币 (USD/EUR) |
orderAmount | Y | string | 16 | 订单金额 (分) |
payCryptoRate | Y | string | 16 | 支付加密货币汇率 (到USDT) |
payFiatRate | Y | string | 16 | 支付法定货币汇率 (到USD) |
payCryptoCurrency | Y | string | 32 | 支付令牌 |
payCryptoVolume | Y | string | 16 | 令牌支付金额 |
payCryptoNetwork | Y | string | 32 | 令牌支付网络 |
hxAddress | Y | string | 256 | 哈希值 |
sign | N | string | 256 | 签名 |
failReason | Y | string | 256 | 失败原因 |
fee | Y | string | 16 | 手续费 |
customParam | N | object | 512 | 可定制字段 |
settlementCurrency | N | string | 16 | 入账金额币种 |
settlementAmount | N | string | 16 | 入账金额 |
address | N | string | 64 | 地址 |
Naddress# Webhook 示例
COMPLETED
{
"fee": "2",
"hxAddress": "2b04aa547740d8de8d442bc1827457b3e9bf4551234567893c319",
"merchantOrderNo": "to_4bc9603bc5c123456",
"orderAmount": "100",
"orderCurrency": "USD",
"orderNo": "3002172361782345678",
"orderStatus": "COMPLETED",
"payCryptoCurrency": "USDT",
"payCryptoNetwork": "TRX",
"payCryptoRate": "1",
"payCryptoVolume": "102",
"payFiatRate": "1",
"settlementAmount": "100",
"settlementCurrency": "USD",
"sign": "C615A4F6436CAA3C5B74AA80AF0CF08D342E7C49D0164765D3563EC3E3E61F889E9B46BB1E6F1EEEB28280DA233B81E31591C8B1A33C0EE7969CD3",
"userId": "u_dabd123456"
}
CLOSE
订单状态说明
参数名 | 详情 |
---|---|
COMPLETED | 支付成功 |
TIMEOUT | 支付取消 |
FAILED | 支付失败 |
DELAY_SUCCESS | 订单超时,支付成功 |
DELAY_FAILED | 订单超时,支付失败 |
Updated 6 days ago