支付通知接入说明
约 1448 字大约 5 分钟
2025-03-07
异步通知概述
- 首先，商户侧配置异步回调通知
notificationUrl地址。 - 每当，交易相关事件发生时（如交易成功），PingPongCheckOut 通知服务将会创建一个JSON对象，其中包含事件相关的数据等信息。
- 然后，PingPongCheckOut 通知服务通过 HTTP POST 请求将JSON对象发送到开发者配置的回调通知
notificationUrl中。 商户侧在收到回调通知后，可根据异步通知报文做下一步的业务处理。
其流程描述如下：
接收异步通知
准备一个支持 HTTP POST 的web服务
PingPongCheckOut 通知服务将以 HTTP POST 方式推送 JSON 格式的数据，因此开发者所提供的 Web 服务需要能够接收并解析来自HTTP POST 请求的 JSON 数据并能够返回相应 HTTP 状态码。
设置回调通知地址
开发者可以通过各接口入参中的 notificationUrl 参数配置回调通知Url地址。
- notificationUrl 需要填写商户自己系统的真实地址，不能填写接口文档或demo上的示例地址。
- notificationUrl 必须是以https://或http://开头的完整全路径地址，并且确保URL中的域名和IP是外网可以访问的，不能填写localhost、127.0.0.1、192.168.x.x等本地或内网IP。
- notificationUrl 不能携带参数。
正确示例
- 完整公网地址：
https://example.pay.cn:8080/notify/receive - 使用公网 IP 且包含服务路径：
https://122.X.X.5:8080/notify/receive
错误示例
- 只有相对路径：
./PayNotify.aspx - 只有地址，没有具体服务路径：
https://example.demo.cn:80 - 本地内网地址，互联网无法访问：
https://localhost:8080/notify/
接收并响应
对于商户交易通知响应，遵循以下约定：
| 接收结果 | HTTP Code 约定 | 应答报文格式约定 |
|---|---|---|
| 接收成功 | 200 <= httpcode < 300，比如：200、201、204 | 无需返回应答报文（返回不会产生影响） |
| 接收失败 |
|
|
提示
重试机制：接收失败的情况下会触发重试机制，PingPongCheckout 会在随后的一段时间内，以递增的时间间隔重发，间隔为 5s/5s/3m/10m/20m/30m/30m/30m/60m/3h/3h/3h（若中间重试通知成功，则中断不再继续重试）。
注意
- 商户不能仅仅依赖于异步通知，如果⻓时间未收到交易结果，商户应该主动向 PingPongCheckout 发起交易查询，查询对应的交易结果。
- 请不要在
notificationUrl后面携带query类型的参数，以免丢失，如果一定要携带，请使用pathInfo的URL模式。 - 异步通知代码处理逻辑不能做登录态校验。
PingPongCheckout回调通知服务器信息
如果商户侧需要防火墙配置后才允许 PingPongCheckout 消息通知服务推送数据，请根据下方信息进行防火墙设置，将IP加入到白名单：
生产环境
| 区域 | IP地址 |
|---|---|
| EU | 3.125.243.2 |
| EU | 3.126.196.22 |
| EU | 18.195.199.34 |
| SG | 188.239.12.25 |
| US | 52.40.91.195 |
| US | 44.253.41.116 |
| US | 54.187.20.194 |
沙箱环境
| IP地址 |
|---|
| 52.76.198.228 |