# Polar 结账接口 (https://talivia.com/zh-CN/docs/revenue-guides/polar/checkout-api)



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

## 将 Talivia 会话发送给后端 [#将-talivia-会话发送给后端]

```javascript title="浏览器移交结账"
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 会把结账元数据复制到生成的订单和订阅，因此一个字段即可覆盖单次和循环产品。

```javascript title="创建 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}`，作为备用和排查信号。