订单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

JSON

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

JSON

{
    "payCryptoCurrency": "ACH",
    "vCryptoNetwork": "BTC",
    "payCryptoRate": "123.4",
    "payCryptoVolume": "123",
    "payFiatRate": "1.23",
    "address": "adfdsafdsafdsafdsafadsfdsaf",
    "customParam": "customParam",
    "failReason": "crypto or network inconsistent",
    "fee": "1.1",
    "hxAddress": "aweweas",
    "merchantOrderNo": "9999999999",
    "orderAmount": "12",
    "orderCurrency": "EUR",
    "orderNo": "300217177567252640030",
    "orderStatus": "CLOSE",
    "settlementAmount": "0",
    "settlementCurrency": "USD",
    "sign": "B42DA144E9BD180F83E8E7EBD2A9F933798616819FF1BBE4AD4C84081073ECB85BD67F850D25303C5FD9CDF17FE82DD4DD0AAA44F9B7D6121EF17DE3428EFF1C",
    "userId": "[email protected]"
}

订单状态说明

参数名	详情
COMPLETED	支付成功
CLOSE	支付关闭
TIMEOUT	支付取消
FAILED	支付失败
DELAY_SUCCESS	订单超时，支付成功
DELAY_FAILED	订单超时，支付失败