Webhook for Order Status
Introduction
Webhook for Order Status
Webhook will call merchant when order payment success/ failed/ overtime/ overtime and pay successfully.
Description
After the payment is completed, the relevant payment results and user information will be sent to the merchant in JSON format. The merchant needs to receive and process them, and respond according to the documentation specifications.
- The same notification may be sent to the merchant multiple times. The merchant must be able to handle duplicate notifications correctly.
- If the merchant's HTTP response code is not 200 or the response content does not include "success," the notification will be considered failed. Subsequent notifications will be retried with the following frequency: every 2 minutes within 10 minutes of the order, every 10 minutes within 1 hour of the order, and every 1 hour within 12 hours of the order.
- When handling notifications, the merchant should first check the status of the relevant business data to determine whether the notification has already been processed. If it has not been processed, continue processing; if it has been processed, return a successful response directly.
- Fields with values of null or "" are not included in the signature.
The merchant system must verify the signature of the payment result notification and check whether the returned order amount matches the amount on the merchant side. This is to prevent "false notifications" caused by data leaks, which could lead to financial losses.
Webhook Parameters
Parameter | Sign | Type | Length | Details |
---|---|---|---|---|
orderNo | Y | string | 64 | Order number |
orderStatus | Y | string | 32 | Order status (COMPLETED, CLOSE, TIMEOUT, FAILED, DELAY_SUCCESS, DELAY_FAILED) |
userId | Y | string | 128 | User id (email or phone number) |
merchantOrderNo | Y | string | 64 | User transaction number |
orderCurrency | Y | string | 32 | Fiat Currency of order (USD/EUR) |
orderAmount | Y | string | 16 | Order amount (Cent) |
payCryptoRate | Y | string | 16 | Payment crypto rate (to USDT) |
payFiatRate | Y | string | 16 | Payment Fiat rate (to USD) |
payCryptoCurrency | Y | string | 32 | Token of payment |
payCryptoVolume | Y | string | 16 | Amount of token payment |
payCryptoNetwork | Y | string | 32 | Network of token payment |
hxAddress | Y | string | 256 | Hash |
sign | N | string | 256 | Sign |
failReason | Y | string | 256 | Fail reason |
fee | Y | string | 16 | Handling Fee |
customParam | N | object | 512 | Customizable fields |
address | N | string | 64 | address |
Webhook Example
SUCCESS
{
"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
{
"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]"
}
Description of Order Status
Code | Details |
---|---|
COMPLETED | Payment success |
CLOSE | Payment close |
TIMEOUT | Payment cancel |
FAILED | Payment failure |
DELAY_SUCCESS | Order overtime and payment success |
DELAY_FAILED | Order overtime and payment failed |
Updated 4 days ago