# Stripe Checkout Sessions (https://talivia.com/docs/revenue-guides/stripe/checkout-sessions)



Use this integration for Stripe-hosted Checkout and for embedded checkout built with the Checkout Sessions API.

## Pass the Talivia session to your backend [#pass-the-talivia-session-to-your-backend]

If your checkout request starts in browser code, include the current opaque session ID.

```javascript title="Browser checkout handoff"
const sessionId = window.talivia.getSessionId();

const response = await fetch('/api/create-checkout', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ sessionId }),
});

const { url } = await response.json();
window.location.assign(url);
```

When checkout is created on the same site as the Talivia tracker, your backend can read the `talivia_session_id` first-party cookie instead. Validate request input normally; the session ID is an attribution identifier, not authentication.

## One-time payment [#one-time-payment]

Set metadata on both the Checkout Session and its underlying Payment Intent. This preserves attribution whichever successful event Stripe delivers first.

```javascript title="Create a one-time Checkout Session"
const session = await stripe.checkout.sessions.create({
  mode: 'payment',
  line_items: [{ price: 'price_123', quantity: 1 }],
  success_url:
    'https://your-site.com/thanks?session_id={CHECKOUT_SESSION_ID}',
  cancel_url: 'https://your-site.com/pricing',
  metadata: {
    talivia_session_id: sessionId,
  },
  payment_intent_data: {
    metadata: {
      talivia_session_id: sessionId,
    },
  },
});
```

Top-level `metadata` appears on `checkout.session.completed`. `payment_intent_data.metadata` is copied to the Payment Intent and appears on `payment_intent.succeeded`.

## Subscription checkout [#subscription-checkout]

For recurring plans, copy the session ID to the Subscription so renewals and lifecycle events keep the original customer context.

```javascript title="Create a subscription Checkout Session"
const session = await stripe.checkout.sessions.create({
  mode: 'subscription',
  line_items: [{ price: 'price_monthly', quantity: 1 }],
  success_url:
    'https://your-site.com/thanks?session_id={CHECKOUT_SESSION_ID}',
  cancel_url: 'https://your-site.com/pricing',
  metadata: {
    talivia_session_id: sessionId,
  },
  subscription_data: {
    metadata: {
      talivia_session_id: sessionId,
    },
  },
});
```

Continue with [Subscriptions and invoices](https://talivia.com/docs/revenue-guides/stripe/subscriptions-and-invoices) for renewals, failed invoices, and customer identity.

## Delayed payment methods [#delayed-payment-methods]

Bank debits, vouchers, and some local payment methods can complete Checkout before money is confirmed. Talivia does not record an unpaid completed session as revenue. It waits for Stripe's asynchronous success event and imports only sessions whose `payment_status` is `paid`.

## Return URL fallback [#return-url-fallback]

Keep `{CHECKOUT_SESSION_ID}` in the success URL even when metadata is present. The return visit gives Talivia a second matching signal and helps diagnose missing metadata.