Stripe Error: card_declined — Card Was Declined

try {
  const intent = await stripe.paymentIntents.create({
    amount: 4999,
    currency: 'gbp',
    payment_method: 'pm_card_declined',
    confirm: true,
  });
} catch (err) {
  // err.type === 'StripeCardError'
  // err.code === 'card_declined'
  // err.decline_code === 'insufficient_funds'
  // err.message === 'Your card has insufficient funds.'
}

The card_declined error is what Stripe returns when the customer’s card issuer (the bank that issued the card) refuses to authorise a charge. Stripe itself rarely blocks charges; almost all card_declined errors come from the issuer. Your job as the integrator is to translate that decline into a useful message and decide whether (and when) to let the customer try again.

Why this happens

• Insufficient funds. The most common decline. Customer's account doesn't have enough to cover the charge plus any held authorisations. `decline_code: insufficient_funds`.
• Issuer fraud lock. The issuing bank flagged the transaction as suspicious — often new merchant, unusual amount, or country mismatch. `decline_code: do_not_honor` or `fraudulent`. The customer's card itself is fine; their bank just doesn't trust this charge.
• Lost or stolen card. The card has been reported lost or stolen and is fully blocked. `decline_code: lost_card` or `stolen_card`. Never retry — the card will never work again.
• 3D Secure required but not completed. SCA / 3D Secure was required by the issuer (mandatory in the EEA under PSD2). The PaymentIntent went to `requires_action` but the customer never completed the challenge. Surface the next-action URL or use Stripe.js `confirmCardPayment()`.
• Wrong CVC, expiry, or postal code. Card details don't match what the issuer has on file. `decline_code: incorrect_cvc`, `expired_card`, or `incorrect_zip`. Have the customer re-enter.

How to fix it

Fixes are ordered by likelihood. Start with the first one that matches your context.

const DECLINE_MESSAGES = {
  insufficient_funds: 'Your card was declined for insufficient funds. Try a different card.',
  incorrect_cvc: 'Your security code is incorrect. Please re-enter and try again.',
  expired_card: 'Your card has expired. Please use another card.',
  do_not_honor: "Your bank declined this charge. Contact your bank or try a different card.",
  lost_card: 'This card has been reported lost. Please use a different card.',
  stolen_card: 'This card has been reported stolen. Please use a different card.',
  generic_decline: 'Your card was declined. Try a different card or contact your bank.',
};

function declineMessage(err) {
  return DECLINE_MESSAGES[err.decline_code]
    ?? DECLINE_MESSAGES.generic_decline;
}

const { error, paymentIntent } = await stripe.confirmCardPayment(
  clientSecret,
  { payment_method: paymentMethodId }
);
if (error?.code === 'card_declined' && error.decline_code === 'authentication_required') {
  // SCA challenge interrupted — retry confirmCardPayment to re-trigger the modal.
}

Detection and monitoring in production

Set up a Stripe webhook for `payment_intent.payment_failed` and log `last_payment_error.decline_code` to your error monitoring. Track decline rate over rolling 24-hour and 7-day windows; a sudden spike usually means a fraud rule change or a misconfigured webhook is preventing legitimate charges.