How to recover failed subscription payments on Braintree

Braintree’s recurring billing is deliberately lean. It charges subscriptions, retries failed charges on a schedule you choose, and tells you what happened through webhooks. Everything else, including emails to customers, a page to update the card and what your product does while a subscription is past due, is up to you. This guide covers what Braintree does natively, the settings that matter, and the pieces you need to add. It ends with a short section on disputes, since a failed or contested renewal often turns into one.

It sticks to Braintree’s own documentation: Recurring billing advanced settings, the Recurring billing overview, Statuses, Subscription: Retry Charge, Subscription webhooks, Account Updater and Managing disputes via the API (all accessed November 2026).

What happens when a subscription charge fails

When Braintree bills a subscription and the transaction is processor declined or gateway rejected, the subscription moves to Past Due. From there, according to the advanced settings guide:

• Braintree retries automatically if retries are enabled in the Control Panel.
• A successful retry returns the subscription to Active, as long as it has not passed its final billing date.
• Automatic retries do not change the start and end dates of the current billing period.
• Some decline codes, such as an expired or stolen card, are never retried because they suggest the transaction is unlikely ever to succeed.

The subscription object helps you track this: daysPastDue gives the number of days the subscription has been past due, and failureCount counts consecutive failed charge attempts.

Subscription statuses at a glance

Status	Meaning (from Braintree’s statuses reference)
Active	Billing normally
Past Due	A charge failed; retries may be pending
Canceled	No further billing will occur
Expired	The subscription reached its set number of billing cycles

Expired is not a failure state; a subscription that ends for non-payment shows up as Canceled or stays Past Due, depending on your settings.

The retry settings

Retries are configured in the Control Panel under Account Settings, Recurring Billing, Options, not through the API. The settings documented by Braintree:

• Whether to retry failed transactions automatically.
• Days before the first retry, between 1 and 10 days.
• What to do after the retries fail: cancel the subscription, continue retrying, or leave it past due.

The last setting deserves a deliberate choice:

Option	What Braintree does	When it makes sense
Cancel	Ends the subscription	You want a clear end state and will win customers back separately
Continue retrying	Retries once per billing cycle, on the usual billing date	Low-value plans where customers often top up later
Leave past due	Balance keeps accruing each cycle, no further retries	You will collect yourself and need the history

With “leave past due”, the balance grows every cycle without any new attempt, so someone has to contact the customer. With “continue retrying”, there is only one attempt per cycle, so it is not a substitute for prompt retries after the first failure.

Manual retries

You can retry a past due subscription yourself with Subscription: Retry Charge, from the API or the Control Panel. Pass true to submit the transaction for settlement automatically if the retry succeeds. A successful manual retry brings the subscription back to Active; a failed manual retry does not count as one of the automatic attempts. This is what you call right after a customer updates their card, rather than waiting for the next scheduled retry.

Account Updater

Account Updater requests updated details for vaulted cards that have expired or been replaced, which prevents some failures before they happen. Per Braintree’s docs:

• Updates depend on the issuing bank participating; prepaid cards and cards used through Apple Pay or Google Pay are not supported.
• After the initial batch, requests go out on a rolling basis, including when a recurring payment is due within two weeks, and after some declines.
• You can review updates in the Control Panel, in a report, or through a daily webhook.

One important detail: adding a new payment method to a customer’s vault does not move existing subscriptions to it. If a customer gives you a new card, update the subscription’s payment method token, then retry the charge.

Webhooks for subscriptions

Braintree sends these subscription webhook kinds:

Kind	When it fires	What to do
subscription_charged_unsuccessfully	An existing subscription fails to produce a successful charge (not on manual retries, not on the initial charge)	Log the decline, start customer messaging
subscription_went_past_due	The subscription moves from Active to Past Due (once per cycle)	Show an in-app banner, send the first email
subscription_charged_successfully	A charge succeeds	Stop messaging, clear the banner
subscription_went_active	The subscription becomes Active	Restore access
subscription_canceled	The subscription is canceled	Remove access, store the cancel date
subscription_expired	The subscription reached its last cycle	End access as planned

Braintree notes that the cancellation date is not returned in subscription search results, so if you need it, store it when subscription_canceled arrives.

What you need to add yourself

Braintree documents some email notifications for recurring billing; check what they cover for your account. A complete recovery process usually needs more than that:

1. A first email on subscription_went_past_due, sent the same day, with one link to update the card. Do not quote the raw decline reason.
2. A card update page built with Braintree’s client-side integration, so card data goes straight to Braintree and never touches your servers. On success, update the subscription’s payment method and call Retry Charge.
3. Reminders timed around the retries, for example a day after each scheduled retry fails.
4. A final notice before the subscription is canceled, with the date.
5. An in-app banner while the subscription is past due.
6. Separate handling for hard declines. If the card is expired or reported stolen, Braintree will not retry, so the email is the only path to recovery: send it immediately.

Braintree disputes

Disputes are the other way subscription revenue leaks, and Braintree provides a full API for them, described in Managing disputes via the API:

• Webhooks of kind dispute_opened, dispute_won, dispute_lost, dispute_accepted, dispute_expired and others tell you when a case opens or changes status.
• Text evidence (for example a refund or tracking number) is added with Dispute: Add Text Evidence.
• File evidence is uploaded with a Document Upload request, then attached with Dispute: Add File Evidence. Braintree’s docs give a 4 MB limit per file and 5 MB per dispute by default.
• Finalize sends your response and evidence to the cardholder’s bank. Evidence can only be added while the dispute is open.
• Reply-by date: each dispute has one. If you miss it, you lose the right to contest and the dispute becomes expired.
• Accepting a dispute means you do not contest it and the funds go back to the customer.

For a subscription business, the strongest evidence is usually the history: when the customer signed up, what they used, which reminders they received and whether they ever tried to cancel. Gather it before the deadline gets close.

Doing this with NoChurn

Braintree keeps card processing, your merchant account and its own subscription retries; NoChurn works next to them. It connects with your Braintree merchant ID and API keys, follows Braintree webhooks, and adds AI-written recovery emails that you review before they go out, with a hosted page to update the payment method. For disputes, NoChurn gathers evidence automatically (cancel flow answers, emails sent, usage, support conversations) and drafts a reply with AI, which is sent to Braintree only after you review it. It also adds cancel flows with offers and a one-click cancel that is always visible, win-back emails at day 30, 60 and 90, and a churn score from 0 to 100. See NoChurn + Braintree.