Stripe Error: insufficient_funds — Insufficient Funds

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

insufficient_funds is the most common reason a Stripe card_declined error fires. It means the issuing bank checked the customer’s available balance, found it less than the amount you tried to charge, and refused authorisation. Stripe didn’t decline — the bank did. Your job is to surface the right message and let the customer recover gracefully without losing the sale.

The trick with insufficient_funds is that it lies somewhere between fraud declines (where you should never retry) and processing errors (where you should retry quickly). Treat it as a temporary state on a valid card: tell the customer clearly, offer an alternative payment method on the same screen, and if they retry on their own initiative later, let them.

Why this happens

• Customer's available balance is below the charge amount. The most literal cause — the card's account simply doesn't hold enough money. Note this is *available* balance, not posted balance: pending transactions, holds, and authorisations all reduce the spendable total even if the customer's app shows a higher number.
• Daily or weekly spend cap on the card. Many debit cards (especially in the UK and EU) have configurable daily limits that the cardholder may not realise are set. The bank returns `insufficient_funds` even though the account has the money, because the limit is exhausted.
• Pending authorisation hold consuming the balance. An earlier authorisation (hotel deposit, fuel pump pre-auth, subscription pre-charge) is still holding funds. Stripe's charge can't go through until the prior auth is captured or released, which can take 7-30 days for some merchants.
• Currency conversion buffer leaving customer short. When the card is denominated in a different currency to the charge, the issuer reserves a buffer (usually 5-10%) on top of the converted amount to absorb FX moves. A customer with £100 may fail a £95 charge in EUR if the buffer pushes the reservation over £100.
• Prepaid or gift card with no top-up. Prepaid cards return `insufficient_funds` once the balance is spent. Unlike a regular debit card, they can't be auto-topped-up, so retrying is pointless until the customer reloads.

How to fix it

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

function declineMessage(err) {
  if (err.code !== 'card_declined') return 'Payment failed. Please try again.';
  switch (err.decline_code) {
    case 'insufficient_funds':
      return "Your card doesn't have enough available balance for this purchase. Try another card, or add funds and retry.";
    case 'do_not_honor':
      return 'Your bank declined the charge. Contact your bank or use another card.';
    default:
      return 'Your card was declined. Please try a different card.';
  }
}

const elements = stripe.elements({ clientSecret });
const paymentElement = elements.create('payment', {
  layout: 'tabs',
  // Stripe automatically shows alternatives based on country + currency
  paymentMethodOrder: ['card', 'apple_pay', 'google_pay', 'klarna'],
});
paymentElement.mount('#payment-element');

Detection and monitoring in production

Track `insufficient_funds` separately from other `card_declined` reasons in your monitoring. A sudden rise can indicate (a) you've started charging customers with auth holds from your own previous transactions, (b) an FX rate move is pushing customers over the edge, or (c) a checkout pricing change has crossed a typical balance threshold. Alert if `insufficient_funds` exceeds 3% of attempts over a rolling 24-hour window.