全部文章

一本积分账本,接 Stripe、PayPal、Waffo 和 Dodo Payments

大多数 SaaS 模板从 Stripe 起步,但一个渠道往往不够。Stripe 并不接受所有国家的商家,很多买家更愿意用 PayPal 付款,而面向全球销售还要处理销售税和增值税。Dodo Payments 这样的记录商户(Merchant of Record)以自己的名义替你销售,并代为处理这些税务。所以多数付费工具最终都需要不止一个渠道,而每多接一个渠道,就多一套 Webhook、退款和边界情况要处理。

SaaScaffold 通过 Stripe、PayPal、Waffo 和 Dodo Payments 收款。四个渠道共用一条订单流程和一本积分账本,所以退款、续费或丢失的 Webhook,无论由哪个渠道处理,看起来都一样。

从结账到积分

每个渠道都走同样的五步:

  1. 保存订单快照。 打开结账页之前,商品、价格、币种、渠道和环境已保存在服务端。
  2. 验证通知。 Webhook 经过签名校验,并与保存的订单核对。
  3. 每个事件只应用一次。 事件先存储再应用,重复的通知会被识别并忽略。
  4. 付款与发放一起写入。 付款和对应积分在同一个原子操作中写入。
  5. 不信任返回页。 从结账页返回不代表已付款,站点会从服务端向渠道核对订单。

三种支付模式

全站模式决定谁能购买,与每个渠道的测试和正式连接相互独立:

  • off:不接受新订单,已有订单、续费和退款照常工作。
  • admin_test:只有管理员能通过测试连接购买。
  • live:客户真实购买,管理员仍可选择测试路径。

四个渠道都支持订阅

月付和年付套餐在四个渠道上都可用。续费依据渠道自己的账单记录入账,迟到的通知会匹配到正确的周期。整个计费周期可以通过渠道退款。

接入其他渠道

SaaScaffold 没有内置的渠道,写在你自己的站点文件里,底座更新不会动到它:

  1. 在 apps/web/src/site/payment-channels.ts 中声明:ID、显示名称和商品 ID 格式。
  2. 在 apps/web/src/site/payments/<id>.server.ts 中编写适配器:创建结账、查询状态、验证并解析 Webhook、退款。只有渠道自己按周期扣款时,才需要加订阅方法。
  3. 在 apps/web/src/site/payment-channels.server.ts 中注册适配器。

新渠道与内置的四个遵循同样的规则。只有金额和币种与订单一致的付款才会发放积分。每个订单只发放一次。丢失的 Webhook 会通过向渠道回读结账来补上。在渠道后台发起的退款或争议会冻结订单,等待人工核对。测试套件中的契约检查会列出适配器漏报的任何信息。

订单流程、账本和退款都不需要改动。编码 Agent 可以按照随代码附带的手册(agents/payments/add-a-payment-method.md)完成整个接入。

了解更多:SaaScaffold 的支付功能。