Polar 结账接口

这是最可靠的 Polar 集成方式。Talivia 会在带签名的 order.paid 网络回调中收到同一会话编号，无需依赖返回访问即可归因订单。

将 Talivia 会话发送给后端

浏览器移交结账

const sessionId = window.talivia.getSessionId();

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

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

会话编号是归因标识符，不是身份验证凭据。请照常在后端验证商品和已登录用户。

创建结账时添加元数据

将 Polar 访问令牌保存在服务器。Polar 会把结账元数据复制到生成的订单和订阅，因此一个字段即可覆盖单次和循环产品。

创建 Polar 结账会话

import { Polar } from '@polar-sh/sdk';

const polar = new Polar({ accessToken: process.env.POLAR_ACCESS_TOKEN });

const checkout = await polar.checkouts.create({
  products: [process.env.POLAR_PRODUCT_ID],
  successUrl: 'https://your-site.com/thanks?checkout_id={CHECKOUT_ID}',
  returnUrl: 'https://your-site.com/pricing',
  externalCustomerId: user.id,
  customerEmail: user.email,
  metadata: { talivia_session_id: sessionId },
});

return Response.json({ url: checkout.url });

externalCustomerId 应是应用中稳定的编号，可为未来续费提供第二个匹配信号。请在成功网址中保留 checkout_id={CHECKOUT_ID}，作为备用和排查信号。