Creem 支付接入指南

接入总览：三步

Creem 是托管收银台（Merchant of Record），接入的核心链路只有三步：

1. 拿 API Key — 注册后在 dashboard 的 Developers 区复制，塞进服务端环境变量 CREEM_API_KEY。先用测试模式开发，不产生真实扣款。
2. 建 checkout — 后端调 API 创建结账会话，拿回 checkout_url，把用户重定向过去付款。
3. 处理支付成功 — 用户付完会跳回 success_url；生产环境必须再挂 webhook，可靠地接收支付事件。

「建 checkout」到底是什么

它是一次 checkout session（结账会话）——让 Creem 临时为你生成一个专属付款页，拿到地址后把用户送过去付钱。后端调一次：

# POST /v1/checkouts
{
  "product_id": "prod_xxx",
  "success_url": "https://yoursite.com/success"
}

返回一个一次性付款页地址：

{
  "id": "ch_1Qy...",
  "checkout_url": "https://checkout.creem.io/ch_1Qy...",
  "status": "pending"
}

然后把用户丢过去：window.location.href = checkout_url。他在 Creem 托管的页面填卡付款，付完跳回你的 success_url。

它和「支付链接」的区别

怎么把「我的订单号」传给 Creem

两个字段，看你想在哪一步读回来：

// TypeScript SDK
const checkout = await creem.checkouts.create({
  productId: "prod_xxx",
  requestId: "order_123",          // ← 你的订单号
  metadata: { userId: "u_123", source: "campaign_x" },
  successUrl: "https://yoursite.com/success",
});

靠 success 跳转拿，和靠 webhook 有啥区别

跳转是给用户看的，webhook 是给你服务器记账的。

为什么生产要用 webhook

• 不丢单：用户付完直接关页面，跳转就没了——你这边「不知道人家付了」，但钱已经收了。webhook 不受用户行为影响。
• 不可伪造：跳转 URL 在用户可控的浏览器里，不验 signature 就能手工拼一个「成功」骗你的发货逻辑；webhook 有 HMAC 验签。
• 只有 webhook 管后续：续费、退订、退款、拒付根本没有「跳转」，只能靠 webhook。做订阅制是刚需。
• 权威性：发货 / 开权限 / 改数据库只信 webhook；跳转只负责「谢谢购买」的 UI。

API Key 用在哪

只有一个场景：你后端去调 Creem API 的凭证，同时兼作跳转签名的 salt。

• 所有服务端请求的 header：x-api-key: ***，建 checkout、查产品、管订阅都靠它认证。
• 验 success 跳转签名的 salt：sha256("k1=v1|k2=v2|...|salt={apiKey}")。

支付链接怎么知道谁付款了

静态支付链接本身不带你的用户身份，谁点都长一样。三条路：

1. 靠用户付款填的邮箱——Creem 侧记录 customer，dashboard 和 checkout.completed 事件都能看到。缺点：这个邮箱不一定等于你系统里的账号邮箱。
2. 给每人发带参数的链接——追加 ?metadata[userId]=u_123，会进 webhook 事件。但要为每人单独拼链接，批量起来和自己调 API 差不多。
3. 要真·可靠 → 用 checkout session——带 request_id / metadata，每次购买自动对上你的订单，还能动态设成功页。