Webhook Notification

Introduction

When the order's status changes, merchants will receive our notification and should take automated actions accordingly.

Here is the event list that triggers the notification:

Order Status	Description
14	Transaction is successful
15	Transaction is failed

Set the Notification Endpoint

There are two ways to set it,

1. Pass it as a parameter (callBackURL) when calling the pay-in endpoint.

2. Configure it in Merchant Console. Navigate to User Center / User Center / Basic Information / Callback URL of a successful payment, and configure it.

Security of Webhook

Funds security is of utmost importance!

Therefore, we have developed a solution to prevent fake notifications. Here are the steps:

• Step 1: On our end, a parameter sign will be included in the notification body.

• Step 2: On your end, you have two options:

  • Option 1: Verify the sign to ensure the authenticity of the notification.

  • Option 2: Retrieve the orderStatus by using the endpoint Query Payment again. It is advised not to solely rely on the orderStatus field provided in the notification body.

By implementing these measures, we aim to enhance the security of the funds and prevent any fraudulent action.

Retry Mechanism

If you provide an invalid notification endpoint, you will not receive any notification.

However, if you provide a valid notification endpoint, we will attempt to notify you 11 times with the following intervals:

Attempt	Interval (in minutes)
1	0
2	1
3	3
4	7
5	15
6	31
7	63
8	127
9	255
10	511
11	1023

Notification Method and Data

Method

HTTP POST

Content-Type: application/x-www-form-urlencoded

Data

Field	Type	Description
merchantId	int64	the unique id generated by us
merchantTradeNo	string	the unique id of transaction generated by merchant
merchantUserId	string	the unique id of user generated by merchant
orderId	string	the unique id of transaction generated by us
orderStatus	int	see details here
orderAmount	string	amount paid by the user
receivedAmount	string	amount received by merchant's account for this transaction
serviceFee	string	commission amount charged by us
actualAmount	string	deprecated
fee	string	deprecated, replace by serviceFee
currency	string	e.g. USD,EUR,GBP etc.
cryptoCurrency	string	deprecated, only works for CryptoCurrency
network	string	deprecated, only works for CryptoCurrency
hash	string	deprecated, only works for CryptoCurrency
remark	string	description of the transaction status
createTime	int64	transaction created time in us (millisecond)
sign	string	for data security, generate by algorithm

Expected Response

Our webhook service experts the only two response values in a TEXT, not a JSON or others.

• success

• fail

If fail or an empty string is received, the webhook service will retry later.

Example

curl -X POST '{callback URL of merchant}' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'param={JSON String}'

The following is some JSON data examples.

COMPLETED

{
  "merchantId": 2000001, 
  "merchantTradeNo": "M100002",
  "merchantUserId": "UID12345",
  "orderId": "23033112345965", 
  "cryptoCurrency": "USD",
  "currency": "USD",
  "serviceFee": "1.01",
  "fee": "1.01",
  "orderAmount": "22.33",
  "receivedAmount": "21.32",
  "actualAmount": "22.33",
  "orderStatus": 14, 
  "network": "TRON(TRC-20)",
  "hash": "0x8bd283cf44643e66a1bbe64817ca593f18dbf78d5ce8a725bc29bf", 
  "remark": "success", 
  "createTime": 1685758334422,
  "sign": "9aa9b34e950061f1bb1e9ccd6fadcedab8e354f6"
}

{
  "merchantId": 2000001, 
  "merchantTradeNo": "M100002",
  "merchantUserId": "UID12345",
  "orderId": "23033112345965", 
  "cryptoCurrency": "USD",
  "currency": "USD",
  "serviceFee": "1.01",
  "fee": "1.01",
  "orderAmount": "22.33",
  "receivedAmount": "21.32",
  "actualAmount": "22.33",
  "orderStatus": 14, 
  "network": "",
  "hash": "", 
  "remark": "success", 
  "createTime": 1685758334422,
  "sign": "9aa9b34e950061f1bb1e9ccd6fadcedab8e354f6"
}

CLOSED

{
  "merchantId": 2000001, 
  "merchantTradeNo": "M100002",
  "merchantUserId": "UID1234x", 
  "orderId": "23033112345965", 
  "cryptoCurrency": "USD",
  "currency": "USD",
  "serviceFee": "1.01",
  "fee": "1.01",
  "orderAmount": "22.33",
  "receivedAmount": "21.32",
  "actualAmount": "22.33",
  "orderStatus": 15, 
  "network": "",
  "hash": "", 
  "remark": "Payment Abandoned", 
  "createTime": 1685758334422,
  "sign": "9aa9b34e950061f1bb1e9ccd6fadcedab8e354f6"
}