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

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

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

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

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

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

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 for renewals, failed invoices, and customer identity.

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

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.