Skip to content

WebHook

请求地址

商户在调用平台网关接口时提供,参看 payment/payout 创建接口请求 notifyUrl 参数。

请求参数

HTTP Header

字段数据类型长度限制是否必填项说明
AcceptStringN/A字段值为 application/json
Content-TypeStringN/A字段值为 application/json
AuthorizationStringAuthorization: {type} {credentials},详情参考签名规范部分
X-Notify-EventEnum String50取值范围见触发事件定义

HTTP Body

字段数据类型必填项说明
eventEnum String取值范围见触发事件定义
codeString值为 OK
errorMessageString值为 null
dataJSON Objectdata 字段为通知事件对应的业务实体对象,具体字段同各个业务查询接口响应结果的 data 字段。

业务实体对象字段说明

响应结果

HTTP Status

商户接收推送成功,返回 200

HTTP Header

字段数据类型是否必填项说明
Content-TypeString字段值只支持 application/json
AuthorizationStringAuthorization: {type} {credentials},详情参考签名规范部分

HTTP Body

字段数据类型是否必填项说明
codeStringcode 值为 OK 代表商户接收并处理成功,其它值表示接收成功处理失败
errorMessageString

商户返回错误码

错误码描述解决方案
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

  • 对推送消息做幂等处理,避免重复处理
  • 成功接收推送消息后,异步处理业务逻辑,以免同步处理时间过长导致网关判定处理超时进行重复推送
  • 成功接收推送消息后,处理业务逻辑时考虑并发场景