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

Webhook Status Codes

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

Webhook Parameter Example

Example (JSON)

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