Stripe Error insufficient_funds: Insufficient funds

Identify: does your log match?

{
  "error": {
    "charge": "ch_3QJ8xY2eZvKYlo2C0aBcDeFg",
    "code": "card_declined",
    "decline_code": "insufficient_funds",
    "doc_url": "https://stripe.com/docs/error-codes/card-declined",
    "message": "Your card has insufficient funds.",
    "payment_intent": { "id": "pi_3QJ8xY2eZvKYlo2C0hIjKlMn", "status": "requires_payment_method" },
    "type": "card_error"
  }
}

1. High

   Customer balance or credit limit

   The debit balance or remaining credit line is lower than the amount. The issuer returns this specific decline_code.

2. Medium

   Pending authorizations hold funds

   Earlier uncaptured authorizations (yours or other merchants') reduce available balance until they expire or are captured.

3. Medium

   Off-session renewal on a drained card

   Subscription renewals charge without the customer present, so the decline is only seen in invoice.payment_failed.

Fix

try {
  await stripe.paymentIntents.confirm(piId);
} catch (err) {
  res.status(500).send('Payment failed');
}

try {
  await stripe.paymentIntents.confirm(piId);
} catch (err) {
  if (err.type === 'StripeCardError') {
    const msg = err.decline_code === 'insufficient_funds'
      ? 'Your card has insufficient funds. Try another card.'
      : err.message;
    return res.status(402).json({ error: msg, paymentIntent: piId });
  }
  throw err;
}

Verify: reproduce it on purpose

$ stripe payment_intents create --amount=2000 --currency=usd --payment-method=pm_card_visa_chargeDeclinedInsufficientFunds --confirm=true

Prevent

• Show err.message for card_error; it is safe for customers.
• Listen to invoice.payment_failed to email customers.
• Never retry the same card in a tight loop; issuers flag it.