Waffo 支付接入:Next.js 结账分步教程
Waffo 有两种形态,接入方式也不同。本教程两种都覆盖,因为 Uncorne 的集成通过同一套结账与 Webhook 契约支持两者。读到最后,你会得到一次能发放许可的沙箱购买。
第 0 步:认清你在接哪一种 Waffo
Waffo 不是一个单一产品。Pancake 是全球化的商户登记(MoR)结账——见 Waffo Pancake 文档。Acquiring 是东南亚收单网关,Webhook 用 RSA 签名——见 Waffo Acquiring 文档。商户登记会替你承担销售税与 VAT,这个概念在 Merchant of Record 概览里有解释。除非你已有区域收单合同,否则选 Pancake。

第 1 步:设定形态与环境
把 WAFFO_FLAVOR 设为 pancake 或 acquiring。默认是 pancake;适配器据此切换端点与签名。每个开发步骤都设 WAFFO_ENVIRONMENT=test。带着测试环境上线是最常见的丢单方式——结账看着正常,但没有真实资金流动,也不会发放许可。
第 2 步:收集凭证
Pancake 需要 WAFFO_STORE_SLUG(或 WAFFO_STORE_ID / WAFFO_MERCHANT_ID)与 WAFFO_PRIVATE_KEY。Acquiring 需要商户合同字段——WAFFO_ACQUIRING_MERCHANT_INFO、WAFFO_ACQUIRING_USER_INFO、WAFFO_ACQUIRING_PAYMENT_INFO、WAFFO_ACQUIRING_ORDER_CURRENCY、WAFFO_ACQUIRING_ORDER_DESCRIPTION——外加各环境的 Webhook 公钥。把它们放进 .env.local,绝不要提交进仓库。
PAYMENT_PROVIDER=waffo
WAFFO_FLAVOR=pancake
WAFFO_ENVIRONMENT=test
WAFFO_STORE_SLUG=your-store
WAFFO_PRIVATE_KEY=sk_test_xxx
WAFFO_PRICE_ID_BUYOUT=price_buyout_test
WAFFO_PRICE_ID_CARE=price_care_test
第 3 步:创建商品与价格
在 Waffo 后台为 Buyout 建一次性商品、为 Care 建周期商品,把价格 id 填入 WAFFO_PRICE_ID_BUYOUT 与 WAFFO_PRICE_ID_CARE。做黑五促销时,另建价格 id 并设 WAFFO_PRICE_ID_BUYOUT_BF 与 WAFFO_PRICE_ID_CARE_BF。Webhook 的方案反推会自动识别 BF id,因此促销无需改代码。

第 4 步:配置 Webhook
把 Waffo 指向你的 /api/payments/webhook/waffo 端点。Pancake 用平台 RSA 公钥(WAFFO_WEBHOOK_PUBLIC_KEY,含 test 与 prod 变体)验证。Acquiring 用 RSA 给请求签名,也需要同一把公钥。务必在服务端验证签名后再信任负载——绝不能跳过。一个接受未验证事件的 Webhook 端点,让任何人用一条 curl 就能伪造已支付订单。
handler 要做三件事:验证签名、从价格 id 反推方案、幂等地调用许可发放,这样重试的事件不会签发两份许可。记录事件 id 与价格 id;当支付没有发放访问权限时,这份日志是你第一个要查的地方。
export async function POST(req: Request) {
const raw = await req.text();
if (!verifyWaffoSignature(raw, req.headers)) {
return new Response("bad signature", { status: 400 });
}
const event = JSON.parse(raw);
const plan = inferPlanFromPriceId(event.price_id);
await grantLicence(event.customer, plan, event.id);
return new Response("ok");
}
上面的 Next.js App Router route handler 运行在服务端——这正是签名验证该待的地方,绝不要放进客户端组件。
第 5 步:设定网关
设 PAYMENT_PROVIDER=waffo 及上述变量。结账调用会为当前方案解析正确的价格 id,Webhook 则通过价格 id 反推方案并发放许可。若没配置价格 id,结账会回退到展示模式——预览有用,创收无用。
第 6 步:跑沙箱测试
使用测试环境做一次测试购买。确认 Webhook 触发、方案被正确反推、许可 key 已签发。然后测失败路径:未验证的签名必须以 400 拒绝。在真实沙箱往返变绿前不要上线。

