Implement Stripe Checkout

The recommended implementation creates Stripe Checkout on your server, returns the public Checkout Session ID and URL to the browser, registers that ID with Biqli, and redirects only after registration succeeds.

Prerequisites

Before writing Checkout code:

connect the intended Stripe account and environment to the workspace;
enable conversion tracking;
configure the website hostname and a Biqli publishable key;
install @biqli/analytics in the browser or use the global script;
keep the Stripe secret key on your server;
decide whether the flow is a one-time payment, paid subscription, or subscription with trial.

Create Checkout on the server

This Express-style example accepts an authenticated customer and creates a one-time Checkout Session. Validate product and price choices on the server rather than trusting the browser.

import Stripe from 'stripe';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

app.post('/api/checkout', requireUser, async (request, response) => {
  const session = await stripe.checkout.sessions.create({
    mode: 'payment',
    customer: request.user.stripeCustomerId,
    line_items: [{price: 'price_example', quantity: 1}],
    success_url: 'https://app.example.com/billing/success',
    cancel_url: 'https://app.example.com/billing/cancel',
  });

  response.json({
    id: session.id,
    url: session.url,
    customerEmail: request.user.email,
  });
});

The response may contain the cs_... ID and Checkout URL. It must not contain your Stripe secret key.

Register and redirect in the browser

import {BiqliAnalytics} from '@biqli/analytics';

const biqli = new BiqliAnalytics({
  publishableKey: 'biqli_pk_xxxxxxxxx',
});

async function beginCheckout() {
  const response = await fetch('/api/checkout', {
    method: 'POST',
    credentials: 'same-origin',
  });
  if (!response.ok) throw new Error('Could not create Checkout.');

  const checkout = await response.json();

  await biqli.storeStripeSession({
    stripe_account_id: 'acct_example123',
    stripe_environment: 'live',
    stripe_session_id: checkout.id,
    customer_email: checkout.customerEmail,
  });

  window.location.assign(checkout.url);
}

If storeStripeSession() fails, show a retryable error before redirecting. Do not continue and assume the success page can repair attribution later. The browser SDK generates an idempotency key for this registration. A repeated exact request is safe. Reusing an identity for another click or reusing an idempotency key with different data is rejected.

One-time payment behavior

For mode: 'payment':

checkout.session.completed creates a sale only when payment_status is paid;
amount_total is recorded as integer minor units;
the Checkout Session ID is the durable Biqli invoice identity for this path;
PaymentIntent attribution is stored when Stripe includes it;
an unpaid completion establishes mapping but creates no sale.

Delayed payment methods

Some payment methods complete Checkout before payment settles.

checkout.session.completed can leave the mapping in an awaiting-payment state.
checkout.session.async_payment_succeeded records the one-time sale after settlement.
checkout.session.async_payment_failed marks the mapped Checkout failed and records no sale.

Do not create a provisional sale in your return page. Wait for Stripe’s final event.

Declines, 3DS, cancellation, and abandonment

Outcome	Expected Biqli result
Card declined	No sale. The customer can retry in Stripe or start a new Checkout.
3DS completed successfully	Sale after Stripe confirms payment.
3DS failed or abandoned	No sale.
Customer uses the cancel URL	No sale.
Checkout abandoned	No sale. Pending mapping expires.
Customer revisits your success URL	No additional sale.
Stripe resends the event	Same result; no duplicate revenue.

Payment Links and Pricing Tables

Stripe Payment Links and Pricing Tables create the Checkout Session inside Stripe, often after the browser has left the part of your application that knows bq_id. That means the recommended exact pre-redirect registration is not automatically available. Do not assume that installing the Stripe App makes arbitrary Payment Link sales attributable. Use one of these approaches:

Prefer a server-created Checkout Session and register its cs_... ID.
If your application already knows a verified customer email, create one pending mapping immediately before launch and rely on the unique-email fallback only when one eligible candidate exists.
Build a trusted server-side attribution flow and use Biqli’s generic sale API after verifying Stripe’s webhook yourself.

The email fallback is not suitable when multiple people, tabs, attempts, or workspaces can share the same email candidate. Biqli rejects ambiguity instead of guessing.

Embedded Checkout and custom frontends

Embedded Checkout uses the same principle: create the session on your server and call storeStripeSession() as soon as the browser receives the session ID, before the customer can complete payment. If you build directly with PaymentIntents rather than Checkout Sessions, preserve bq_id in your trusted order record and use the server tracking API after verified payment. The managed app’s browser registration endpoint accepts Checkout Session IDs, not arbitrary PaymentIntent IDs.

Keep product data authoritative

Biqli records the paid Stripe amount and currency. Subscription product labels come from invoice line data included in the allowed event payload. Biqli does not make a separate Product or Price lookup just to decorate conversion activity. Use Stripe as the authority for Checkout price, tax, discounts, and final amount. Never calculate the recorded sale from a browser-submitted display price.

Production checklist

Use stripe_environment: 'live' with cs_live_... sessions.
Use the live Stripe account ID connected to the intended workspace.
Use an allowed production hostname and the production workspace publishable key.
Keep all secret keys and Checkout creation on the server.
Register before every redirect, including retry and upgrade flows.
Test one real low-value payment and refund before sending production traffic.

For subscriptions and trials, continue with Subscription lifecycle.

GETTING STARTED

BROWSER TRACKING

SERVER TRACKING

INTEGRATIONS

OPERATIONS

Implement Stripe Checkout

Prerequisites

Create Checkout on the server

Register and redirect in the browser

One-time payment behavior

Delayed payment methods

Declines, 3DS, cancellation, and abandonment

Payment Links and Pricing Tables

Embedded Checkout and custom frontends

Keep product data authoritative

Production checklist

​Prerequisites

​Create Checkout on the server

​Register and redirect in the browser

​One-time payment behavior

​Delayed payment methods

​Declines, 3DS, cancellation, and abandonment

​Payment Links and Pricing Tables

​Embedded Checkout and custom frontends

​Keep product data authoritative

​Production checklist

Prerequisites

Create Checkout on the server

Register and redirect in the browser

One-time payment behavior

Delayed payment methods

Declines, 3DS, cancellation, and abandonment

Payment Links and Pricing Tables

Embedded Checkout and custom frontends

Keep product data authoritative

Production checklist