---
url: >-
  https://acquirer-api-docs-v4-en.pingpongx.com/en/notes/guide/subscriptionNotify/index.md
description: >-
  This guide explains how to receive and process asynchronous Subscription
  notifications for lifecycle status changes and subscription plan update
  results. Merchants should configure a valid `notifyUrl` and implement
  signature verification, idempotency, and proper ACK handling.
---
## Use Cases

- Subscription notifications are used to receive subscription lifecycle status changes or subscription plan update results.
- Merchants can decide whether to continue providing service based on fields such as `event`, `status`, and `currentPeriod`.
- This callback is initiated by PingPongCheckout and is not a merchant-initiated request.

## Configuration

- Configure the subscription notification URL through `notifyUrl` in Subscription-related APIs.
- `notifyUrl` must be a publicly reachable merchant endpoint that supports HTTP `POST` and JSON payload parsing.
- Do not use local or intranet addresses such as `localhost`, `127.0.0.1`, or `192.168.x.x`.

## ACK Rules

| Reception Result | HTTP Code Rule | Response Body Rule |
|---|---|---|
| Success | `200 <= httpcode < 300` | No fixed response body is required, as long as the body is not the plain text `FAIL` |
| Failure | Non-`2xx`, or `2xx` with a response body exactly equal to `FAIL` | Retries will be triggered |

:::note Tip
The retry schedule is `5s/5s/3m/10m/20m/30m/30m/30m/60m/3h/3h/3h`. Any successful retry stops the remaining retries.
:::

## Handling Recommendations

1. Verify the signature first, then perform idempotency checks, and only then update your local subscription state.
2. Use `event` together with `status` for business decisions instead of relying on a single field.
3. `currentPeriod` is returned at the top level of `bizContent`, not inside `duration`.
4. If payment notifications and subscription notifications are received for the same cycle, handle idempotency separately for each notification type.

## Notification Payload

- [Subscription Notification](/en/notes/notify/subscription/notify/)