接入支付服务商
完成后,买家在 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 之前会先回到你自己的域名,所以这里要填公网域名。
注册 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 没有到达,买家也没有回到网站。确认端点已注册且订阅了正确的事件,然后在服务商后台重新发送事件。