← Back to blogTry free

Stripe checkout.session.completed: how to grant access without giving it to unpaid users

November 13, 2026

The usual Stripe Checkout integration listens for checkout.session.completed, finds the user, and unlocks the product. It works in every demo. In production it has three holes: it can fire before the money has arrived, it can arrive without any way to tell which of your users it belongs to, and the fallback many people add, unlocking on the success page, can be triggered by anyone.

1. “Completed” is not “paid”

The event means the customer finished the Checkout form. For card payments the charge normally succeeds at the same moment, but for delayed payment methods such as bank debits the session can complete while the payment is still pending. Check the field that actually answers the question: session.payment_status. If it is not paid, do not grant access yet.

For those delayed methods Stripe sends a follow-up: checkout.session.async_payment_succeeded when the money arrives, or checkout.session.async_payment_failed when it does not. Handle all three event types, as in the handler below.

2. Link the session to your user before the customer leaves

The webhook arrives with Stripe’s customer id and an email, not with your user id. Matching by email breaks when the customer pays with a different address than their account. Set client_reference_id when you create the session and it comes back untouched on the event:

// When you create the session, attach YOUR user id to it
const session = await stripe.checkout.sessions.create({
  mode: 'subscription',
  line_items: [{ price: process.env.STRIPE_PRICE_ID!, quantity: 1 }],
  client_reference_id: user.id, // comes back on the webhook
  customer_email: user.email,
  success_url: 'https://example.com/welcome',
  cancel_url: 'https://example.com/pricing',
})

3. Grant access in the webhook handler

// After signature check + idempotency guard
switch (event.type) {
  case 'checkout.session.completed':
  case 'checkout.session.async_payment_succeeded': {
    const session = event.data.object as Stripe.Checkout.Session

    // "completed" means the customer finished the form.
    // It does NOT always mean the money has arrived.
    if (session.payment_status !== 'paid') break

    const userId = session.client_reference_id // set when you created the session
    if (!userId) break // cannot link this payment to anyone, log it and investigate

    await db.grantAccess({
      userId,
      stripeCustomerId: String(session.customer),
      stripeSubscriptionId: session.subscription ? String(session.subscription) : null,
    })
    break
  }

  case 'checkout.session.async_payment_failed': {
    const session = event.data.object as Stripe.Checkout.Session
    await notifyPaymentFailed(session.client_reference_id)
    break
  }
}

Run this behind a signature check and an idempotency guard, otherwise a retried event grants access twice. See signature verification failures and duplicate events.

4. Never unlock from the success_url

The redirect to your success page tells you the browser arrived there. It is not proof of payment: anyone can open that URL, and it can load before your webhook has been processed. Use the success page only to show a message like “we are activating your account”, and let it poll your own database until the webhook has flipped the flag. The other side of this race, a customer who paid and sees a paywall, is covered in a customer just paid you and is staring at a paywall.

Quick check: in the Stripe dashboard filter Checkout sessions by status complete, then compare each one against your users table. A paid session with no access, or access with no paid session, is a bug in this flow.

Access also has to end

Granting is the easy half. Subscriptions fail renewals, get canceled, refunded and downgraded, and none of that comes through checkout.session.completed. See what to do with access when a payment fails and the Stripe subscription lifecycle.

Check whether it already went wrong

Run the reconciliation script once to list paid customers without access and access without payment, or let Venwai compare Stripe with your app every day using a read-only key and alert you in Slack, Discord, Telegram, or email.

Free while it’s in beta, no card required: venwai.com.

Is your Stripe out of sync with your app?

Venwai compares Stripe with who your app actually lets in, once a day, using a read-only key. It alerts you the moment they disagree. Free while in beta, no card required.

Check my Stripe for free