Checkout Session（收银会话）

Checkout Session 是推荐的收款方式：服务端凭 API Key 创建会话，拿到托管收银台 url，前端以弹层或跳转打开。税额自动计算。

核心概念

mode —— 会话用途

mode	用途	说明
`payment`	单次支付	line items 可用一次性价格或临时金额
`subscription`	开通订阅	line items 必须引用 `recurring` 类型的 `price_id`
`setup`	仅绑卡，不扣款	用于先收集支付方式、之后再扣款

presentation —— iframe 与 link

presentation	买家体验	前端代码
`iframe`	SDK 弹层，买家不离开你的网站（推荐）	`FastStar.checkout.open({ url })`
`link`	整页跳转到托管收银台	`window.location.href = url`

line_items

每个 line item 引用你的商品目录，或（仅 Direct/PSP 模式）传临时金额：

字段	类型	说明
`price_id`	string，可选	商品目录中的价格（`price_...`）
`product_id`	string，可选	商品目录中的商品（`prod_...`），使用其默认价格
`quantity`	int	数量
`ad_hoc_amount`	int64，可选	临时金额（最小货币单位）——仅 Direct/PSP 模式可用
`ad_hoc_currency`	string，可选	`ad_hoc_amount` 的币种
`description`	string，可选	收银台展示的条目描述

MoR 规则：Merchant of Record 商户的每个 line item 都必须引用商品目录的 price_id 或 product_id——平台需要商品信息完成税务合规。临时金额（ad_hoc_amount / ad_hoc_currency）仅在 Direct/PSP（直连）模式可用。商品目录通过 /merchant/catalog/products 与 /merchant/catalog/prices 管理（见 API 参考）。

税额如何展示

会话返回 amount_subtotal、amount_tax 与 amount_total（均为最小货币单位）：

含税地区（如欧盟 VAT）：税已包含在售价内，amount_total = amount_subtotal，amount_tax 展示其中包含的税额。
外加地区（如美国销售税）：税在售价之外另加，amount_total = amount_subtotal + amount_tax。

创建会话时传 buyer_country（必要时含地区）可在第一时间得到准确税额。

创建会话

curl https://api.faststarpay.com/api/v1/public/checkout/sessions \
  -H "X-API-Key: 你的_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "payment",
    "presentation": "iframe",
    "line_items": [
      { "price_id": "price_xxx", "quantity": 1 }
    ],
    "customer_email": "[email protected]",
    "success_url": "https://yoursite.com/success",
    "cancel_url": "https://yoursite.com/cancel",
    "buyer_country": "US",
    "client_reference_id": "order_10042"
  }'

响应（在统一的 { success, message, data } 响应包内）：

{
  "success": true,
  "message": "Checkout session created successfully",
  "data": {
    "session": {
      "id": "cs_xxx",
      "status": "open",
      "amount_subtotal": 999,
      "amount_tax": 80,
      "amount_total": 1079,
      "currency": "USD",
      "session_token": "xxx",
      "expires_at": "2026-06-13T12:00:00Z"
    },
    "url": "https://cashier.faststarpay.com/checkout/cs_xxx?token=xxx",
    "session_token": "xxx"
  }
}

请求字段

字段	类型	说明
`mode`	string	`payment` \| `subscription` \| `setup`
`presentation`	string	`iframe` \| `link`
`line_items`	array	见上文
`customer_email`	string，可选	预填买家邮箱
`success_url`	string	支付成功后的落地页
`cancel_url`	string	取消后的落地页
`buyer_country`	string，可选	ISO 国家代码，用于计算税额
`client_reference_id`	string，可选	你方订单 / 引用号，原样回传便于对账

服务端示例（Node）

// Express：创建 Checkout Session 并把 url 返回给浏览器
app.post('/api/checkout', async (req, res) => {
  const r = await fetch('https://api.faststarpay.com/api/v1/public/checkout/sessions', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': process.env.FASTSTAR_API_KEY, // API Key 只保存在服务端
    },
    body: JSON.stringify({
      mode: 'payment',
      presentation: 'iframe',
      line_items: [{ price_id: 'price_xxx', quantity: 1 }],
      success_url: 'https://yoursite.com/success',
      cancel_url: 'https://yoursite.com/cancel',
    }),
  });
  const { data } = await r.json();
  res.json({ url: data.url });
});

前端示例

// 从你的服务端拿到会话 url，再打开弹层
const { url } = await (await fetch('/api/checkout', { method: 'POST' })).json();
FastStar.checkout.open({ url });

FastStar.on('checkout.success', (data) => {
  // 仅界面交互——履约由 payment.succeeded Webhook 驱动
  console.log('已支付', data.checkout_session_id);
  window.location.href = '/thanks';
});

履约：前端事件用于确认买家体验，履约的唯一依据是服务端 Webhook（payment.succeeded）。用 client_reference_id 把事件匹配回你的订单。