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。测试和正式环境的公钥不同。
填写项目配置
回到 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 Key | Webhook 公钥 |
勾选启用并点击 保存 provider。保存商户 ID、私钥和至少一个商品 ID 后卡片显示已配置;保存 webhook 公钥后显示 Webhook 已配置。要让买家输入优惠码,打开 结账时允许使用优惠码,优惠码在 Waffo 创建。
套餐要有对应商品
验证
- 用普通用户登录,打开
/pricing购买套餐。预期:跳转到 Waffo 结账页,显示套餐价格。 - 用 Waffo 的测试付款信息付款。预期:经
/api/billing/callback/waffo回到站点,服务端先在 Waffo 查询该订单的支付记录,再标记为已付款。 - 打开
/admin/billing-webhooks。预期:出现签名有效的order.completed(一次性)或subscription.activated(订阅)事件。 - 打开
/admin/orders。预期:订单已付款,账单显示实际扣款金额;用了优惠码时低于套餐价格。
切换到正式环境
- 创建正式环境的 API 密钥和商品,并关闭测试模式重新添加 webhook。
- 保存正式环境的商户私钥、商品 ID 和 webhook 公钥。测试密钥无法验证正式环境的事件。
- 实付一笔,并在 Waffo 后台退款。
常见问题
webhook 签名校验失败
保存的 webhook 公钥属于另一个环境,或者没有填写。Waffo 签名中的 t 以毫秒计,重试沿用原值,所以 45 分钟以内的事件都会接受,更早的会被拒绝。改写请求体的代理也会导致签名失效。
下单失败,提示 "No Waffo subscription product is configured"
套餐是订阅,但它的周期没有对应的商品 ID。保存月付或年付商品 ID,或修改套餐周期。
退款或续费没有反映到订单上
退款和订阅变更在 Waffo 后台操作。它们的事件(如 refund.succeeded、subscription.renewed)记为已忽略:不改变本地订单,不创建新订单,也不会再次发放套餐积分。