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 merchant must be able to handle duplicate notifications correctly or the same notification may be sent to the merchant multiple times.
• Merchant's HTTP response code need to be 200 or the response content include success, the notification will be successed. 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.

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
address	N	string	64	User Address
payNo	N	string	64	User payment number(Requires configuration)
settlementAmount	N	string	16	Entered amount
settlementCurrency	N	string	16	Currency of entry amount
payMethod	N	string	16	only affect while using WALLET CONNECT and TON CONNECT Payment method user used
fromAddress	N	string	256	only affect while using WALLET CONNECT and TON CONNECT User address for token transfer
discountAmount	N	string	256	discount amount (in USD)

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