1. API Webhook (Callback)介绍

📌

如果需要启用 webhook 功能，API 下单时候客户在请求的 Http 参数 callbackUrl 中填写 webhook 地址，没有则不进行通知，系统通过 POST JSON 数据回调通知客户;

Webhooks 当代收、代付订单状态有终态数据时，会发起 HTTP 回调。

2. Webhook 回调参数说明（HTTPS POST）

Http Header

参数	参数名称	参数类型	是否必填	案例
sign	签名字符串	String	是	ae3daa4e6739a3955d67981f

Http payload

参数	参数名称	参数类型	是否必填	案例
mchOrderId	商户订单号	String	是	Deffe998283
orderId	平台订单号	String	是	202304141646943827467169734
bankId	银行订单号	String	否	DF55BA0F441A
orderStatus	订单状态; 成功:SUCCESS; 失败:FAILED; 撤销:REVERSED; 处理中:PAYING; 详情参考订单状态说明	String	是	SUCCESS
amount	订单金额（元）;保留 2 位小数	String	是	1.00
realAmount	实际金额（元）;保留 2 位小数	String		1.00
orderType	订单类型; PAYMENT:收款; PAYOUT:出款;	String	是	PAYMENT
failMessage	失败原因	String	否
createTime	创建时间(零时区); 格式:yyyyMMddHHmmss;	String	是	20230307000000
transIds	扩展订单号	String	否	EDF55BA0F441A
payMethod	支付方式	String	否	PIX
mchFee	商户手续费	String	否	2.00
currency	币种	String	否
USD

必须响应 success 或者 200 表示请求接受成功，否则非 success 或者 200 ，会发起回调重试，重试时间回调会按 5 min * 回调次数递增尝试 7 次

Webhook 回调案例

3. Webhook Header Sign 签名规则

📌

签名字符串 signBody = http paload + key
http paload 为回调的JSON数据，请不要封装对象，直接拿返回数据签名先
key 为商户密钥
生成签名算法与下单一致

签名案例

// 参考回调案例
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==

// 判断签名是否正确
Digester d = DigestUtil.digester(DigestAlgorithm.SHA512);  
String sign = d.digestHex(signBody);
Boolean verifyResult=StrUtil.equals(sign,request.getHeader('sign'))

4. Webhook 回调测试验证

📌

自助登录后管平台后，通过API下完单，可以查询处理中的订单，点击 mock success 和 mock fail 按钮，分别模拟回调 webhook url 地址订单成功和失败通知，方便验证签名和报文，实际交易不记账处理

5. Webhook 回调 IPs 地址

地区	Webhook IPs
北美洲	`18.228.164.232`、`18.228.73.43`、`54.233.252.236`、`54.94.8.45`
南美洲	`18.228.164.232`、`18.228.73.43`、`54.233.252.236`、`54.94.8.45`
亚洲	`13.200.70.4`、`15.207.47.92`、`3.108.48.106`、`43.205.72.188`
中东	`13.200.70.4`、`15.207.47.92`、`3.108.48.106`、`43.205.72.188`
欧洲	`13.200.70.4`、`15.207.47.92`、`3.108.48.106`、`43.205.72.188`
非洲	`13.200.70.4`、`15.207.47.92`、`3.108.48.106`、`43.205.72.188`

WebHook 介绍

1. API Webhook (Callback)介绍#

2. Webhook 回调参数说明（HTTPS POST）#

3. Webhook Header Sign 签名规则#

4. Webhook 回调测试验证#

5. Webhook 回调 IPs 地址#

1. API Webhook (Callback)介绍

2. Webhook 回调参数说明（HTTPS POST）

3. Webhook Header Sign 签名规则

4. Webhook 回调测试验证

5. Webhook 回调 IPs 地址