三种常见故障排查
若结账能打开但没有许可,价格 id 几乎可以肯定是错的——把它和 Webhook 日志对照。若测试环境签名校验失败,你用的是生产公钥而不是测试公钥。若方案总是 Buyout,说明 Care 的价格 id 从没写进环境。
以后换网关
在 Uncorne 里,五家服务商适配器共享这套契约,因此 Creem、Stripe、PayPal、Lemon Squeezy 走的是同一代码路径——只换环境变量。平行步骤见 Creem 支付接入教程,或在投入之前读 网关对比来做选择。
结账调用实际做了什么
访客点击 Buyout 或 Care 时,服务端 action 读取当前方案、解析匹配的价格 id,并开启一个 Waffo 托管的结账会话。价格 id 来自服务端,因此客户无法通过篡改 URL 参数用 Buyout 的价格买到 Care。会话携带指向你内部用户 id 的 metadata 引用;支付清算后,Webhook 正是靠这个引用知道该给哪个账户充值。
Pancake 与 Acquiring 实际差在哪
两种形态共享结账与 Webhook 契约,但签名路径不同。Pancake 用平台 RSA 公钥验证负载;Acquiring 用 RSA 给每个请求签名,并在你这边期待同一把公钥。因此验证 helper 应把形态作为参数,而不是硬编码某一套算法分支。测试与生产要各用一把公钥,并在每条 Webhook 日志里打上环境标记——没有环境标签的日志,在故障时几乎没用。
值得记录的 Webhook 事件
Waffo 会发送支付完成、退款与争议事件。每一条都记三个字段:事件 id、价格 id 与客户引用。因为价格 id 在日志里,几个月后你都能回答「这个人到底买的哪个方案?」而不必猜。争议事件应把许可标记为待复核,而不是悄悄撤消——在切断付费客户之前,你需要人读过证据。
幂等不是可选项
当你的端点响应不够快时,Waffo 会重试 Webhook 投递。如果 handler 在确认事件之前就发放许可,一次慢数据库调用就可能为同一笔购买发放两份许可。把事件 id 存进唯一列,并把重复事件当作成功的空操作。这是「为什么这个客户有两个席位?」工单最常见的来源,而且在顺利路径测试里完全看不出来。
沙箱矩阵,而不只是一条顺利路径
一次成功购买是演示,不是测试。上线前在测试模式跑完这张短矩阵:
- 标准价格 id 买 Buyout——许可签发,方案反推正确。
- 标准价格 id 买 Care——周期方案生效,续费日期已记录。
- 促销开启时用 BF 价格 id——BF 方案被反推,无需改代码。
- 同一事件 id 重放 Webhook——没有第二份许可,也没有重复扣款。
- 签名被篡改的请求——以 400 拒绝并记录。
第 5 行能抓出配错的公钥。一条全绿的顺利路径配着坏掉的签名校验,等于你刚上线了一个安全漏洞。
上线清单
把 WAFFO_ENVIRONMENT 切到 production,换成正式私钥与正式 Webhook 公钥,并把 Webhook URL 指向生产域名的 HTTPS 地址。然后做一笔小额真实购买,盯住整条链路:支付、Webhook、方案反推、许可。别把测试价格 id 带进生产——这是「staging 里明明能用」工单最常见的原因。
接下来读什么
FAQ
该用哪种 Waffo 形态?+
想要全球商户登记结账用 pancake。仅当你已有需要特定字段与 RSA 签名的区域收单合同时,才用 acquiring。
需要验证 Waffo Webhook 签名吗?+
需要。集成对两种形态都用平台公钥在服务端验证。跳过验证会让任何人用未签名请求伪造已支付事件。
许可是怎么签发的?+
Webhook 通过价格 id(含 BF id)反推方案并幂等调用许可发放。若未配置价格 id,结账会回退到展示模式。
支付后没有发放访问权限该查什么?+
把 Webhook 日志里的价格 id 与环境变量对照。价格 id 写错、测试环境用了生产公钥、Care 价格 id 缺失是最常见的三个原因。