Payment integration is one of the few areas of a codebase where "it worked in my manual test" genuinely doesn't mean it works — the actual correctness of a Stripe integration is proven by its webhook handling, not its checkout button.
Stripe is a payments platform providing APIs for one-time payments, subscriptions, and complex billing scenarios, along with hosted Checkout pages that handle PCI compliance for you. The critical architectural detail most integrations get wrong at first: the checkout flow only starts a payment — webhooks, not the client-side redirect, are the actual source of truth for whether a payment succeeded.
Why Stripe Integration Matters (and When to Skip It)
Building payment processing from scratch means handling PCI compliance, card network integrations, fraud detection, and international payment methods — Stripe abstracts all of it behind a well-documented API and hosted Checkout, letting most teams accept payments in days rather than months, without ever handling raw card data.
Skip a full Stripe integration if you're validating a business idea pre-payment or your volume/complexity genuinely doesn't need programmatic billing yet — a simple payment link or an entirely manual invoicing process might be sufficient before investing in a full integration.
Getting Started with Stripe
Creating a Checkout session for a one-time payment:
import Stripe from "stripe";
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
const session = await stripe.checkout.sessions.create({
mode: "payment",
line_items: [{ price: "price_abc123", quantity: 1 }],
success_url: "https://yourapp.com/success?session_id={CHECKOUT_SESSION_ID}",
cancel_url: "https://yourapp.com/cancel",
});
// redirect the user to session.url
Handling the webhook that confirms payment:
app.post("/webhooks/stripe", express.raw({ type: "application/json" }), async (req, res) => {
const sig = req.headers["stripe-signature"] as string;
let event: Stripe.Event;
try {
event = stripe.webhooks.constructEvent(req.body, sig, process.env.STRIPE_WEBHOOK_SECRET!);
} catch (err) {
return res.status(400).send(`Webhook signature verification failed`);
}
if (event.type === "checkout.session.completed") {
const session = event.data.object as Stripe.Checkout.Session;
await grantAccessForOrder(session.client_reference_id!);
}
res.json({ received: true });
});
Core Stripe Concepts Every Developer Should Know
Webhooks are the actual source of truth, not the success redirect. A user can close the tab after payment but before the redirect completes, or the redirect can fail for unrelated reasons — the webhook fires reliably regardless of what happens client-side, which is why granting access/fulfilling an order must happen in the webhook handler, not the redirect page.
Always verify webhook signatures. Without verifying stripe-signature against your webhook secret, anyone who discovers your webhook URL could send fake "payment succeeded" events. This is a real, common integration mistake with direct financial impact if missed.
Idempotency matters because webhooks can be delivered more than once. Stripe's own documentation guarantees at-least-once delivery, meaning your handler needs to tolerate receiving the same event twice without double-fulfilling an order:
const alreadyProcessed = await db.processedEvents.exists(event.id);
if (alreadyProcessed) return res.json({ received: true });
await db.processedEvents.create({ id: event.id });
// ...proceed with fulfillment
Subscriptions involve a whole additional set of webhook events (customer.subscription.updated, invoice.payment_failed) beyond the initial checkout — handling subscription lifecycle correctly means listening for and responding to these events, not just the initial purchase.
Common Stripe Mistakes and How to Fix Them
Mistake 1: granting access or fulfilling an order based on the client-side success redirect alone. This is exploitable — a user can navigate directly to the success URL without ever paying. Fix: always gate fulfillment on the verified webhook event, treating the redirect as UX only.
Mistake 2: not verifying webhook signatures, or verifying them incorrectly (e.g., after the body has already been parsed as JSON, which breaks signature verification since Stripe needs the raw body). Fix: use the raw request body middleware specifically for the webhook route, and always verify via stripe.webhooks.constructEvent.
Mistake 3: not handling webhook idempotency, causing duplicate fulfillment (double-granting credits, sending duplicate confirmation emails) when Stripe redelivers an event. Fix: track processed event IDs and skip already-handled events.
When Should You Use Stripe Checkout Instead of Custom Payment Elements?
Use Stripe Checkout (the hosted page) for the fastest path to PCI-compliant payments with minimal custom UI work — it handles the entire payment form, including 3D Secure and various payment methods, without you building any of it. Use Stripe Elements (embeddable payment form components) when you need the payment form to feel fully native within your own UI rather than a redirect to a Stripe-hosted page, accepting more implementation responsibility in exchange for that control.
Stripe Integration in Production
Test extensively with Stripe's test mode and test webhook events before going live, specifically exercising the failure and retry paths (failed payments, disputed charges, subscription cancellations), not just the happy path. Also set up Stripe's webhook event log monitoring and alerting for failed webhook deliveries — a webhook endpoint that starts silently failing is a payments bug that won't show up in your application logs unless you're specifically watching for it.
Before considering a Stripe integration production-ready, verify fulfillment happens only via the verified webhook and that duplicate event delivery is handled — those two things are where the real integration risk lives, not the checkout button itself.