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

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

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

Waffo 有两种形态,接入方式也不同。本教程两种都覆盖,因为 Uncorne 的集成通过同一套结账与 Webhook 契约支持两者。读到最后,你会得到一次能发放许可的沙箱购买。

第 0 步:认清你在接哪一种 Waffo

Waffo 不是一个单一产品。Pancake 是全球化的商户登记(MoR)结账——见 Waffo Pancake 文档。Acquiring 是东南亚收单网关,Webhook 用 RSA 签名——见 Waffo Acquiring 文档。商户登记会替你承担销售税与 VAT,这个概念在 Merchant of Record 概览里有解释。除非你已有区域收单合同,否则选 Pancake。

Waffo 后台展示 Pancake 与 Acquiring 两种产品选择
Waffo 后台展示 Pancake 与 Acquiring 两种产品选择

第 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
Waffo API key 界面,高亮显示测试私钥
Waffo API key 界面,高亮显示测试私钥

第 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,因此促销无需改代码。

Waffo 商品界面,显示 Buyout 与 Care 的价格 id
Waffo 商品界面,显示 Buyout 与 Care 的价格 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");
}
Webhook 日志,显示一条已验证的支付事件与反推出的方案
Webhook 日志,显示一条已验证的支付事件与反推出的方案

上面的 Next.js App Router route handler 运行在服务端——这正是签名验证该待的地方,绝不要放进客户端组件。

第 5 步:设定网关

设 PAYMENT_PROVIDER=waffo 及上述变量。结账调用会为当前方案解析正确的价格 id,Webhook 则通过价格 id 反推方案并发放许可。若没配置价格 id,结账会回退到展示模式——预览有用,创收无用。

第 6 步:跑沙箱测试

使用测试环境做一次测试购买。确认 Webhook 触发、方案被正确反推、许可 key 已签发。然后测失败路径:未验证的签名必须以 400 拒绝。在真实沙箱往返变绿前不要上线。

Waffo 沙箱测试购买过程中的托管结账页
Waffo 沙箱测试购买过程中的托管结账页

三种常见故障排查

若结账能打开但没有许可,价格 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 存进唯一列,并把重复事件当作成功的空操作。这是「为什么这个客户有两个席位?」工单最常见的来源,而且在顺利路径测试里完全看不出来。

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

一次成功购买是演示,不是测试。上线前在测试模式跑完这张短矩阵:

  1. 标准价格 id 买 Buyout——许可签发,方案反推正确。
  2. 标准价格 id 买 Care——周期方案生效,续费日期已记录。
  3. 促销开启时用 BF 价格 id——BF 方案被反推,无需改代码。
  4. 同一事件 id 重放 Webhook——没有第二份许可,也没有重复扣款。
  5. 签名被篡改的请求——以 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 缺失是最常见的三个原因。

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