---
url: >-
  https://acquirer-api-docs-v4-en.pingpongx.com/notes/zh/guide/subscriptionNotify/index.md
description: >-
  订阅通知接入说明介绍了如何接收和处理 Subscription
  订阅状态变化与订阅计划更新结果的异步通知。开发者需配置有效的`notifyUrl`，并按照约定完成验签、幂等处理与 ACK 响应。
---
## 适用场景

- 订阅通知用于接收订阅计划状态变化或计划更新结果。
- 商户可基于 `event`、`status`、`currentPeriod` 等字段，决定是否继续向用户提供服务。
- 该通知由 PingPongCheckout 主动发起，不是商户主动调用的接口。

## 配置方式

- 在 Subscription 相关接口中配置订阅通知地址 `notifyUrl`。
- `notifyUrl` 必须是商户侧真实可访问的公网地址，且需要支持 HTTP `POST` 接收 JSON 报文。
- 不要使用 `localhost`、`127.0.0.1`、`192.168.x.x` 等本地或内网地址。

## ACK 规则

| 接收结果 | HTTP Code 约定 | 应答报文格式约定 |
|---|---|---|
| 接收成功 | `200 <= httpcode < 300` | 无需返回固定报文，只要响应体不为纯文本 `FAIL` |
| 接收失败 | 非 `2xx`，或 `2xx` 但响应体精确等于 `FAIL` | 会触发重试 |

:::note 提示
重试间隔为 `5s/5s/3m/10m/20m/30m/30m/30m/60m/3h/3h/3h`。任意一次重试成功后，将停止后续重试。
:::

## 处理建议

1. 先验签，再做幂等，最后再更新本地订阅状态。
2. 业务判断时应结合 `event` 和 `status` 一起处理，不能只看单一字段。
3. `currentPeriod` 位于 `bizContent` 顶层，不在 `duration` 内。
4. 若同一订阅周期同时收到支付通知和订阅通知，应分别按各自通知类型做幂等处理。

## 通知报文

- [订阅通知](/notes/zh/notify/subscription/notify/)