Stripe 结账会话

Stripe 托管结账以及用结账会话接口构建的内嵌结账都适用此集成。

将 Talivia 会话传给后端

如果结账请求从浏览器代码开始，请包含当前不透明的会话编号。

浏览器移交结账

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);

如果结账与 Talivia 追踪器位于同一网站，后端也可以读取第一方 Cookie talivia_session_id。请照常验证请求输入；会话编号是归因标识符，不是身份验证凭据。

单次付款

同时为结账会话及其底层付款意图设置元数据，让两个对象都保留相同的归因信息。Talivia 会从结账会话事件记录这类付款。订单引用以 cs_ 开头的结账会话支持的付款意图会被忽略，以免重复计算收入。

创建单次付款结账会话

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 } },
});

顶层 metadata 出现在 checkout.session.completed 上；payment_intent_data.metadata 会复制到付款意图，并出现在 payment_intent.succeeded 上。

订阅结账

循环套餐应把会话编号复制到订阅，让续费和生命周期事件保留原始客户上下文。

创建订阅结账会话

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 } },
});

续费、失败账单和客户身份请继续阅读订阅与账单。

延迟付款方式

银行扣款、凭证及部分本地付款方式可能在确认到账前就完成结账。Talivia 不会将尚未付款的已完成会话记为收入，而会等待 Stripe 异步成功事件，并只导入 payment_status 为 paid 的会话。

返回网址备用信号

即使已经添加元数据，也请在成功网址中保留 {CHECKOUT_SESSION_ID}。返回访问能提供第二个匹配信号，也有助于排查元数据缺失。