Graceful handling of insufficient funds vs generic declines

A declined payment that locks the checkout form, redirects to a dead-end error page, or crashes the component turns a recoverable event into an abandoned cart. Customers whose first card triggers a fraud hold or hits an insufficient-funds block cannot switch to a second card without restarting the entire flow, which inflates checkout abandonment on an experience already covered by user-experience and error-resilience taxons. For high-ticket orders this converts one soft decline into lost revenue and a support ticket, and repeated decline-and-reload loops can trip Stripe Radar rules that escalate future attempts to hard blocks.

Handle Stripe errors by category instead of treating every failure as terminal. Keep isProcessing scoped so the form re-enables after the promise resolves, show a generic recovery message for card_error (not the raw decline code), and leave inputs mounted so the customer can swap cards and retry without a page reload. Wire this through the component that calls stripe.confirmPayment, for example src/components/checkout/PaymentForm.tsx:

const { error, paymentIntent } = await stripe.confirmPayment({ /* ... */ })
setIsProcessing(false)
if (error?.type === 'card_error') {
  setError('Your card was declined. Try a different card or contact your bank.')
  return
}