Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.xpaycheckout.com/llms.txt

Use this file to discover all available pages before exploring further.

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, 4-hour cooldown for manual retries.

​
Manual Retry Capability

Merchants have full control over subscription retry attempts through the xPay dashboard:
Manual retries are subject to a 4-hour cooldown period to prevent excessive payment attempts and respect payment processor limits.

​
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