How to handle declined payments with Stripe API

1const DECLINE_CATEGORIES = {
2  // Customer must update their card or contact bank
3  customer_action: [
4    'insufficient_funds', 'expired_card', 'incorrect_cvc',
5    'incorrect_number', 'card_not_supported',
6  ],
7  // Retry may succeed — transient failures
8  retryable: [
9    'processing_error', 'reenter_transaction',
10    'try_again_later',
11  ],
12  // Do not tell user the reason — fraud related
13  fraud: [
14    'fraudulent', 'lost_card', 'stolen_card',
15    'merchant_blacklist', 'pickup_card',
16  ],
17  // Bank-side blocks
18  bank_block: [
19    'do_not_honor', 'generic_decline',
20    'no_action_taken', 'restricted_card',
21    'transaction_not_allowed',
22  ],
23};
24
25function categorizeDecline(declineCode) {
26  for (const [category, codes] of Object.entries(DECLINE_CATEGORIES)) {
27    if (codes.includes(declineCode)) return category;
28  }
29  return 'unknown';
30}

1function getDeclineResponse(declineCode) {
2  const category = categorizeDecline(declineCode);
3
4  switch (category) {
5    case 'customer_action':
6      return {
7        message: getCustomerMessage(declineCode),
8        action: 'update_payment_method',
9        retry: false,
10      };
11    case 'retryable':
12      return {
13        message: 'A temporary issue occurred. Retrying your payment...',
14        action: 'auto_retry',
15        retry: true,
16      };
17    case 'fraud':
18      return {
19        message: 'Your card was declined. Please contact your bank or try a different card.',
20        action: 'contact_bank',
21        retry: false,
22      };
23    case 'bank_block':
24      return {
25        message: 'Your bank declined this transaction. Please contact them or try a different card.',
26        action: 'contact_bank',
27        retry: false,
28      };
29    default:
30      return {
31        message: 'Payment could not be processed. Please try a different payment method.',
32        action: 'try_different_method',
33        retry: false,
34      };
35  }
36}

1async function createPaymentWithRetry(params, maxRetries = 2) {
2  let lastError;
3
4  for (let attempt = 0; attempt <= maxRetries; attempt++) {
5    try {
6      const paymentIntent = await stripe.paymentIntents.create(params);
7      return { success: true, paymentIntent };
8    } catch (err) {
9      lastError = err;
10
11      if (err.code !== 'card_declined') throw err;
12
13      const category = categorizeDecline(err.decline_code);
14      if (category !== 'retryable' || attempt === maxRetries) {
15        return {
16          success: false,
17          ...getDeclineResponse(err.decline_code),
18          decline_code: err.decline_code,
19        };
20      }
21
22      // Wait before retry (exponential backoff)
23      await new Promise(r => setTimeout(r, 1000 * (attempt + 1)));
24    }
25  }
26}

1async function logDecline(customerId, declineCode, amount, currency) {
2  const entry = {
3    timestamp: new Date().toISOString(),
4    customer_id: customerId,
5    decline_code: declineCode,
6    category: categorizeDecline(declineCode),
7    amount,
8    currency,
9  };
10
11  // Store in your database
12  console.log('Decline logged:', JSON.stringify(entry));
13  // await db.collection('payment_declines').insertOne(entry);
14}

1app.post('/api/pay', async (req, res) => {
2  const { amount, currency, paymentMethodId, customerId } = req.body;
3
4  const result = await createPaymentWithRetry({
5    amount,
6    currency: currency || 'usd',
7    customer: customerId,
8    payment_method: paymentMethodId,
9    confirm: true,
10    automatic_payment_methods: { enabled: true, allow_redirects: 'never' },
11  });
12
13  if (!result.success) {
14    await logDecline(customerId, result.decline_code, amount, currency);
15    return res.status(402).json(result);
16  }
17
18  res.json({ success: true, id: result.paymentIntent.id });
19});