Introduction

This webhook notification informs merchants when an order is successfully paid or fails. If needed, merchants should provide the refund callback URL for configuration.

Upon payment completion, the payment result and user information are sent to the merchant in JSON format. Notifications may be sent multiple times, so the merchant must handle duplicate notifications correctly. If the merchant's HTTP response does not equal 200 or does not include "success", the notification is considered failed, triggering retries. Notifications are sent at these intervals:

Every 2 minutes for the first 10 minutes
Every 10 minutes for the first hour
Every hour for the next 12 hours

To prevent "fake notifications" that could cause financial loss, the merchant must validate the signature of the payment result notification and verify that the returned order amount matches the merchant’s order amount.

Processing Notifications

Check the business data status to determine if the notification has already been processed.
If unprocessed, proceed with handling. If already processed, return a success result.
Use data locks for concurrency control to avoid issues from function re-entry.

Fields that are empty (null or "") are not included in the signature.

Refund Webhook Parameters

Parameter	Signature Required	Type	Length	Description
refundType	Yes	string	64	Refund type
merchantOrderNo	Yes	string	64	Merchant order number
paymentOrderNo	Yes	string	64	ACH payment order number
orderStatus	Yes	string	16	Refund order status
tokenAmount	Yes	string	32	Token amount
faitAmount	Yes	string	16	Fiat amount
fiatCurrency	Yes	string	16	Fiat currency
refundNetwork	Yes	string	32	Refund network (e.g., TRX)
refundToken	Yes	string	32	Refund token (e.g., USDT)
refundOrderNo	Yes	string	64	ACH refund order number
hxAddress	Yes	string	256	Hash address
sign	No	string	128	Signature Check on About the sign

Webhook Status Codes

Code	Description
`COMPLETED`	Refund succeeded
`FAILED`	Refund failed

Webhook Parameter Example

{
    "faitAmount": "9.90000000",
    "fiatCurrency": "USD",
    "hxAddress": "05b40909e7dd03cd0c1303c1e740edaa682f15ea7ed4af3bca5adffbe10da277",
    "merchantOrderNo": "17304484880000",
    "orderStatus": "COMPLETED",
    "paymentOrderNo": "300317304490044680240",
    "refundNetwork": "TRX",
    "refundOrderNo": "300217304490044230335",
    "refundToken": "USDT",
    "refundType": "MERCHANT_APPROVE_REFUND",
    "sign": "C2A745E335DE17F3D0C6F2920CD62A96F6F8445E692ED5CDE7EED35BF8AF7B2BC298CC2440700A6F3323A71D18C5200B793286B340B8AB6B67F99424C1B3A154",
    "tokenAmount": "8.40000000"
}