← 返回博客
Tutorial发布于 2026-11-08· 9 分钟阅读

Creem 支付接入:Next.js 结账分步教程

WangNan, author at Uncorne
作者 WangNan
出品方 Uncorne · 更新于 2026-11-17

Creem 是最接近「类 Stripe 托管结账 + 商户登记」的方案。它替你处理销售税与 VAT,这正是费率高于裸处理器的原因——这个取舍在 Merchant of Record 概览里有解释。本教程把一个 Next.js SaaS 从零带到一次真实的沙箱支付。

由 Next.js 应用渲染的 Creem 托管结账页
由 Next.js 应用渲染的 Creem 托管结账页

第 0 步:先读文档

Creem 文档短到可以一口气扫完。这里要紧的是两页:商品/价格和 Webhook。把 Creem Webhook 指南开着——第 3 步你会回来查。

第 1 步:创建账户与 API key

在 Creem 注册,切到测试模式,创建 API key,存入 CREEM_API_KEY。开发期设 CREEM_ENV=test,沙箱往返变绿后再改为 live。测试 key 与正式 key 是分开的;混用是换来一头雾水的 401 的最快方式。

PAYMENT_PROVIDER=creem
CREEM_API_KEY=creem_test_xxx
CREEM_ENV=test
CREEM_WEBHOOK_SECRET=whsec_test_xxx
CREEM_PRICE_ID_BUYOUT=price_buyout_test
CREEM_PRICE_ID_CARE=price_care_test
Creem 测试模式 API key 界面
Creem 测试模式 API key 界面

第 2 步:创建商品与价格

在 Creem 后台为 Buyout 建一次性商品、为 Care 建周期商品。把价格 id 填入 CREEM_PRICE_ID_BUYOUT 与 CREEM_PRICE_ID_CARE——槽位名与套餐一致。若迁移旧配置,旧的 CREEM_PRICE_ID_PRO 与 CREEM_PRICE_ID_SCALE 名称仍作为回退被读取。做黑五促销时另建价格 id 并设 CREEM_PRICE_ID_BUYOUT_BF 与 CREEM_PRICE_ID_CARE_BF;Webhook 的方案反推已经能识别它们。

Creem 商品界面,显示 Buyout 与 Care 的价格 id
Creem 商品界面,显示 Buyout 与 Care 的价格 id

第 3 步:配置 Webhook

把 Creem 指向你的 /api/payments/webhook/creem 端点,把 Webhook 密钥存入 CREEM_WEBHOOK_SECRET。集成会在信任每个事件前验证签名。结账事件通过商品/价格 id 反推方案并发放许可;退款或取消事件则撤消它。

export async function POST(req: Request) {
  const body = await req.text();
  if (!verifyCreemSignature(body, req.headers)) {
    return new Response("bad signature", { status: 400 });
  }
  const evt = JSON.parse(body);
  if (evt.type === "checkout.completed") {
    await grantLicence(evt.customer, inferPlan(evt.product.id), evt.id);
  }
  if (evt.type === "subscription.canceled") {
    await revokeLicence(evt.customer);
  }
  return new Response("ok");
}
Creem Webhook 日志,列出一次完成的结账与一次退款事件
Creem Webhook 日志,列出一次完成的结账与一次退款事件

handler 作为 Next.js App Router route handler 运行,因此验证留在服务端。让发放幂等:Creem 会重试事件,重试的结账绝不能创建第二份许可。记录事件 id 与事件类型——当退款看似没有撤消访问时,这份日志会告诉你实际到达的是哪个事件。

第 4 步:设定网关

设 PAYMENT_PROVIDER=creem,外加 CREEM_API_KEY 与 CREEM_WEBHOOK_SECRET。结账调用为当前方案(或促销开启时的 BF 价格 id)选取正确价格 id,并重定向到 Creem 的托管结账。你从不接触卡号数据,这让 PCI 合规范围不落到你的应用上。

第 5 步:跑沙箱测试

用测试模式做一次测试购买。确认 Webhook 触发、方案被正确反推、许可 key 已签发,然后发起一笔测试退款,看着许可被撤消。最后这一步是人们最容易忘的,却是保护你收入的。完整往返变绿后,再用 CREEM_ENV=live 与正式 key 上线。

Creem 沙箱中退款事件撤消许可
Creem 沙箱中退款事件撤消许可

三种常见故障排查

