订单Webhook

介绍

订单状态Webhook

Webhook会在订单支付成功/失败/超时/超时支付成功时调用商户。

说明

👍

支付完成后，相关支付结果及用户信息会以JSON格式发送给商户，商户需要接收并处理，并按照文档规范进行响应。

同一条通知可能会多次发送给商户，商户必须正确处理重复通知。

直到商户响应HTTP状态码为200，且返回信息包含“success”时，通知才会重新发送。

此类情况下可能会发生多次通知尝试。通知频率如下：

• 10分钟内的订单，每10秒发送一次请求。
• 1小时内的订单，每1分钟发送一次请求。
• 24小时内的订单，每10分钟发送一次请求。

🚧

商户系统必须对支付结果通知进行签名验证，并检查返回的订单金额是否与商户端金额相符。防止数据泄露导致“误报”，造成经济损失。

商户在处理通知时，应先检查相应业务数据的状态，判断该通知是否已处理，若未处理，则继续处理，若已处理，则直接返回成功响应。

商户在进行状态检查和业务数据处理前，应使用数据锁进行并发控制，防止函数重入导致数据混乱。

签名中不应包含值为 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	令牌支付网络
address	N	string	256	ACH地址 (用户将加密货币发送到此地址)
hxAddress	Y	string	256	哈希值
sign	N	string	256	签名
failReason	Y	string	256	失败原因
fee	Y	string	16	手续费
customParam	N	object	512	可定制字段

Webhook 示例

JSON

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

订单状态说明

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