接入支付服务商

完成后,买家在 Stripe、Creem、PayPal、DodoPayments、微信支付、支付宝或 Waffo 付款,付款确认后订单标记为已付款。

同一时间只有一个支付服务商处于启用状态。微信支付和支付宝例外。启用且配置齐全后,所有人民币计价的套餐都由它们收款:优先微信支付,微信支付未就绪时走支付宝;其它币种仍由当前服务商收款。你在后台接入服务商、注册 webhook,再完成一笔测试付款。支付功能不需要任何环境变量。

准备工作

  • 服务商账号及其 API 凭据。微信支付使用正式商户号,其他厂商(包括支付宝沙箱)先使用测试环境。
  • 部署后的公网地址。本地 127.0.0.1 收不到 webhook。
  • 拥有 config.read 和 config.write 的管理员账号。
  • /admin/plans 中至少有一个上架的套餐,见管理定价套餐。

在支付服务商创建测试资源

厂商适用场景
Stripe订阅结账、门户与退款
Creem托管结账,请先核对适配器兼容性
PayPal使用沙箱买家验证一次性付款
DodoPayments绑定厂商商品 ID 的托管结账
微信支付人民币一次性扫码收款
支付宝人民币一次性付款,跳转支付宝电脑网站收银台,支持退款
Waffo代收代缴销售税的托管结账(merchant of record),支持一次性和订阅套餐

填写服务商配置

打开支付配置

进入 设置 → 支付配置(/admin/config/payment)。每个服务商卡片会显示 缺少密钥 或 已配置,以及 Webhook 未配置 或 Webhook 已配置。点选要配置的服务商。

填写 Checkout 跳转

在 Checkout 跳转 中填写:

  • 成功 URL:付款确认后买家的落地页,例如 https://<你的域名>/app/billing。
  • 取消 URL:其他情况下的落地页,例如 https://<你的域名>/pricing。
  • API base URL:调用的服务商 API 地址。Creem、PayPal 和 DodoPayments 默认分别是 https://api.creem.io、https://api-m.sandbox.paypal.com 和 https://test.dodopayments.com,在测试和正式环境之间切换时修改这里。Stripe 不使用这个字段,测试环境还是正式环境由密钥决定。微信支付默认 https://api.mch.weixin.qq.com,只有这一个环境。支付宝默认指向沙箱网关;Waffo 只有 https://api.waffo.ai 一个地址,测试还是正式由密钥决定。
  • 结账时允许使用优惠码:见提供优惠码。

买家在到达成功 URL 之前会先回到你自己的域名,所以这里要填公网域名。

填入 API 凭据

在 密钥配置 中填写所选服务商的字段:

按上方对应厂商指南中的字段对照表填写。

密钥字段保存后不会再显示,留空保存会保留已保存的值。

注册 webhook

按上表中对应厂商的指南登记 HTTPS 端点、勾选事件并保存验签凭据。微信支付和支付宝在每次下单时传入通知地址。

启用服务商

勾选 设为当前支付 provider,点击 保存 provider。卡片上会出现 启用中 和 Webhook 已配置,运行状态 面板显示当前服务商。取消勾选并保存当前服务商后,没有任何服务商处于启用状态。不勾选保存其它服务商,当前服务商保持不变。勾选微信支付或支付宝会为人民币套餐启用该渠道,只有在没有其它当前服务商时才把它设为当前服务商。能力 面板会显示该服务商是否支持客户门户、订阅、退款和优惠码。

提供优惠码

在 Checkout 跳转 中打开 结账时允许使用优惠码,点击 保存 provider。这个开关只存一份(payment.checkout.allow_promotion_codes),默认关闭。打开后 Stripe 和 Waffo 的托管结账页会显示优惠码输入框;其它服务商忽略此开关,能力 面板中优惠码显示为不支持。优惠码本身在服务商后台创建。

账单的实付金额取自签名 webhook 或服务端确认给出的实收金额,应付金额仍是套餐原价。退回买家实付的全部金额即为全额退款。

验证

用普通用户登录,打开 /pricing,用服务商的测试卡或沙盒买家购买一个方案,然后检查:

  • 安全 → Webhooks(/admin/billing-webhooks)中出现该服务商的事件,签名校验通过。
  • 商业化 → 订单(/admin/orders)中订单状态为已付款。
  • 买家的 /app/billing 中出现发票,方案附带的积分出现在 /app/credits。积分由内置的履约插件在订单提交后发放。如果积分没有到账,到 /admin/audit 查找 billing.fulfilment.failed 记录。
  • 使用微信支付时,买家跳转到 /app/billing/pay/<order>,用微信扫码付款,付款后几秒内页面跳到成功 URL。
  • 使用支付宝时,买家跳转到支付宝收银台,付款后经 /api/billing/callback/alipay 回到站点,服务端先查单再把订单标记为已付款。

pnpm validate:billing 会检查订单状态机、未配置路径和签名处理。pnpm validate:wechat-pay 在不调用微信支付的前提下检查签名、解密、金额核对和按币种选渠道。pnpm validate:alipay、pnpm validate:waffo 和 pnpm validate:promotion-codes 分别对支付宝、Waffo 和折后金额做同样的检查。要真实调用沙盒,在保存好服务商凭据后运行 pnpm validate:external。

常见问题

买家从定价页被带到 /system/payment-failed

结账被拒绝。到 Webhooks 查看 checkout.not_configured 或 checkout.failed 事件及错误信息,然后在 支付配置 中补全凭据。DodoPayments 还需要产品 id。

webhook 签名校验失败

确认保存的 Webhook secret 是该端点的签名密钥,DodoPayments 要保存完整的 whsec_…。Stripe 和 DodoPayments 会拒绝与服务器时间相差超过 300 秒的事件,请检查服务器时间。改写请求体的代理也会导致签名失效。

买家付款后落到不存在的页面

在默认值变更之前初始化的数据库中,成功 URL 可能仍是没有对应路由的 http://127.0.0.1:5173/app/billing/orders。把它改为存在的页面,例如 https://<你的域名>/app/billing。

微信支付或支付宝下单被拒绝,原因是 provider_unsupported

微信支付和支付宝只收人民币一次性付款。在 /admin/plans 把套餐的币种设为 CNY、计费周期设为一次性或终身,或改用其它服务商收款。

订单一直是待付款

webhook 没有到达,买家也没有回到网站。确认端点已注册且订阅了正确的事件,然后在服务商后台重新发送事件。

参考

下一步