Guides
Start typing to search…

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)

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 Check on about the 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

{
    "fee": "2",
    "hxAddress": "2b04aa547740d8de8d442bc1827457b3e9bf4551234567893c319",
    "merchantOrderNo": "to_4bc9603bc5c123456",
    "orderAmount": "100",
    "orderCurrency": "USD",
    "orderNo": "3002172361782345678",
    "orderStatus": "COMPLETED",
    "payCryptoCurrency": "USDT",
    "payCryptoNetwork": "TRX",
    "payCryptoRate": "1",
    "payCryptoVolume": "102",
    "settlementAmount": "100",
    "settlementCurrency": "USD",
    "sign": "C615A4F6436CAA3C5B74AA80AF0CF08D342E7C49D0164765D3563EC3E3E61F889E9B46BB1E6F1EEEB28280DA233B81E31591C8B1A33C0EE7969CD3",
    "userId": "u_dabd123456"
}

CLOSE

{
    "payCryptoCurrency": "USDT",
    "vCryptoNetwork": "BTC",
    "payCryptoRate": "123.4",
    "payCryptoVolume": "123",
    "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

TIMEOUT

Payment cancel

FAILED

Payment failure

DELAY_SUCCESS

Order overtime and payment success

DELAY_FAILED

Order overtime and payment failed

ORDER_EXCEPTION

User pays repeatedly. If an order is paid multiple times, only the first payment will be marked as successful, and subsequent payments will be marked as order_exception and send webhook

Updated 4 days ago