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

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]"
}

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