1. API Webhook (Callback) Introduction

📌

To enable the webhook feature, merchants must specify the webhook URL in the 【callbackUrl】 parameter during API order placement. If no URL is provided, no notifications will be sent. The system will callback to notify merchants via POST JSON data.

Webhooks trigger HTTP callbacks when collection or payout orders reach final status.

2. Webhook Callback Parameters（HTTPS POST）

Http Header

Parameter	Name	Type	Required	Example
sign	Signature String	String	Y	ae3daa4e6739a3955d67981f

Http payload

Parameter	Name	Type	Required	Example
mchOrderId	Merchant Order Number	String	Y	Deffe998283
orderId	Platform Order Number	String	Y	202304141646943827467169734
bankId	Bank Order Number	String	N	DF55BA0F441A
orderStatus	Order Status; SUCCESS; FAILED; REVERSED; PAYING; Details refer toOrder Status	String	Y	SUCCESS
amount	Order Amount (in currency unit); 2 decimal places retained	String	Y	1.00
realAmount	Actual Amount (in currency unit); 2 decimal places retained	String		1.00
orderType	Order Type; PAYMENT PAYOUT	String	Y	PAYMENT
failMessage	Failure Reason	String	N
createTime	Creation Time (UTC); Format: yyyyMMddHHmmss;	String	Y	20230307000000
transIds	Extended Order Number	String	N	EDF55BA0F441A
payMethod	Payment Method	String	N	PIX
mchFee	Merchant Fee	String	N	2.00
currency	Currency	String	N
USD

The response must be "success" or HTTP status 200 to indicate successful receipt of the request. Otherwise, if the response is not "success" or 200, the system will retry the callback up to 7 times with increasing intervals (5 minutes * callback attempt count).

Webhook Callback Example

3. Webhook Header Signature Rules

📌

Signature string signBody = http payload + key

http payload is the callback JSON data (use the raw returned data for signing without encapsulation)

key is the merchant secret key

The signature generation algorithm is consistent with order placement 【sha512】

Signature Example

// Reference callback example
payload ={"realAmount":"166840.0","orderType":"PAYOUT","bankId":"9jZVPfXobPGXXnt","amount":"166840.0","createTime":"20250812091550","orderId":"202508121955196515039150080","payMethod":"NET_BANKING","orderStatus":"SUCCESS","mchOrderId":"W20250812091450181OT","failMessage":"fix order to SUCCESS"} 

// signBody = http paload + key
signBody = {"realAmount":"166840.0","orderType":"PAYOUT","bankId":"9jZVPfXobPGXXnt","amount":"166840.0","createTime":"20250812091550","orderId":"202508121955196515039150080","payMethod":"NET_BANKING","orderStatus":"SUCCESS","mchOrderId":"W20250812091450181OT","failMessage":"fix order to SUCCESS"}Dkfldkfl==

// Verify signature correctness
Digester d = DigestUtil.digester(DigestAlgorithm.SHA512);  
String sign = d.digestHex(signBody);
Boolean verifyResult=StrUtil.equals(sign,request.getHeader('sign'))

4. Webhook Callback Testing & Verification

📌

After logging into the Dashboard, merchants can test webhook functionality by placing orders via API and querying pending orders. Click the "mock success" and "mock fail" buttons to simulate successful and failed order notifications respectively to the webhook URL, facilitating signature and message verification. Actual transactions are not recorded during testing.

5. WebhookWebhook Callback IP Addresses

Zone	Webhook IPs
North America	`18.228.164.232`、`18.228.73.43`、`54.233.252.236`、`54.94.8.45`
South America	`18.228.164.232`、`18.228.73.43`、`54.233.252.236`、`54.94.8.45`
Asia	`13.200.70.4`、`15.207.47.92`、`3.108.48.106`、`43.205.72.188`
Mid East	`13.200.70.4`、`15.207.47.92`、`3.108.48.106`、`43.205.72.188`
Europe	`13.200.70.4`、`15.207.47.92`、`3.108.48.106`、`43.205.72.188`
Africa	`13.200.70.4`、`15.207.47.92`、`3.108.48.106`、`43.205.72.188`

APIs WebHook

1. API Webhook (Callback) Introduction#

2. Webhook Callback Parameters（HTTPS POST）#

3. Webhook Header Signature Rules#

4. Webhook Callback Testing & Verification#

5. WebhookWebhook Callback IP Addresses#

1. API Webhook (Callback) Introduction

2. Webhook Callback Parameters（HTTPS POST）

3. Webhook Header Signature Rules

4. Webhook Callback Testing & Verification

5. WebhookWebhook Callback IP Addresses