---
url: >-
https://acquirer-api-docs-v4-en.pingpongx.com/notes/zh/onlinePayment/developer/paymentNotify/index.md
description: 说明如何配置和接收支付异步通知，覆盖 notificationUrl、通知报文、响应要求、IP 白名单和重试机制。
---
## 异步通知概述
- 首先，商户侧配置异步回调通知`notificationUrl`地址。
- 每当，交易相关事件发生时（如交易成功），PingPongCheckOut 通知服务将会创建一个JSON对象，其中包含事件相关的数据等信息。
- 然后，PingPongCheckOut 通知服务通过 HTTP POST 请求将JSON对象发送到开发者配置的回调通知`notificationUrl`中。
商户侧在收到回调通知后，可根据异步通知报文做下一步的业务处理。
其流程描述如下：
```mermaid
sequenceDiagram
participant 买家 as 🛒 买家
participant 商户前端 as 💻 商户前端
participant 商户业务系统 as 🏪 商户业务系统
participant PingPong as 🔄 PingPongCheckOut
Note over 买家,PingPong: 下单与支付流程
买家->>商户前端: 1. 选择商品并结算
商户前端->>商户业务系统: 2. 请求创建订单
商户业务系统->>PingPong: 3. 创建支付订单（POST /orders）
PingPong-->>商户业务系统: 4. 返回支付订单信息（含 checkoutUrl）
商户业务系统-->>商户前端: 5. 返回支付链接
商户前端-->>买家: 6. 展示支付选项
商户前端-->>买家: 7. 跳转支付页面（checkoutUrl）
买家->>PingPong: 8. 在支付页面完成支付
Note over 商户业务系统,PingPong: 异步通知流程
PingPong-->>商户业务系统: 9. 异步通知支付结果
Note over 商户业务系统,PingPong: 支持重试机制（详见重试流程图）
商户业务系统-->>PingPong: 10. 确认接收通知
商户业务系统-->>商户前端: 11. 传递支付结果
商户前端-->>买家: 12. 显示支付结果
opt 主动查询支付结果（可选）
商户业务系统->>PingPong: 13. 查询订单状态
PingPong-->>商户业务系统: 14. 返回最新订单状态
end
```
[//]: # ()
## 接收异步通知
### 准备一个支持 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 | 无需返回应答报文（返回不会产生影响） |
| 接收失败 | - `httpcode` > 300 或 `httpcode` < 200
- 200 <= `httpcode` < 300，比如：200、201、204
| |
:::note 提示
重试机制：接收失败的情况下会触发重试机制，PingPongCheckout 会在随后的一段时间内，以递增的时间间隔重发，间隔为 `5s/5s/3m/10m/20m/30m/30m/30m/60m/3h/3h/3h`（若中间重试通知成功，则中断不再继续重试）。
:::
```mermaid
sequenceDiagram
participant 商户 as 🏪 商户业务系统
participant 通知服务 as 📡 PingPongCheckOut通知服务
Note over 通知服务,商户: 首次通知
通知服务-->>商户: 1. HTTP POST 推送 JSON 通知
商户-->>通知服务: 2. 返回处理结果
alt 接收成功（HTTP 2xx 且报文体不返回 FAIL）
Note over 通知服务,商户: 通知流程结束
else 接收失败
Note over 通知服务,商户: 进入重试机制（5s/5s/3m/10m/20m/30m/30m/30m/60m/3h/3h/3h）
loop 每次重试重复“推送通知 -> 返回处理结果”
通知服务-->>商户: 3. 重试推送通知
商户-->>通知服务: 4. 返回处理结果
end
Note over 通知服务,商户: 任一重试成功即停止后续重试
end
```
:::warning 注意
1. 商户不能仅仅依赖于异步通知，如果⻓时间未收到交易结果，商户应该主动向 PingPongCheckout 发起交易查询，查询对应的交易结果。
2. 请不要在`notificationUrl`后面携带query类型的参数，以免丢失，如果一定要携带，请使用pathInfo的URL模式。
3. 异步通知代码处理逻辑不能做登录态校验。
:::
## 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 |
## 通知报文
交易异步通知
退款异步通知
预授权请款通知
预授权撤销通知