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, when the payment may be collected again

A card payment may be collected again only when the card scheme’s response to the decline allows a retry. A decline the card scheme doesn’t allow retrying on the saved card, or a failure that stops the payment method, runs no failure behaviour.

Your automation rules also fire on the failure. Every account starts with two, which email the customer when Try again or Double-up rescheduled the payment.

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 as a new payment, 3 days after the failure, or later if the card scheme sets an earliest retry. A retry is retried only once: if it also fails, the amount is collected with a payment added at the end of the plan.

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.

Plans suspended by a failed payment method

Some failure codes mean the payment method can’t be used again. When one occurs, ElasticPay switches the customer to another saved payment method of the same kind if they have one. Otherwise it suspends every plan that would charge the failed method (those set up with it, and those using it as the customer’s default, closing ones included) and emails the customer a recovery link (in sandbox, only if the customer’s address belongs to someone in your team: see Emails in test mode). The customer’s status doesn’t change, and their plans on other payment methods carry on.

While suspended, a plan takes no payments. Payments due meanwhile still count: the plan shows them as behind, a plan with a total collects them at the end, and a plan that runs until further notice doesn’t.

Plans suspended for your review

Some bank debit codes are about the customer rather than the account: 2 (DDR cancelled at bank), 4 (Customer deceased), 27 (Invalid transaction), 50 (Customer refund), 91 and 991 (Credit card chargeback), 92 and 992 (Direct debit claim) and 93 (Recall). When one occurs, the bank account can’t be used again, and every collecting plan of the customer is suspended for your review, whatever payment method it uses. No recovery link is emailed to the customer, and nothing resumes the plans but you: click Resume on each one when you’ve decided to collect again. The customer page shows a banner while any plan is suspended for review.

Payment method recovery

Any new payment method saved for the customer resumes the plans a failed payment method suspended, from that day: the recovery link, Customer is with me, Collect Payment Details, a card the customer saves while paying, or the API. The new payment method becomes the customer’s default, and plans set up with the failed method switch to it. A plan you suspended, or one suspended for your review, stays suspended.

While a plan waits for a new payment method, its page and the customer’s show a Recovery in Progress card:

1. Customer is with me opens the setup form for the customer to enter a new card or bank account.
2. Resend customer setup email sends the recovery link again, at most once every 3 hours.

Setup links stay valid for 30 days and can be used once. Once the last link has expired, the card says The last setup link has expired. and Send a new setup email sends the customer a new one.

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