---
url: 'https://acquirer-api-docs-v4-en.pingpongx.com/notes/zh/notify/index.md'
description: >-
  异步通知接口用于接收交易相关事件的回调信息。适用于需要实时了解交易状态变化的场景，如交易成功、退款等。开发者需配置可公网访问的`notificationUrl`地址，并确保该服务支持接收和解析HTTP
  POST请求中的JSON数据。关键特性包括自动重试机制以应对网络不稳定情况，以及明确的HTTP响应
---
## 异步通知概述

- 首先，商户侧配置异步回调通知`notificationUrl`地址。
- 每当，交易相关事件发生时（如交易成功），PingPongCheckOut 通知服务将会创建一个JSON对象，其中包含事件相关的数据等信息。
- 然后，PingPongCheckOut 通知服务通过 HTTP POST 请求将JSON对象发送到开发者配置的回调通知`notificationUrl`中。
商户侧在收到回调通知后，可根据异步通知报文做下一步的业务处理。

其流程描述如下：

```mermaid
%%{init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#E3F2FD',
    'primaryTextColor': '#0D47A1',
    'primaryBorderColor': '#1976D2',
    'lineColor': '#1565C0',
    'secondaryColor': '#BBDEFB',
    'tertiaryColor': '#90CAF9',
    'background': '#F8FBFF',
    'mainBkg': '#E3F2FD',
    'secondBkg': '#BBDEFB',
    'tertiaryBkg': '#90CAF9',
    'actorBkg': '#2196F3',
    'actorBorder': '#1976D2',
    'actorTextColor': '#FFFFFF',
    'actorLineColor': '#1565C0',
    'signalColor': '#0D47A1',
    'signalTextColor': '#0D47A1',
    'noteBkgColor': '#E1F5FE',
    'noteTextColor': '#01579B',
    'noteBorderColor': '#0288D1',
    'loopTextColor': '#0D47A1',
    'activationBkgColor': '#B3E5FC',
    'activationBorderColor': '#0277BD'
  }
}}%%

sequenceDiagram
    participant Developer as 👨‍💻 开发者
    participant Merchant as 🏪 商户业务系统
    participant PP as 🔄 PingPongCheckOut
    participant Notify as 📡 PingPongCheckOut Notify Server

    Developer->>Merchant: 开发者配置 notificationUrl
    Merchant->>PP: request
    Note over PP: 触发事件（如交易成功）
    PP->>Notify: 触发并推送回调通知
    Notify-->>Merchant: request
    Merchant->>Merchant: 开发者业务处理
    Merchant->>Notify: 返回 HTTP 状态码 200～299
```

## 接收异步通知

### 准备一个支持 HTTP POST 的web服务
PingPongCheckOut 通知服务将以 HTTP POST 方式推送 JSON 格式的数据，因此开发者所提供的 Web 服务需要能够接收并解析来自HTTP POST 请求的 JSON 数据并能够返回相应 HTTP 状态码。

### 设置回调通知地址
开发者可以通过各接口入参中的 `notificationUrl` 参数配置回调通知Url地址。
> 异步通知受双方网络连接状态影响，请确保通知地址公网可访问

### 接收并响应
 对于商户交易通知响应，遵循以下约定：

| 接收结果 | HTTP Code 约定                                                                                           | 应答报文格式约定                                        |
|------|--------------------------------------------------------------------------------------------------------|-------------------------------------------------|
| 接收成功 | 200 <= `httpcode` < 300，比如：200、201、204                                                                 | 无需返回应答报文                                        |
 | 接收失败 | <ul><li> `httpcode` > 300 或 `httpcode` < 200</li><li> 200 <= `httpcode` < 300，比如：200、201、204</li></ul> | <ul><li> 报文体任意</li><li> 需返回应答报文「FAIL」</li></ul> |

> 重试机制：接收失败的情况下会触发重试机制，PingPongCheckout 会在随后的一段时间内，以递增的时间间隔重发，间隔为 `5s/5s/3m/10m/20m/30m/30m/30m/60m/3h/3h/3h`（若中间重试通知成功，则中断不再继续重试）。

::: danger
1. 商户不能仅仅依赖于异步通知，如果⻓时间未收到交易结果，商户应该主动向 PingPongCheckout 发起交易查询，查询对应的交易结果;
2. 请不要在`notificationUrl`后面携带query类型的参数，以免丢失，如果一定要携带，请使用pathInfo的URL模式;
3. 异步通知代码处理逻辑不能做登录态校验。
:::

## PingPongCheckout回调通知服务器信息
如果商户侧需要防火墙配置后才允许 PingPongCheckout 消息通知服务推送数据，请根据下方信息进行防火墙设置，将IP加入到白名单：

| 生产环境          | 沙箱环境          |
|:--------------|:--------------|
| 3.125.243.2   | 52.76.198.228 |
| 3.126.196.22  ||
| 18.195.199.34 ||
| 188.239.12.25 ||

## 通知报文

<a href="/notes/zh/notify/subscription/notify/#订阅通知" target="_blank">订阅通知</a>
<br/>
<a href="/notes/zh/notify/payment/notify/#交易异步通知" target="_blank">交易异步通知</a>
<br/>
<a href="/notes/zh/notify/refundNotify/#退款异步通知" target="_blank">退款异步通知</a>
<br/>
<a href="/notes/zh/notify/status/captureNotify/#预授权请款通知" target="_blank">预授权请款通知</a>
<br/>
<a href="/notes/zh/notify/status/voidNotify/#预授权撤销通知" target="_blank">预授权撤销通知</a>