Payment fixes for AI-built apps

The most common failures

Five payment-category failure modes show up in nearly every rescue intake for apps built with Lovable, Bolt, v0, Cursor, Claude Code, Base44, and Replit Agent. They are not exotic — they are the same scaffolding gaps repeated across every generator.

• Raw body consumed before signature verification. The generated route calls await request.json() first, which re-encodes the JSON Stripe signed byte-for-byte. stripe.webhooks.constructEvent then throws No signatures found matching the expected signature. Fix is await request.text() and pass the raw string. See Stripe webhook not firing and Webhook signature verification failed.
• Test-mode keys shipped to production. pk_test_ baked into the client bundle, sk_test_ in the server env, and no live-mode webhook endpoint registered in the Stripe dashboard. Users see a working checkout in preview; the live site either errors or silently drops every payment. See Stripe stuck in test mode in production.
• Missing STRIPE_WEBHOOK_SECRET in the production scope. Written to local .env during scaffolding, never propagated to Vercel Production. Every verification call throws, handler returns 500, Stripe enters exponential backoff, and the dashboard fills with red failed badges.
• Edge runtime on the webhook route. Bolt and some v0 templates default API routes to export const runtime = "edge". The Stripe Node SDK needs the Node crypto API and a real request body; edge strips both. Remove the directive; stay on the default Node runtime.
• No idempotency on retried events. Stripe replays events on any non-2xx. Without a unique constraint on event.id in a stripe_events table, a single transient timeout creates duplicate subscription rows, double entitlement grants, or repeated invoice emails. Store event.id, short-circuit on unique-violation.
• Slow work inside the webhook handler. Sending an email, running an AI call, or writing to multiple tables synchronously inside the handler risks Stripe's 10-second timeout. Acknowledge with 200 immediately, push the event to Inngest, QStash, or a Postgres queue, process async.

Shared root causes

The payment-category symptoms differ but their root causes cluster into four patterns. Any rescue starts by eliminating these before inspecting individual routes.

• Demo-path scaffolding. AI generators test one successful checkout.session.completed event against a test-mode webhook they registered during onboarding. Production paths — refund, dispute, subscription update — are never exercised.
• Env-var scope drift between Vercel environments. Keys are set in Development or Preview but never in Production. Because Next.js silently resolves process.env.MISSING to undefined, the bug only surfaces when Stripe retries exhaust and the customer emails support.
• Runtime and middleware side effects. Edge runtime directives, global body parsers, or Next.js middleware rewriting the request before the webhook route — each one invalidates the Stripe signature without a meaningful error.
• No replay-safe write path. Handlers assume exactly-once delivery. Stripe guarantees at-least-once. Every write should either be idempotent by construction or gated on event.id.

Prevention checklist

Merge these before the next Stripe-touching deploy. Each one turns a silent production failure into a loud build failure or a recoverable 200 response.

1. Validate process.env at module load with a zod schema — missing STRIPE_SECRET_KEY or STRIPE_WEBHOOK_SECRET should fail the build, not a live request.
2. Register a live-mode webhook endpoint in the Stripe dashboard the same day you flip to live keys. Copy the whsec_live_… secret into Vercel Production scope.
3. Scope test keys to Development and Preview only. Production should contain live keys exclusively.
4. Read the raw body in every webhook route: await request.text(), never await request.json().
5. Remove any export const runtime = "edge" directive from Stripe webhook routes and stay on the default Node runtime.
6. Store event.id in a stripe_events table with a unique constraint; short-circuit on 23505.
7. Return 200 within one second. Push slow work to Inngest, QStash, or a Postgres queue.
8. Add a CI step that runs stripe trigger checkout.session.completed against preview deploys and asserts a 200.
9. Log the first 8 characters of the signing secret on boot so a misconfigured deploy is visible in function logs within one request.
10. Replay one live event before announcing a pricing page or hitting publish on marketing.