How to Handle Failed Payments in Stripe

When a payment fails in Stripe, the invoice.payment_failed event includes a failure code and failure message that explain what went wrong. The most common reasons include:

• Insufficient funds: The card does not have enough balance to cover the charge. This is the most common failure reason and is often temporary.
• Expired card: The card’s expiration date has passed. The customer needs to provide updated card details.
• Card declined (generic): The issuing bank declined the charge without providing a specific reason. This can happen due to spending limits, unusual activity flags, or bank-side fraud rules.
• Fraud detection: Either Stripe Radar or the issuing bank flagged the transaction as potentially fraudulent.
• Authentication required: The card requires 3D Secure or other strong customer authentication (common for European cards under PSD2/SCA regulations).
• Processing error: A temporary issue with the payment network. These usually resolve on retry.

Each failure type requires a different response. Insufficient funds may resolve on their own after a retry, while an expired card always requires customer action.

Stripe’s Smart Retries feature uses machine learning to optimize the timing and likelihood of successful payment retries. Rather than retrying on a fixed schedule, Smart Retries analyzes network-wide signals to determine the best moment to retry.

How Smart Retries works:

• After an initial failure, Stripe schedules up to 4 retry attempts over a configurable window (typically 7-14 days)
• The algorithm considers factors like time of day, day of week, historical success rates for similar cards, and the specific failure code
• Retries are automatically skipped if the failure code indicates a retry will not succeed (e.g., stolen card, account closed)

You can configure the retry window and maximum number of retries in your Stripe Dashboard under Billing settings. After all retries are exhausted, you can configure Stripe to either leave the subscription active (with the invoice open), cancel the subscription, or mark it as unpaid.

Smart Retries recovers a meaningful portion of initially failed payments without any manual intervention, making it an essential first layer of your payment recovery strategy.

While automated retries handle many failures, some situations require direct customer outreach:

Reach out immediately when:

• The failure code is expired_card — this will never resolve without the customer providing new card details
• The customer is on a high-value plan or is a strategic account
• Multiple retries have already failed
• The failure code indicates authentication is required (SCA/3DS)

Wait for automatic retries when:

• The failure code is insufficient_funds — this often resolves within a few days
• The failure code is processing_error — temporary network issues usually clear up
• It is the first failure for this customer

For high-value accounts, consider having your customer success team make a personal call in addition to automated dunning emails. A direct conversation can resolve payment issues faster and demonstrates that you value the relationship.

The invoice.payment_failed webhook is the event you receive from Stripe whenever a payment attempt fails. Handling this event correctly is critical to your dunning process.

Key data in the webhook payload:

• data.object.customer: The Stripe Customer ID — use this to look up the customer in your system
• data.object.subscription: The Subscription ID associated with this invoice
• data.object.attempt_count: How many times Stripe has attempted to collect this payment
• data.object.next_payment_attempt: When Stripe will retry (null if no more retries are scheduled)
• data.object.last_finalization_error or charge failure details: The specific failure code and message

Use the attempt_count field to determine which dunning email to send. On the first attempt, send a gentle notification. On subsequent attempts, increase urgency. When next_payment_attempt is null, the customer is about to lose access.

Here are effective approaches for each stage of payment failure communication:

First failure (friendly notification):

• Subject: “Quick heads up: your payment for [Product] did not go through”
• Tone: casual, helpful. No urgency.
• Content: explain what happened, provide a link to update payment, mention that you will retry automatically

Second/third failure (increasing urgency):

• Subject: “Action needed: update your payment method for [Product]”
• Tone: professional, slightly more urgent
• Content: remind them of the ongoing issue, mention what they will lose access to, provide the payment update link prominently

Final notice (before cancellation):

• Subject: “Your [Product] subscription will be cancelled on [Date]”
• Tone: direct and clear
• Content: state the specific date they will lose access, list what they will lose (data, features, team access), provide one last payment update link

In all cases, make the call-to-action — the payment update link — impossible to miss.

The best approach to failed payments is to prevent them from happening. Implement these proactive strategies:

Card updater services: Stripe participates in card network updater programs (Visa Account Updater, Mastercard Automatic Billing Updater). When a card is reissued with a new number or expiration date, Stripe can automatically update the stored payment method. This happens transparently and prevents a significant portion of “expired card” failures.

Pre-expiry reminders: Send an email 30 days and again 7 days before a customer’s card expires. Include a direct link to your payment settings page. Many customers will proactively update their card when reminded.

In-app alerts: Display a banner or notification inside your application when:

• A card is expiring within 30 days
• A payment has recently failed
• The subscription is in a dunning state

Multiple payment methods: Allow customers to store a backup payment method. If the primary fails, Stripe can automatically attempt the backup.

Combining prevention with a strong dunning sequence creates a comprehensive approach that minimizes involuntary churn.