Failed payments and retries

XPay can retry a recurring invoice payment when the first attempt fails. Merchants must process each payment outcome and keep customer access aligned with the subscription state.

Default behavior#

The default subscription configuration allows up to three retries after the initial payment attempt. For standard billing intervals, XPay retries the payment one day after the previous failed attempt when custom retry timing isn't supplied.

Each subscription_payment and invoice_payment webhook includes the latest payment result. Payment webhooks can also include attempts_left and the current retry count.

Configure retry timing#

Supply payment_retries_timing when creating or updating a subscription:

{
  "payment_retries_timing": [
    {
      "date": 1,
      "hour": 0,
      "minute": 0
    },
    {
      "date": 2,
      "hour": 0,
      "minute": 0
    },
    {
      "date": 3,
      "hour": 0,
      "minute": 0
    }
  ]
}

• date: Number of days to add.
• hour: Number of hours to add.
• minute: Number of minutes to add.

The number of entries must match the subscription's allowed retry count.

Custom retry-timing example#

For the three entries above, the resulting sequence is:

State changes after failure#

When a recurring payment fails:

• The invoice remains unpaid.
• The invoice ID is recorded in the subscription's unpaid_invoices.
• The subscription changes to inactive.
• XPay retries while attempts remain.
• Normal future collection stops after the allowed attempts are exhausted.

A declined payment is a payment outcome, not an HTTP request failure. The API request can complete successfully even when the payment is unsuccessful.

Recover the subscription#

The merchant can recover an inactive subscription by:

1. Paying the invoice through POST /public/v1/invoice/{invoice_id}/pay.
2. Marking the invoice paid when payment was collected separately.
3. Sending the customer an invoice payment link.
4. Collecting a new payment token with the XPay Element and updating the subscription's payment.token before retrying payment.

After the invoice is paid successfully, the invoice becomes paid and the subscription returns to paid.

Recommended webhook handling#

For subscription_payment and invoice_payment:

1. Match the event to the subscription and invoice IDs.
2. Store the latest invoice and subscription states.
3. Read attempts_left before notifying the customer that retries are exhausted.
4. Grant or restore access only after the payment result is successful.
5. Avoid creating a replacement subscription for an invoice payment failure.