Appearance
WebHook
请求地址
商户在调用平台网关接口时提供,参看 payment/payout
创建接口请求 notifyUrl
参数。
请求参数
HTTP Header
字段 | 数据类型 | 长度限制 | 是否必填项 | 说明 |
---|---|---|---|---|
Accept | String | N/A | 字段值为 application/json | |
Content-Type | String | N/A | 是 | 字段值为 application/json |
Authorization | String | 是 | Authorization: {type} {credentials},详情参考签名规范部分 | |
X-Notify-Event | Enum String | 50 | 是 | 取值范围见触发事件定义 |
HTTP Body
字段 | 数据类型 | 必填项 | 说明 |
---|---|---|---|
event | Enum String | 是 | 取值范围见触发事件定义 |
code | String | 是 | 值为 OK |
errorMessage | String | 否 | 值为 null |
data | JSON Object | 是 | data 字段为通知事件对应的业务实体对象,具体字段同各个业务查询接口响应结果的 data 字段。 |
业务实体对象字段说明
响应结果
HTTP Status
商户接收推送成功,返回 200
HTTP Header
字段 | 数据类型 | 是否必填项 | 说明 |
---|---|---|---|
Content-Type | String | 是 | 字段值只支持 application/json |
Authorization | String | 是 | Authorization: {type} {credentials},详情参考签名规范部分 |
HTTP Body
字段 | 数据类型 | 是否必填项 | 说明 |
---|---|---|---|
code | String | 是 | code 值为 OK 代表商户接收并处理成功,其它值表示接收成功处理失败 |
errorMessage | String | 否 |
商户返回错误码
错误码 | 描述 | 解决方案 |
---|---|---|
OK | 处理成功 | |
FAIL | 处理失败 | 待支付平台网关重新通知 |
示例
平台请求
Bash
curl https://{{merchant_notify_url}} \
-X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H 'Authorization: V2_SHA256 appId=483f6c9c743b4a9bbd34bee0c9c81eb7,sign=7363f5c7746b79863326940e8b25ffb0f1f7fec22382f036a6b06f8b9e290229,timestamp=1715410373693,nonce=29E890BE88FFAE17DCB2985502F50C92' \
-d '{"key1": "value1", "key2": "value2"}'
商户响应
- 处理成功响应
HTTP
HTTP/1.1 200 OK
Content-Type: application/json
Date: Mon, 06 Mar 2024 12:00:00 GMT
{
"code": "OK"
}
- 处理失败响应
HTTP
HTTP/1.1 200 OK
Content-Type: application/json
Date: Mon, 06 Mar 2024 12:00:00 GMT
{
"code": "FAIL",
"errorMessage": "根据实际情况填充相关错误信息"
}
网关处理商户响应策略
当符合以下条件时,网关按策略重复通知,直到超过系统配置的阈值
- 通知接口响应非 200 状态码
- 通知接口响应结果 code 值不等于 OK
- 通知接口超时无响应
事件定义
事件命名:{entity}.{domain_event}
通知事件 | 描述 | 默认开启 |
---|---|---|
PAYMENT.PAID | 收单成功 | 是 |
PAYOUT.PAID | 代付成功 | 是 |
PAYOUT.FAILURE | 代付失败 | 是 |
PAYOUT.REVERSED | 代付退票 | 是 |
PAYOUT.CANCELLED | 代付取消 | 是 |
商户处理建议
TIP
- 对推送消息做幂等处理,避免重复处理
- 成功接收推送消息后,异步处理业务逻辑,以免同步处理时间过长导致网关判定处理超时进行重复推送
- 成功接收推送消息后,处理业务逻辑时考虑并发场景