若 Webhook 返回 400,检查时间戳窗口与密钥——重放或时间错位的事件会被设计性地拒绝。若方案总是默认那个,Creem 里的价格 id 与环境里的不一致。若退款后访问仍然有效,确认你同时处理取消与退款事件类型,而不只是结账。

以后换网关

因为 Creem、Waffo、Stripe、PayPal、Lemon Squeezy 在 Uncorne 里都位于同一套结账与 Webhook 契约之后,切换供应商只是配置项——不是重写。平行步骤见 Waffo 支付接入教程,更宏观的决策见计费网关指南。

结账调用实际做了什么

点击 Buyout 或 Care 会触发一个服务端 action,它解析方案的价目 id 并创建 Creem 结账会话。价格 id 在服务端选定,因此客户无法编辑 URL 参数用 Buyout 的价格买到 Care。会话在 metadata 里携带你的内部用户引用;Webhook 到达时,正是这个引用让你给正确的账户充值。把浏览器重定向到 Creem 返回的 URL——不要试图把它的结账嵌进你自己的布局里。

事件、幂等与重试契约

Creem 会重试 Webhook 投递,直到你的端点以 2xx 应答。让 handler 快且幂等:先确认,若许可服务慢再把工作丢进后台任务。把事件 id 存进唯一列,这样重试的 checkout.completed 不会创建第二份许可。记录事件 id、事件类型与商品 id——当有人报告退款没有移除访问权限时,这份日志就是你查出实际到达了哪个事件的办法。

周期性 Care:必须处理的三个事件

Care 是订阅,所以首次结账成功只是开始。处理 subscription.active 保持访问开启、subscription.canceled 在付费期末撤消访问,以及退款路径立即撤消。要明确决定取消是立即生效还是期末生效——中途切断访问是一张你本不需要的工单。把 Creem 返回的续费日期存下来,让你自己的 UI 能显示它。

沙箱矩阵,而不只是一条顺利路径

在碰生产之前,用测试模式跑完这些情况:

  1. 标准价格 id 买 Buyout——签发一次性许可。
  2. 标准价格 id 买 Care——订阅生效,续费日期已存。
  3. 促销开启时用 BF 价格 id——推出正确的 BF 方案。
  4. 同一个 checkout.completed 事件投递两次——一份许可,不是两份。
  5. Care 上做一笔测试退款——访问被撤消,没有遗留的订阅。

第 4、5 行是多数集成崩掉的地方。单靠一次成功购买证明不了什么。

上线清单

切到 CREEM_ENV=live,把测试 API key 与 Webhook 密钥换成正式的,并确认 Webhook URL 在生产域名上用 HTTPS。除非还需要回退,否则从环境里移除旧的 PRO 与 SCALE 价格 id。然后做一笔小额真实购买、再退款,盯住整条链路——结账、签名、方案、许可、撤消——之后再做任何对外宣布。

接下来读什么

因为五家适配器共用一个契约,若你换供应商,这些运维习惯可以直接带过去。Waffo 教程走的是平行配置,网关对比解释 Creem 的商户登记费率什么时候值回票价。

该记什么日志,以及为什么它重要

支付集成是你技术栈里人们半夜打你电话的部分。三行日志能让这种电话变短:Creem 事件 id、反推出的方案、以及采取的许可动作。有了这些字段,你不用问客户点了什么就能重建任何事故。再加上时间戳,你还能判断续费是晚了还是 Webhook 被重试过。原始负载不要写进日志——里面有客户邮箱——只存你真正需要的字段。若必须调试签名失败,记事件 id 与验证结果,而不是整个 body。十秒能读完的日志,比没人敢打开的冗长 dump 值钱得多。

FAQ

Creem 是商户登记(MoR)吗?+

是——Creem 替你处理销售税 / VAT 与合规,这正是其费率高于裸处理器的原因。投入前请以 Creem 定价页的当前费率为准。

需要验证 Creem Webhook 签名吗?+

需要。集成会在服务端对每个事件用 CREEM_WEBHOOK_SECRET 验证。跳过会让任何人用未签名请求伪造结账事件。

退款会怎样?+

Webhook 收到取消或退款事件后会撤消许可,使退款客户无法继续访问。上线前请在沙箱里测这条路径。

旧的 PRO 和 SCALE 价格 id 名还能用吗?+

能。迁移旧配置时 CREEM_PRICE_ID_PRO 与 CREEM_PRICE_ID_SCALE 仍作为回退被读取,但新项目应使用与套餐匹配的 BUYOUT 与 CARE 名称。

全部常见问题 · Markdown 版本(供 AI 智能体阅读)