Stripe Webhook Failed Payment Handling: Complete Guide (And Automation)

// The invoice.payment_failed event payload
{
  "id": "evt_xxx",
  "type": "invoice.payment_failed",
  "data": {
    "object": {
      "id": "in_xxx",
      "customer": "cus_xxx",
      "subscription": "sub_xxx",
      "status": "open",
      "attempt_count": 1,
      "next_payment_attempt": 1717200000,  // next retry timestamp
      "last_payment_error": {
        "code": "card_declined",
        "decline_code": "insufficient_funds",
        "message": "Your card has insufficient funds."
      }
    }
  }
}

const express = require('express');
const stripe = require('stripe')(process.env.STRIPE_SECRET_KEY);

const app = express();

// IMPORTANT: Use raw body for signature verification
app.post('/webhooks/stripe',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const sig = req.headers['stripe-signature'];
    let event;

    // Step 1: Verify the webhook signature
    try {
      event = stripe.webhooks.constructEvent(
        req.body,
        sig,
        process.env.STRIPE_WEBHOOK_SECRET
      );
    } catch (err) {
      console.error('Webhook signature verification failed:', err.message);
      return res.status(400).send('Webhook Error');
    }

    // Step 2: Idempotency. skip if already processed
    const alreadyProcessed = await checkIfProcessed(event.id);
    if (alreadyProcessed) {
      return res.json({ received: true, skipped: true });
    }

    // Step 3: Handle the event
    try {
      switch (event.type) {
        case 'invoice.payment_failed':
          await handlePaymentFailed(event.data.object);
          break;

        case 'invoice.payment_action_required':
          await handleActionRequired(event.data.object);
          break;

        case 'customer.subscription.updated':
          await handleSubscriptionUpdated(event.data.object);
          break;
      }

      // Mark event as processed for idempotency
      await markAsProcessed(event.id);
    } catch (err) {
      console.error('Webhook handler error:', err);
      return res.status(500).send('Handler Error');
    }

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

const SOFT_DECLINES = [
  'insufficient_funds',
  'processing_error',
  'try_again_later',
  'reenter_transaction',
  'issuer_not_available',
];

const HARD_DECLINES = [
  'stolen_card',
  'lost_card',
  'card_not_supported',
  'expired_card',
  'fraudulent',
  'do_not_honor',
  'pickup_card',
];

async function handlePaymentFailed(invoice) {
  const decline = invoice.last_payment_error?.decline_code;
  const isLastAttempt = invoice.next_payment_attempt === null;
  const customer = invoice.customer;

  if (SOFT_DECLINES.includes(decline)) {
    // Soft decline: Stripe will retry automatically.
    // Send a gentle heads-up email on first failure.
    if (invoice.attempt_count === 1) {
      await sendDunningEmail(customer, {
        template: 'soft_decline_notice',
        declineReason: decline,
      });
    }
  } else if (HARD_DECLINES.includes(decline)) {
    // Hard decline: retries won't help.
    // Send immediate card update request.
    const portal = await stripe.billingPortal.sessions.create({
      customer: customer,
      return_url: 'https://yourapp.com/account',
    });

    await sendDunningEmail(customer, {
      template: 'card_update_required',
      cardUpdateUrl: portal.url,
      declineReason: decline,
    });
  }

  // Final attempt failed. escalate urgently
  if (isLastAttempt) {
    await sendDunningEmail(customer, {
      template: 'final_warning',
      cardUpdateUrl: await createPortalUrl(customer),
    });

    await notifyTeam({
      type: 'payment_final_failure',
      customer: customer,
      invoice: invoice.id,
      decline_code: decline,
    });
  }
}

async function handleActionRequired(invoice) {
  // Customer needs to authenticate with their bank (3D Secure)
  // Send them the hosted invoice URL to complete authentication
  await sendDunningEmail(invoice.customer, {
    template: 'authentication_required',
    paymentUrl: invoice.hosted_invoice_url,
  });
}

async function handleSubscriptionUpdated(subscription) {
  if (subscription.status === 'past_due') {
    // Subscription moved to past_due. update your app's access logic
    await updateUserAccess(subscription.customer, {
      status: 'past_due',
      gracePeriodEnds: Date.now() + 7 * 24 * 60 * 60 * 1000,
    });
  }

  if (subscription.status === 'unpaid') {
    // All retries exhausted, subscription marked unpaid
    await updateUserAccess(subscription.customer, {
      status: 'suspended',
    });
  }
}