What Smart Retries actually does

Stripe Smart Retries is part of Stripe Billing’s revenue recovery toolkit. When a subscription invoice payment fails, Smart Retries uses a machine-learning model trained on Stripe’s network to choose the times at which to reattempt the charge, rather than retrying on a fixed day-3, day-5, day-7 schedule.

You configure two things: how many attempts to make, up to eight, and the window inside which they can happen. Stripe decides the rest. You can also set what happens when the last attempt fails: mark the subscription unpaid, cancel it, or leave the invoice open.

Stripe reports that Smart Retries recovers materially more than fixed schedules, and there is no reason to doubt it. Against the alternative most billing systems shipped with, a model that has seen billions of retry outcomes is a large improvement.

How it decides when to retry

Stripe has described the inputs at a high level: the decline code, the card brand and type, the issuer, the time and day of the original failure, the customer’s payment history, and aggregated patterns from similar cards across Stripe’s network. From these it estimates, for each candidate retry time, the probability that the attempt will approve, and schedules the attempts at the most promising moments within your window.

For insufficient_funds specifically, the model is looking for the pattern of funds returning: paydays, the first of the month, the day after a regular deposit. It is a well-informed guess about the cardholder’s cash cycle.

Where it is blind

8maximum Smart Retries attempts per invoice, each one a prediction
51the network response code behind Stripe's insufficient_funds
15reattempts per card per 30 days before Visa treats them as excessive

Every retry engine that lives at the processor shares the same limitation. It sees attempts and outcomes. It does not see the account.

It cannot observe balance. The only way Smart Retries learns whether funds are back is by trying. A retry that lands a day before payday declines again, consumes one of your attempts, adds a processing fee and adds another decline to the card’s history with the issuer.

It only learns from your traffic. Aggregated patterns help, but the model’s knowledge of a specific cardholder is limited to the payments you have sent through Stripe.

It shares the reattempt budget. Every Smart Retry counts against the network limits on reattempts for that card. Mastercard’s Transaction Processing Excellence programme charges for attempts beyond its thresholds, and Visa caps reattempts at 15 per card per 30 days. Eight scheduled attempts is a lot of budget to spend on predictions.

It does not know issuer timing advice. On Mastercard, an insufficient-funds decline on a recurring transaction may come back with a Merchant Advice Code 24 to 30 telling you to wait one hour to ten days. Stripe surfaces the network advice code on the payment error, but the scheduler does not treat it as a constraint you can configure.

None of this makes Smart Retries bad. It makes it a scheduler, and the ceiling of any scheduler is the quality of its guess.

Handling insufficient_funds in Stripe

When a subscription payment fails, Stripe sends an invoice.payment_failed webhook. The invoice carries the attempt count and the next scheduled attempt time, and the underlying payment error carries the decline code. For insufficient funds it is insufficient_funds, which maps to network response code 51.

A minimal handler does three things:

  1. Reads the decline code and classifies it (soft or hard).
  2. On a soft decline, records the invoice, the card BIN and last four, the amount and the currency, so it can be matched later.
  3. On a hard decline, pauses automatic retries for that subscription and triggers customer outreach or the card account updater.

Stripe’s card account updater already handles expired and replaced cards for you. The work is in the soft-decline branch, which is where the money is.

Adding a network signal

Here is the combination that gets around the blind spot. Keep Smart Retries on. For Mastercard cards, also subscribe to a signal from the network itself.

PaymentRetryAlert is built on the Mastercard Payment Optimization Platform. When a recurring Mastercard payment on one of your registered merchant IDs is declined for insufficient funds, the network monitors that card for up to 30 days. When conditions indicate a retry is more likely to approve, you receive a signed RETRY_NOW webhook carrying the card BIN, last four digits, amount, currency and the network transaction identifier of the original decline.

Your handler matches the alert to the open Stripe invoice and calls the invoice pay endpoint right away. The retry goes through Stripe like any other. Nothing in your routing changes, and you do not touch Smart Retries settings.

A few practical notes:

  • Retry immediately on the alert. Approval likelihood decays with delay. Do not queue the alert behind the next scheduled Smart Retry.
  • Dedupe on the alert’s notification ID. Deliveries are retried if your endpoint does not acknowledge them.
  • Let the two coexist. If a Smart Retry approves first, PaymentRetryAlert detects the successful authorization and cancels monitoring. You are not billed for an alert that never fires.
  • Store what you need to match. The card BIN, last four, amount, currency and the time of the original decline are enough. If your processor exposes the network transaction identifier, store that too.

What to expect

Smart Retries will keep recovering the invoices it recovers today. The network signal adds recoveries on the slice where scheduling guesses wrong: cardholders whose pay cycle does not fit the pattern, accounts topped up on an unusual day, funds that arrive and leave again before the next scheduled attempt.

It also removes attempts. A RETRY_NOW that approves on the first try means the remaining scheduled retries never fire, which saves processing fees and keeps you further from the network reattempt thresholds.

Use the recovery calculator to model the effect on your own decline volume. The model assumes only a portion of unrecovered insufficient-funds declines receive an alert, consistent with Mastercard’s indicative analysis, and applies the standard fee rate with no volume discount, so it is deliberately conservative.