Stripe Card Declined Codes Explained: Every Code and What to Do

const paymentIntent = await stripe.paymentIntents.retrieve('pi_xxx');

if (paymentIntent.status === 'requires_payment_method') {
  const error = paymentIntent.last_payment_error;

  console.log(error.code);          // "card_declined"
  console.log(error.decline_code);   // "insufficient_funds"
  console.log(error.message);        // "Your card has insufficient funds."

  // For invoices (subscription payments):
  const invoice = await stripe.invoices.retrieve('in_xxx');
  console.log(invoice.last_payment_error?.decline_code);
}

const softDeclines = {
  'insufficient_funds': {
    meaning: 'Customer does not have enough balance right now',
    action: 'Retry in 3-5 days (after payday). Send dunning email.',
    frequency: '30-40% of all SaaS failures',
  },
  'processing_error': {
    meaning: 'Temporary issue at the bank or network level',
    action: 'Retry in 24 hours. Usually resolves itself.',
    frequency: '5-8%',
  },
  'authentication_required': {
    meaning: '3D Secure / SCA challenge needed',
    action: 'Send customer a payment link that triggers 3DS flow.',
    frequency: '10-15% (higher in EU due to SCA mandate)',
  },
  'approve_with_id': {
    meaning: 'Bank wants to verify identity before approving',
    action: 'Retry once. If fails again, ask customer to call bank.',
    frequency: '2-3%',
  },
  'try_again_later': {
    meaning: 'Issuer system is temporarily unavailable',
    action: 'Retry in 2-4 hours. Almost always succeeds on retry.',
    frequency: '1-2%',
  },
  'reenter_transaction': {
    meaning: 'Bank is asking for the charge to be resubmitted',
    action: 'Retry immediately. Often a network glitch.',
    frequency: '<1%',
  },
};

const hardDeclines = {
  'expired_card': {
    meaning: 'Card has passed its expiration date',
    action: 'Send card update email immediately. Do NOT retry.',
    frequency: '15-20% of all SaaS failures',
  },
  'generic_decline': {
    meaning: 'Bank declined with no specific reason given',
    action: 'Retry once in 24h. If fails again, send update email.',
    frequency: '15-20% (catch-all code)',
    note: 'Can be soft or hard. Retry once to differentiate.',
  },
  'card_not_supported': {
    meaning: 'Card does not support this type of purchase',
    action: 'Customer needs a different card entirely.',
    frequency: '3-5%',
  },
  'do_not_honor': {
    meaning: 'Bank refuses without explanation (usually fraud flag)',
    action: 'Send card update email. Customer may need to call bank.',
    frequency: '5-8%',
  },
  'stolen_card': {
    meaning: 'Card reported stolen by the cardholder',
    action: 'Do NOT retry. Do NOT contact about this card.',
    frequency: '<1%',
  },
  'lost_card': {
    meaning: 'Card reported lost by the cardholder',
    action: 'Do NOT retry. Send card update email for a new card.',
    frequency: '<1%',
  },
  'pickup_card': {
    meaning: 'Bank wants the card confiscated (fraud suspected)',
    action: 'Do NOT retry. Send card update email for a new card.',
    frequency: '<1%',
  },
  'incorrect_number': {
    meaning: 'The card number is wrong',
    action: 'Customer entered the card number incorrectly.',
    frequency: '<1% (rare for stored cards)',
  },
  'incorrect_cvc': {
    meaning: 'The CVC/CVV does not match',
    action: 'Customer needs to re-enter their card details.',
    frequency: '<1% (rare for subscriptions)',
  },
  'invalid_account': {
    meaning: 'Card account is closed or invalid',
    action: 'Customer needs a completely different card.',
    frequency: '1-2%',
  },
  'card_velocity_exceeded': {
    meaning: 'Too many transactions in a short period',
    action: 'Wait 24h and retry once. If fails, send update email.',
    frequency: '<1%',
  },
  'withdrawal_count_limit_exceeded': {
    meaning: 'Customer hit their daily transaction limit',
    action: 'Wait 24h and retry once.',
    frequency: '<1%',
  },
  'currency_not_supported': {
    meaning: 'Card cannot be charged in this currency',
    action: 'Customer needs a card that supports your billing currency.',
    frequency: '<1%',
  },
};

// Soft declines that are worth retrying
const SOFT_DECLINES = new Set([
  'insufficient_funds', 'processing_error',
  'try_again_later', 'reenter_transaction',
  'approve_with_id',
]);

// Hard declines where retry is pointless
const HARD_DECLINES = new Set([
  'expired_card', 'stolen_card', 'lost_card',
  'card_not_supported', 'invalid_account',
  'pickup_card', 'incorrect_number',
]);

// Never contact about these
const FRAUD_DECLINES = new Set([
  'stolen_card', 'pickup_card',
]);

app.post('/webhooks/stripe', async (req, res) => {
  const event = stripe.webhooks.constructEvent(req.body, sig, secret);

  if (event.type === 'invoice.payment_failed') {
    const invoice = event.data.object;
    const code = invoice.last_payment_error?.decline_code;

    if (FRAUD_DECLINES.has(code)) {
      // Don't retry, don't email about this card
      await flagForReview(invoice);

    } else if (SOFT_DECLINES.has(code)) {
      // Stripe Smart Retries will handle the retry timing
      // Send a gentle dunning email with card update option
      await sendDunningEmail(invoice, { tone: 'informational' });

    } else if (HARD_DECLINES.has(code)) {
      // Don't retry. go straight to card update request
      await sendCardUpdateEmail(invoice, { urgency: 'high' });

    } else {
      // generic_decline, do_not_honor, unknown
      // Treat as soft for retry, but also send update email
      await sendDunningEmail(invoice, { tone: 'standard' });
    }
  }

  res.json({ received: true });
});

// SaveMRR does all of the above automatically . 
// decline-aware triage, smart email sequences,
// and one-click card update links.