Order Webhook

Introduction

Webhook for payment notification.

Webhook will call merchant when order payment COMPLETED, FAILED and PENDING.

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.
• 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.

Webhook Parameters

Parameter	Sign	Type	Length	Details
orderNo	Y	string	64	Order number
orderStatus	Y	string	32	Order status
userId	Y	string	128	User id (email or phone number)
userIp	Y	string	128	User IP address
usdAmount	Y	string	32	Order amount count as USD
fiatAmount	Y	string	16	Order amount count as payment fiat currency
fiatCurrency	Y	string	16	Payment fiat currency
fiatRate	Y	string	16	Payment Fiat rate (to USD)
fee	Y	string	16	Handling Fee
qrCode	Y	string	32	QRcode address
merchantOrderNo	Y	string	64	Merchant order number
failReason	Y	string	256	Fail reason
orderTime	Y	string	256	UTC+8 time zone, formatted as yyyy-MM-dd hh:mm:ss
sign	N	string	256	Signature

Webhook Example

COMPLETED

JSON

{
    "orderNo": "31313131311111",
    "orderStatus": "COMPLETED",
    "userId": "[email protected]",
    "userIp": "127.0.0.1",
    "usdAmount": "10.01",
    "fiatAmount": "100001",
    "fiatCurrency": "VND",
    "fiatRate": "2111",
    "fee": "2.1",
    "qrCode": "00020101021138580010A000000727012800069704070114190360421800120208QRIBFTTA53037045802VN830084006304EDC5",
    "merchantOrderNo": "313131",
    "failReason": "",
    "orderTime": "2023-12-09 18:34:26",
    "sign": "B42DA144E9BD180F83E8E7EBD2A9F933798616819FF1BBE4AD4C84081073ECB85BD67F850D25303C5FD9CDF17FE82DD4DD0AAA44F9B7D6121EF17DE3428EFF1C"
}

Description of Order Status

Code	Details
PENDING	Payment processing
COMPLETED	Payment success
FAILED	Payment failure