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 correctly handle duplicate notifications.

The notification will be resent until merchant's response HTTP status code is 200 and the return msg contains "success".

Multiple notification attempts may occur in such cases. The notification frequency is as follows:

• For orders within 10 minutes, a request will be made every 10 seconds.
• For orders within 1 hour, a request will be made every 1 minute.
• For orders within 24 hours, a request will be made every 10 minutes.

🚧

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.

When processing a notification, the merchant should first check the status of the corresponding business data to determine if the notification has already been processed. If not processed, the merchant should proceed with handling. If already processed, the merchant can return a success response directly.

Before performing status checks and processing business data, the merchant should use data locks for concurrent control to prevent data confusion caused by function re-entry.

Fields with values of null should not be included in the signature.

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

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": "USDT",
    "vCryptoNetwork": "BTC",
    "payCryptoRate": "123.4",
    "payCryptoVolume": "123",
    "payFaitRate": "1.23",
    "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]"
}

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