Waffo

通过 Waffo 收款,由它作为 merchant of record 代收代缴销售税。

  • 结账 Waffo 托管结账页,价格取自套餐(含税)
  • 订阅 月付与年付,首期付款时结算
  • 客户门户 不支持
  • 退款 只能在 Waffo 后台操作
  • 优惠码 支持

Waffo 是 merchant of record(记录商户):由它向买家销售并处理各地销售税。结账要求商品预先存在于 Waffo,但只需建三个商品,所有套餐共用;每次结账的价格取自套餐。

准备工作

准备公网 HTTPS 站点、/admin/plans 中已上架的套餐(见管理定价套餐),以及开好店铺的 Waffo 商户账号。整个流程跑通前都在测试环境操作。

完成后,一笔测试订单经签名的 order.completed 或 subscription.activated webhook 结算。

在 Waffo 完成准备

创建 API 密钥

在 Waffo 后台打开 API & Development → API Keys,点击 Create API Key 并选择测试环境。立即下载私钥,之后不会再显示。测试还是正式由密钥所属环境决定。同时记下商户 ID(MER_…)。

创建商品

创建一个一次性商品、一个月付订阅商品和一个年付订阅商品,复制它们的 ID。每次结账都会覆盖价格,商品本身的价格无所谓。

登记 webhook

在 Settings → Webhooks 添加一个测试模式的 HTTP webhook,地址为 https://<你的域名>/api/billing/webhook/waffo,订阅 order.completed 和 subscription.activated。

复制 webhook 公钥

在同一页面复制测试环境的 Webhook Public Key。测试和正式环境的公钥不同。

官方说明 · 认证 · 创建结账会话 · Webhooks

填写项目配置

回到 Kernlift 后台,打开 /admin/config/payment。选择 Waffo,填写公网成功 URL 和取消 URL,API base URL 保持 https://api.waffo.ai。

来源后台字段
商户 ID(MER_…)商户 ID(MER_...)
所售商品的税务类别:saas、digital_goods、software、ebook、online_course、consulting 或 professional_service税务类别(saas、digital_goods、software 等);留空保持 saas
三个商品 ID一次性商品 ID、月付订阅商品 ID、年付订阅商品 ID
下载的 API 私钥商户私钥
同一环境的 Webhook Public KeyWebhook 公钥

勾选启用并点击 保存 provider。保存商户 ID、私钥和至少一个商品 ID 后卡片显示已配置;保存 webhook 公钥后显示 Webhook 已配置。要让买家输入优惠码,打开 结账时允许使用优惠码,优惠码在 Waffo 创建。

套餐要有对应商品

一次性套餐需要一次性商品,月付或年付套餐需要对应周期的订阅商品,缺少时下单被拒绝。按其它周期续费的订阅套餐无法通过 Waffo 销售。
Kernlift 后台的 Waffo 配置字段

验证

  1. 用普通用户登录,打开 /pricing 购买套餐。预期:跳转到 Waffo 结账页,显示套餐价格。
  2. 用 Waffo 的测试付款信息付款。预期:经 /api/billing/callback/waffo 回到站点,服务端先在 Waffo 查询该订单的支付记录,再标记为已付款。
  3. 打开 /admin/billing-webhooks。预期:出现签名有效的 order.completed(一次性)或 subscription.activated(订阅)事件。
  4. 打开 /admin/orders。预期:订单已付款,账单显示实际扣款金额;用了优惠码时低于套餐价格。

切换到正式环境

  1. 创建正式环境的 API 密钥和商品,并关闭测试模式重新添加 webhook。
  2. 保存正式环境的商户私钥、商品 ID 和 webhook 公钥。测试密钥无法验证正式环境的事件。
  3. 实付一笔,并在 Waffo 后台退款。

常见问题

webhook 签名校验失败

保存的 webhook 公钥属于另一个环境,或者没有填写。Waffo 签名中的 t 以毫秒计,重试沿用原值,所以 45 分钟以内的事件都会接受,更早的会被拒绝。改写请求体的代理也会导致签名失效。

下单失败,提示 "No Waffo subscription product is configured"

套餐是订阅,但它的周期没有对应的商品 ID。保存月付或年付商品 ID,或修改套餐周期。

退款或续费没有反映到订单上

退款和订阅变更在 Waffo 后台操作。它们的事件(如 refund.succeeded、subscription.renewed)记为已忽略:不改变本地订单,不创建新订单,也不会再次发放套餐积分。

下一步