Stripe Checkout works. Why is my Next.js app still showing unpaid?

Anthony Loren — Sun, 08 Nov 2026 01:54:45 +0000

Originally published on Helpful Mods. I build Helpful Mods, which sells the Funnel service used in this walkthrough.

The customer finishes Checkout, lands on your success page, and clicks the thing they just paid for. Your app sends them straight back to pricing.

Before changing the redirect, follow that purchase into the application. Which user owns it? Has the payment worker processed it? What does the paid page read when the customer arrives?

The interesting part is often between those steps. Stripe can have a completed payment while your app is still waiting for a worker, looking up another customer, or serving an old access result.

Here's how I'd connect a Next.js App Router app to Funnel and Revenue and work through it. Funnel runs beside the app as a Node.js service with PostgreSQL and a background worker. Your existing login and application database stay involved throughout.

Start with one purchase and its IDs

Open the failing purchase and put these values next to each other:

Record	What it connects
App user ID	The signed-in person opening the paid page.
Funnel customer ID	That person's saved customer journey.
Checkout ID	The purchase attempt queued in Funnel.
Stripe Session ID	The Checkout Session created for that attempt.

This catches a surprisingly ordinary problem: the customer pays in one account, then opens your app in a browser signed into another. It also catches code that creates the right purchase but reads access for a different customer.

Save the Funnel customer ID against your app user in the database. Later routes can find it from the current session. If your app already has a billing-account record, that's a sensible home for the mapping.

Connect the Next.js backend to Funnel

The example on GitHub includes lib/funnel-client.mjs, a small adapter for the calls below. Put it behind a server-only wrapper in your app and supply the signToken helper from your purchased Funnel package's dist/core/auth.js:

const funnel = createFunnelClient({
  origin: process.env.FUNNEL_ORIGIN,
  tenant: process.env.FUNNEL_TENANT_ID,
  offerId: "standard",
  signToken: claims => signToken(claims, process.env.HM_AUTH_SECRET),
});

FUNNEL_ORIGIN is the origin of your installed service. HM_AUTH_SECRET is the same private signing secret configured there. The wrapper lives in your backend, where it can use that secret and read your existing authentication session.

Shape the verified session result as {userId, email, emailVerified}, then capture the customer:

const customerId = await funnel.capture(session, actualConsentChoice);

The adapter calls POST /api/funnel/commands/capture with the email and consent choice. It signs the app user ID as the token's sub; Funnel uses that actor as the customer owner. Save the returned customerId before moving on to checkout.

If you get verified_email_required, inspect the token claims. Funnel needs verifiedEmail from the account your authentication provider has verified. A user can have a valid app session while their email is still unverified, or your adapter can accidentally leave the verified claim out. This is worth checking before spending an afternoon on Stripe settings.

The example adapter creates short-lived, customer-scoped tokens for each call. Your Route Handler obtains the current session and customer mapping first. The Next.js authentication guide has useful examples of doing that authorization close to the data request.

Give the checkout worker time to return a URL

The checkout command is POST /api/funnel/commands/checkout:

{
  "customerId": "THE_SAVED_CUSTOMER_ID",
  "offerId": "standard",
  "requestKey": "THE_SAVED_PURCHASE_INTENT_KEY"
}

In the adapter, that becomes:

const checkoutId = await funnel.startCheckout(
  session,
  customerId,
  savedRequestKey,
);

Save one request key for the attempt. When the response gets lost or someone double-clicks, retrying that key continues the same work. Creating a new key on every click gives you more attempts to untangle.

The command returns a checkoutId and a jobId. The worker then creates the Stripe Session and saves its URL. Read the customer command with {customerId} and find the entry matching your saved checkout ID. The adapter does that lookup for you:

const checkout = await funnel.checkoutStatus(session, customerId, checkoutId);
if (checkout.ready) {
  // Return this URL to the checkout interface so it can navigate there.
  return Response.json({ url: checkout.url });
}
return Response.json({ status: "preparing" }, { status: 202 });

Put a “Preparing checkout…” state here and poll your authenticated status route with a bounded delay. If the URL never appears, inspect the saved job and worker heartbeat. An idle worker can make the checkout button look broken even though the request was saved successfully.

Follow the payment back into the app

Your Stripe Snapshot webhook destination for this installation is:

https://YOUR_FUNNEL_SERVICE/webhooks/stripe/funnel

Configure that destination's signing secret as HM_STRIPE_WEBHOOK_SECRET. Funnel verifies the delivery and queues a read of the current Stripe resource. The same worker that prepared Checkout also needs to be running for this part.

When payment succeeded but access hasn't changed, Stripe's delivery history is a useful next stop. Look at the destination URL and response. An old development endpoint or a signing secret from another destination can leave a perfectly good payment disconnected from the deployed application.

Then follow the saved job into the checkout record. A received event tells you the request arrived; the reconciliation result tells you what the app learned about the purchase.

If the delivery history shows the same purchase arriving more than once, our duplicate-webhook guide follows the event and purchase IDs into a database transaction. That's useful when one payment creates two fulfillment jobs, or a replay appears to change an already-settled purchase.

Stripe's Checkout fulfillment guide explains another reason to build this path: customers sometimes pay and close the tab before reaching your success page. Their purchase still needs to reach the application.

Read current access where the paid resource is served

Funnel's access command takes {customerId} and returns active, status and offerIds. The example adapter checks for active access to its configured offer:

const access = await funnel.access(session, customerId);
if (!access.allowed) {
  return <PaymentStatus status={access.status} />;
}
return <PaidWorkspace />;

Put that check in the backend operation that serves the paid data as well as the page. If reconciliation is still running, show the current payment status and a way to check again. That gives the customer something more useful than another trip to pricing.

For the paid page, use dynamic rendering and a fresh service read. The adapter sets cache: "no-store"; your own access endpoint should also send Cache-Control: no-store. Otherwise, a cached unpaid result can outlive the payment that should have replaced it. The Next.js Route Handler reference covers the Request and Response APIs used by the adapter.

A fresh access check also picks up later changes. A refund, expired subscription or billing hold should affect the next protected request, including when the customer has kept the same tab open.

Stripe took the payment. Now give the customer access. goes further into those rules, including failed renewals and partial refunds. Once the Next.js connection works, those are good cases to put through the same access screen.

Try the awkward states while you're building

The Next.js example ZIP gives you a local app where you can start a sample checkout, leave access pending, simulate confirmation and apply a later hold. Open the protected resource after each change and watch what the server returns. The sample states make the waiting and recovery screens easy to work on before connecting your own Stripe account.

Run npm ci, npm test and npm run dev, then open http://127.0.0.1:3000. The GitHub repository has the adapter, tests and instructions for connecting it to your existing auth and customer records.

Once those pieces are connected, take the original failing purchase through the same path again. You should be able to point to the app user, their saved checkout, the worker's reconciliation result and the current access response. That's a much better explanation of “paid” than the page the browser happened to land on.

Funnel and Revenue supplies the customer journey, durable checkout jobs, Stripe reconciliation and access reads used here.

Written with AI assistance. The implementation and example repository are linked throughout.

DEV Community: Anthony Loren