--- 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 中的域名是外网可以访问的，不能填写 localhost、127.0.0.1、192.168.x.x 等本地或内网地址。 - notificationUrl 建议使用标准 Web 端口：`https://` 默认使用 443 端口，`http://` 默认使用 80 端口。 - 如需区分不同业务场景，建议使用路径形式，例如 `/notify/payment`、`/notify/refund`。 #### 正确示例 - 完整公网地址：`https://pay.example.com/notify/receive` - 使用不同业务路径：`https://pay.example.com/callback/payment` - HTTP 标准端口地址：`http://notify.example.com/receive` #### 错误示例 - 只有相对路径：`./PayNotify.aspx` - 只有地址，没有具体服务路径：`https://example.demo.cn` - 本地内网地址，互联网无法访问：`https://localhost:8080/notify/` ### 接收并响应 对于商户交易通知响应，遵循以下约定： | 接收结果 | HTTP Code 约定 | 应答报文格式约定 | |------|--------------------------------------------------------------------------------------------------------|-------------------------------------------------| | 接收成功 | 200 <= `httpcode` < 300，比如：200、201、204 | 响应体为空、无响应体，或响应体不为「FAIL」 | | 接收失败 | | | :::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. 如需区分业务路径，建议使用 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 | ## 通知报文 交易异步通知 退款异步通知 预授权请款通知 预授权撤销通知