Skip to main content
xPay’s Subscription Retry Mechanism is a robust system designed to handle failed subscription payments intelligently. It ensures that temporary payment issues don’t immediately terminate subscriptions while providing clear escalation paths when payments consistently fail.

​
Retry Configuration

The retry mechanism operates with predefined rules to ensure optimal payment recovery:
  • Automatic Retry Schedule: 4, 8, 12, and 24 hours after failure.
  • Retry Limits: 4 automatic attempts max, with a 4-hour cooldown between manual retries.

​
Manual Retry Capability

Merchants can retry failed subscription payments through the xPay dashboard or the Manual Retry API. Manual retries are only allowed when the subscription is in the UNPAID status.
Manual retries are subject to a 4-hour cooldown. If a retry is attempted too soon, the API returns the earliest time at which another retry can be attempted.

​
Notification System

The system sends various notifications during the retry process:
  Customer Notifications
  • First Payment Failure - Immediate notification to customer
  • Final Failure - Customer notification with payment update link
  Merchant Notifications
  • Failed Subscription Transactions - Notifications for failed subscription transactions

​
State Management

The subscription retry mechanism manages subscription states throughout the retry process:
  • ACTIVE/TRIALING - Normal subscription states that can be charged
  • UNPAID - Final state after all retries are exhausted
  • Next Payment Date - Dynamically updated for retry scheduling

​
Webhook Events

The retry mechanism triggers specific webhook events to keep your system updated:
  • subscription.cycle_charged - Successful retry payment
  • subscription.unpaid - All retries exhausted
  • subscription.ended - Subscription terminated after retry failure

  View Webhook Events

  Webhook Setup