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

第 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
第 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 的方案反推已经能识别它们。

第 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");
}
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 上线。

三种常见故障排查
若 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 能显示它。
沙箱矩阵,而不只是一条顺利路径
在碰生产之前,用测试模式跑完这些情况:
- 标准价格 id 买 Buyout——签发一次性许可。
- 标准价格 id 买 Care——订阅生效,续费日期已存。
- 促销开启时用 BF 价格 id——推出正确的 BF 方案。
- 同一个
checkout.completed事件投递两次——一份许可,不是两份。 - 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 名称。