Stripe event: payment_intent.payment_failed, read the decline properly and do not retry blindly

paymentintent.paymentfailed: classify, then act once

The attempt failed. Everything you need is in data.object.last_payment_error: code, decline_code, and message.

What to do on receipt

1. Read last_payment_error.code (e.g. card_declined) and decline_code (e.g. insufficient_funds, expired_card, do_not_honor).

2. Sort into two buckets:

   • Soft, retryable: insufficient_funds, try_again_later, authentication_required. Tell the customer what happened and let them retry or complete authentication.
   • Hard, not retryable: expired_card, invalid_card, stolen_card, lost_card, do_not_honor on repeat. Ask for a different payment method. Do not retry the same card.
3. If code is authentication_required, the customer needs to complete 3D Secure. Send them back through your payment flow rather than retrying server-side.
4. Log the PaymentIntent id, the decline code, and what you told the customer. Return 200.

The trap

Retrying hard declines in a loop. Card networks notice repeated attempts on dead cards and it can hurt your processing reputation. One clean failure message to the customer beats five silent retries. Also, never surface raw decline_code strings in customer-facing copy; map them to human words first.

Checklist

• The PaymentIntent itself stays around after failure; you can confirm it again with a new payment method rather than creating a fresh one, which keeps your records tidy.
• payment_intent.requires_action is a different event for the 3DS case. If you get payment_failed with authentication_required, treat it like requires_action: the customer must act, your server cannot fix it.

Stripe's event reference says paymentintent.paymentfailed occurs when a PaymentIntent has failed the attempt to create a payment method or a payment. Verified live at https://docs.stripe.com/api/events/types. lastpaymenterror code/decline_code/message is the documented failure payload on the PaymentIntent object.