Skip to main content
When a subscription renewal fails, PayNext moves it to past_due status. Use this guide to let customers update their payment method and reactivate their subscription.

​
Decision Flowchart

​
Recover Past-Due

For past_due subscriptions, you must collect payment via SDK checkout—there’s no API-only option.
1

Create a client session

Include customer and subscription—do not include plan.id:
cURL
Do not include plan.id for recovery—PayNext uses the existing plan from the subscription.
2

Mount the SDK

Display checkout with the customer’s saved payment method:
Outcomes:
  • Success: Subscription returns to active, billing cycle resets
  • Failure: Customer can switch to a different card and retry instantly

​
Reactivate Cancelled Subscription

For cancelled subscriptions, you can either collect payment via SDK checkout (above) or reactivate directly via API:
cURL
The outcome depends on whether the paid period (current_period_end) is still active:
  • Paid period still active (current_period_end in the future) — the subscription returns to active with no charge, restoring access for the remaining paid period.
  • Paid period has ended (current_period_end in the past or unset) — PayNext attempts an immediate charge on the customer’s saved payment method:
    • Charge succeeds → active with a new billing period.
    • Charge fails → past_due; the subscription enters the standard retry flow and access is not restored.
PayNext emits a single subscription_v2 event reflecting the resulting status (subscription_v2.activated on reactivation, or subscription_v2.past_due if the reactivation charge fails).
API reactivation works for scheduled_for_cancellation and cancelled subscriptions. A past_due subscription cannot be reactivated this way—collect payment via SDK checkout instead.

​
Automatic Recovery From Card Updates

Some past-due subscriptions recover without any action from you or the customer. When a saved card is reissued or its network token becomes usable again, PayNext charges the subscription right away instead of waiting for the next scheduled retry. A success moves the subscription back to active and emits subscription_v2.renewed. Two rules keep this from producing a burst of attempts, and they explain why you won’t always see an immediate charge:
  • After a failed update-triggered attempt, PayNext waits 24 hours before trying again from another update.
  • If a scheduled retry is already due shortly, PayNext lets that one run instead.
The regular retry ladder continues underneath, so nothing is lost if an update-triggered attempt is skipped. A payment declined for insufficient funds recovers the same way, on a different trigger: the card network signals when the funds are likely there, and the attempt runs then instead of on schedule. See Funds-Available Retries.

​
Dead Payment Methods

A payment method can reach a state where no charge can succeed: the card is expired, closed, or invalid and it has no usable network token, or the customer revoked the mandate in Cash App, Pix, PayPal, or Venmo. When that happens, PayNext stops attempting charges rather than sending a run of guaranteed declines. Any attempt that is aborted this way is recorded as INCOMPLETE with decline_code payment_method_disabled and advice_code do_not_try_again. The subscription stays past_due and waits for a recovery—it is not cancelled at that moment. If nothing recovers it within the grace period, PayNext cancels it with cancellation_details.reason set to dead_instrument.
This is the window to reach the customer. A subscription_v2.past_due event with a payment_method_disabled decline means retries will not help—prompt the customer for a new payment method rather than waiting for the ladder.

​
Best Practices

  1. Notify customers promptly when renewals fail—the sooner they update their card, the higher the recovery rate
  2. Use email or in-app messaging to direct customers to your recovery page
  3. Show the amount due clearly in your UI before they reach checkout