一本积分账本,接 Stripe、PayPal、Waffo 和 Dodo Payments
大多数 SaaS 模板从 Stripe 起步,但一个渠道往往不够。Stripe 并不接受所有国家的商家,很多买家更愿意用 PayPal 付款,而面向全球销售还要处理销售税和增值税。Dodo Payments 这样的记录商户(Merchant of Record)以自己的名义替你销售,并代为处理这些税务。所以多数付费工具最终都需要不止一个渠道,而每多接一个渠道,就多一套 Webhook、退款和边界情况要处理。
SaaScaffold 通过 Stripe、PayPal、Waffo 和 Dodo Payments 收款。四个渠道共用一条订单流程和一本积分账本,所以退款、续费或丢失的 Webhook,无论由哪个渠道处理,看起来都一样。
从结账到积分
每个渠道都走同样的五步:
- 保存订单快照。 打开结账页之前,商品、价格、币种、渠道和环境已保存在服务端。
- 验证通知。 Webhook 经过签名校验,并与保存的订单核对。
- 每个事件只应用一次。 事件先存储再应用,重复的通知会被识别并忽略。
- 付款与发放一起写入。 付款和对应积分在同一个原子操作中写入。
- 不信任返回页。 从结账页返回不代表已付款,站点会从服务端向渠道核对订单。
三种支付模式
全站模式决定谁能购买,与每个渠道的测试和正式连接相互独立:
off:不接受新订单,已有订单、续费和退款照常工作。admin_test:只有管理员能通过测试连接购买。live:客户真实购买,管理员仍可选择测试路径。
四个渠道都支持订阅
月付和年付套餐在四个渠道上都可用。续费依据渠道自己的账单记录入账,迟到的通知会匹配到正确的周期。整个计费周期可以通过渠道退款。
接入其他渠道
SaaScaffold 没有内置的渠道,写在你自己的站点文件里,底座更新不会动到它:
- 在
apps/web/src/site/payment-channels.ts中声明:ID、显示名称和商品 ID 格式。 - 在
apps/web/src/site/payments/<id>.server.ts中编写适配器:创建结账、查询状态、验证并解析 Webhook、退款。只有渠道自己按周期扣款时,才需要加订阅方法。 - 在
apps/web/src/site/payment-channels.server.ts中注册适配器。
新渠道与内置的四个遵循同样的规则。只有金额和币种与订单一致的付款才会发放积分。每个订单只发放一次。丢失的 Webhook 会通过向渠道回读结账来补上。在渠道后台发起的退款或争议会冻结订单,等待人工核对。测试套件中的契约检查会列出适配器漏报的任何信息。
订单流程、账本和退款都不需要改动。编码 Agent 可以按照随代码附带的手册(agents/payments/add-a-payment-method.md)完成整个接入。
了解更多:SaaScaffold 的支付功能。