Skip to content
ElasticPay

Handling Failures

What happens on failure

When a scheduled payment fails:

  1. The payment_intent.failed webhook event fires
  2. The failure code is recorded on the payment intent
  3. The plan’s failure_count is incremented
  4. The configured failure behaviour is applied

Failure behaviours

NEW_AT_END — Add to end

The missed payment is added as an extra payment at the end of the plan schedule. The total number of payments increases by one; the plan end date extends.

Best for: Fixed-total plans where full collection is required.

TRY_AGAIN — Retry

The failed payment is retried after a delay (default: 3 days). If the retry also fails, the behaviour is applied again.

Best for: Most plans — gives the customer time to resolve a temporary card issue.

DOUBLE_UP — Double up

The next scheduled payment is doubled to include the failed amount. No extra payment is added to the end of the schedule.

Best for: Plans where extending the term is not desirable.

DO_NOTHING — Do nothing

The failure is recorded, the total amount is reduced by the failed amount, and no catchup occurs. The plan continues on its normal schedule.

Best for: Plans where partial collection is acceptable.

Customer on hold

After a configurable number of consecutive failures, the customer is placed on hold status. This pauses payment processing across all of the customer’s plans until a new payment method is provided.

Payment method recovery

To recover a customer from hold:

  1. Open the customer or plan detail page
  2. Click Open Recovery Setup Intent
  3. A recovery email is sent to the customer with a link to update their card
  4. The customer enters a new card via the hosted widget
  5. On success, the new card is saved, hold status is cleared, and suspended plans resume automatically

Resending the recovery email

If the customer did not receive the email or the link expired, click Resend Recovery Email on the customer or plan detail page.

Manual override

For one-off situations where automated recovery is not appropriate:

  1. Suspend the plan
  2. Process the payment manually (via the virtual terminal or a direct payment intent)
  3. Apply a Balance Adjustment if needed to correct the collected total
  4. Resume the plan