Renewal & Auto-Recovery
This page covers renewal, failed-charge retry and compensation queries after a subscription becomes active. For the main integration flow, read the Subscription Integration Guide first.
Handling Renewals and Recovery Charges
- At the end of each billing period, PingPong automatically initiates the renewal charge according to the subscription plan.
- If a renewal charge fails and
autoRecovery.enabled=true, the subscription entersPAST_DUEand retries according to the automatic retry policy. - If
autoRecovery.enabled=false, there is no automatic retry after a failed charge and the subscription transitions toCANCELLED. - Retry counts and intervals use the platform default policy (see Automatic retry mechanism below); merchant-defined retry policies are not supported by the current baseline capability. Non-retryable outcomes such as hard declines and risk-control rejections do not enter automatic retry.
- When automatic retries are exhausted, the subscription transitions to
CANCELLEDwithcancelReason=payment_retry_exhaustedin the subscription notification. - Based on
status,currentPeriodand your own service policy, decide whether to keep providing service, allow a make-up charge window, or downgrade.
Automatic Retry Mechanism and the PAST_DUE Recovery Action
The default automatic retry policy uses an interval and attempt count based on the subscription period:
| Period unit | Retry interval | Default max attempts |
|---|---|---|
DAY | 2 hours | 1 |
WEEK | 24 hours | 7 |
MONTH | 48 hours | 7 |
YEAR | 72 hours | 7 |
PAST_DUE recovery checkout (action)
When a renewal charge fails and the subscription enters PAST_DUE, the subscription notification (SUBSCRIPTION_PAST_DUE) carries an action object for guiding the user back to the PingPong checkout to retry the current period payment:
"action": {
"redirectUrl": "https://sandbox-safepay.pingpongx.com?token=...",
"actionExpiredAt": 1792200000
}redirectUrl: the recovery checkout URL. Merchants can redirect the user to it, or deliver it via in-app messages or email so the user can retry the current bill.actionExpiredAt: the URL expiry (second-level timestamp). Validity = min(72 hours, remaining automatic retry window) from generation: effectively about 2 hours forDAYsubscriptions and up to 72 hours forWEEK/MONTH/YEAR.- Once the automatic retry window is exhausted,
actionis no longer generated (the notification does not carry it), earlier links stop working, and the subscription follows the retries-exhausted flow (cancelReason=payment_retry_exhausted).
Merchants are advised to deliver action.redirectUrl to the user promptly after receiving SUBSCRIPTION_PAST_DUE — for DAY subscriptions the link is valid for only about 2 hours.
It is recommended to evaluate renewal scenarios in two steps:
| Look at first | Fields to watch | Typical meaning | Recommended action |
|---|---|---|---|
| Subscription level | status=ACTIVE | The subscription is in normal fulfillment | Keep providing service |
| Subscription level | status=PAST_DUE | This period's charge failed; in recovery or grace period | Keep service / downgrade / remind the customer to top up, per your rules |
| Subscription level | status=CANCELLED + cancelReason=payment_retry_exhausted | Automatic retries exhausted; subscription terminated | Stop renewal and service |
| Payment level | Current period payment status=SUCCESS | This period was actually charged | Book and reconcile normally |
| Payment level | Current period payment failed or has no success record | This period's money has not been collected | Enter dunning, grace or suspension flow based on the subscription status |
Define at least one of the following renewal-failure policies:
- Grace period with continued service: keep serving during
PAST_DUEand remind the customer to top up. - Grace period with downgraded service: keep the account but close premium entitlements.
- Immediate suspension: stop the subscription service right after a renewal failure.
When a renewal fails and enters the grace period, the subscription notification pushes notifyType=SUBSCRIPTION_PAST_DUE (status=PAST_DUE); after a successful recovery charge it pushes SUBSCRIPTION_RECOVERED. For full notification payload examples, see Subscription Status & Notifications · Notification payload structure.
When you receive SUBSCRIPTION_PAST_DUE, it is recommended to first mark the subscription as "pending recovery" or "in grace period", then decide whether to keep serving based on the payment result.
Querying the Subscription Plan and Payment Records
When notifications are delayed, lost, or you need compensation reconciliation, keep a dual perspective — subscription level and payment level — when querying:
| Query API | Best at answering |
|---|---|
| Query Subscription | Whether the subscription is ACTIVE, still in trial, cancelled, and which period it is in |
| Query Subscription Payments | How much was charged in each period, whether the charge succeeded, which payment method was used, and whether there were refunds |
