Stripe integration is mostly about choosing the right payment flow and trusting the webhook, not the browser. Use Checkout for a fast hosted flow, Payment Intents for a custom checkout and webhooks for fulfilment.
Key takeaways
- Never trust a price or amount sent from the client; resolve it on the server.
- Checkout Sessions and Payment Intents are different flows; pick one and keep it consistent.
- Webhooks are the source of truth for payment success, refunds and subscription changes.
- Prefer the simplest boundary that keeps data and authorisation on the server.
What matters in practice
- Verify the webhook signature against the raw request body.
- Use idempotency keys and make fulfilment safe to retry.
How to implement it
- Create products and prices. Keep price IDs in server-side configuration.
- Create the session. Resolve the cart and amount on the server, then create a Checkout Session.
- Redirect and return. Use the success URL only for UX; do not fulfil the order there.
- Handle the webhook. Verify the signature, check idempotency and update the order.
- Test the failures. Declined cards, 3D Secure, expired sessions, duplicate webhooks and refunds.
- Monitor. Log webhook failures and reconcile Stripe events with your database.
A working example
// app/api/webhooks/stripe/route.ts
import Stripe from "stripe";
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
export async function POST(request: Request) {
const body = await request.text();
const signature = request.headers.get("stripe-signature")!;
const event = stripe.webhooks.constructEvent(
body,
signature,
process.env.STRIPE_WEBHOOK_SECRET!,
);
if (event.type === "checkout.session.completed") {
await fulfilOrder(event.data.object.id);
}
return Response.json({ received: true });
}
Production checklist
| Area | Check |
|---|---|
| Prices | Server-side price IDs, never client amounts |
| Webhook | Raw body, signature verification and idempotency |
| Fulfilment | Safe to retry; no duplicate emails or licences |
| Tax | Stripe Tax or your own rules, reviewed by an accountant |
| Testing | Declines, 3DS, refunds, disputes and duplicate events |
| Reconciliation | A daily check between Stripe and your order table |
Common mistakes
- Fulfilling an order on the success page instead of the webhook.
- Parsing the webhook body as JSON before verifying the signature.
- Trusting a client-supplied price or currency.
- Ignoring duplicate and out-of-order webhook events.
When this is the wrong tool
Every tool has a boundary. If the team is small, the use case is simple and the operational cost is high, a simpler stack may be better. The right choice is the one you can debug, secure and hand over without the original author.
Rollout plan
- Prove one slice. Use Stripe in Next.js for one real route or feature, not the whole product.
- Set the boundary. Write down what stays on the server, what runs on the client and how data crosses the boundary.
- Add the safety net. Types, validation, tests and error handling around the new slice.
- Measure. Check bundle size, latency, error rate and the developer experience before expanding.
- Document and hand over. Record the pattern, the pitfalls and the version constraints.
Testing strategy
| Layer | What to test | Why |
|---|---|---|
| Types | Strict compile and no unjustified any | Catches contract drift early |
| Unit | Pure logic, validation and state transitions | Fast feedback |
| Integration | API, database and auth boundaries | Most production failures live here |
| End-to-end | The critical user journey | Proves the wiring |
| Operations | Logs, errors, retries and rollback | A release is not finished at deploy |
Operational checklist
- Pin the runtime and dependency versions; test upgrades in a branch.
- Keep secrets on the server and validate every external payload.
- Add structured logs with a request ID, but never log tokens or personal data.
- Set a performance or bundle budget and check it in CI.
- Write a short runbook for the most likely failure.
Frequently asked questions
Use Checkout when you want Stripe to host the payment page and you do not need a fully custom checkout. Use Payment Intents when you need control over the UI and the payment flow.
Yes, if you need reliable fulfilment. The success page can be closed, refreshed or spoofed; the webhook is the server-side confirmation.
Use the Stripe CLI to forward events to your local route and replay events. Test duplicate events and failed signatures.
Yes, but confirm your registration and nexus obligations with an accountant. Stripe calculates tax; it does not decide where you are liable.
Sources and further reading
- Stripe Checkout documentation (docs.stripe.com)
- Stripe Billing documentation (docs.stripe.com)
- Stripe webhooks documentation (docs.stripe.com)
- PCI Security Standards Council (pcisecuritystandards.org)
Related reading
Need an implementation review?
Send the repository or the design. I will review the boundary, the failure modes and the parts that will be expensive to change later.
How to cite this guide: Nur Hossain Repon, “Stripe in Next.js: complete developer guide (2026)”, Nhrepon Portfolio, reviewed October 2026, https://nhrepon.com/posts/stripe-in-next-js-complete-developer-guide-2026.





Comments
No comments yet.