Stripe
通过 Stripe Checkout 收取一次性付款和按月、按年续费的订阅,支持退款和客户门户。
Stripe 是适配最完整的支付服务商。买家在 Stripe 托管的 Checkout 页面付款,价格取自你的套餐,所以不需要在 Stripe 里创建产品或价格。
支持的能力
| 能力 | 是否支持 | 说明 |
|---|---|---|
| 一次性付款 | 支持 | 计费周期为一次性或终身的套餐 |
| 订阅 | 支持 | 按月或按年续费的套餐 |
| 在后台退款 | 支持 | 全额或部分退款,在 /admin/orders 操作 |
| 客户门户 | 支持 | 买家从 /app/billing/portal 打开 |
| 币种 | 套餐的币种 | 按套餐上保存的币种原样发给 Stripe |
续费由 Stripe 扣款。这个适配器只结算订阅的第一笔付款,不处理 Stripe 的 invoice.* 事件,所以续费不会生成新订单,也不会再次发放套餐附带的积分。
准备工作
你需要准备
- 一个 Stripe 账号。整个流程跑通之前使用测试模式。
- 站点已部署到公网 HTTPS 地址。Stripe 无法把 webhook 发到
127.0.0.1。 - 拥有
config.read和config.write的管理员账号。 /admin/plans中至少有一个上架的套餐,见管理定价套餐。
完成后你会得到
- 保存在后台的密钥(
sk_test_…)和 webhook 签名密钥(whsec_…)。 - Stripe 成为当前支付服务商,并有一笔测试购买结算为已付款订单。
在 Stripe 完成准备
下面这些步骤在 Stripe Dashboard 里完成。
打开测试环境的 API 密钥页
打开 dashboard.stripe.com/test/apikeys。地址里的 /test/ 表示你在测试模式。
测试密钥和正式密钥不能混用
测试密钥只能搭配测试环境的 webhook 签名密钥,正式密钥只能搭配正式环境的。先在测试模式把整个流程跑通,再去正式模式创建任何东西。
复制密钥
在 Standard keys 下,点击 Secret key 一行的 Reveal test key,复制密钥。它以 sk_test_ 开头。
打开 webhook 页面
打开 dashboard.stripe.com/test/workbench/webhooks,点击 Add destination。
选择事件
勾选下面三个事件,然后继续:
| 事件 | 在这里的作用 |
|---|---|
checkout.session.completed | 把订单标记为已付款,并保存订阅 id |
checkout.session.async_payment_failed | 把订单标记为失败 |
checkout.session.expired | 把订单标记为已取消 |
这三个结账会话事件覆盖表中的状态变化。
填写端点地址
目标类型选择 Webhook endpoint,把 Endpoint URL 设为:
https://<你的域名>/api/billing/webhook/stripe点击 Create destination。
复制签名密钥
在这个目标的详情页里,显示并复制 Signing secret。它以 whsec_ 开头。
每个目标一个密钥
每个目标有自己的签名密钥。从别的目标或 Stripe CLI 复制来的密钥无法校验这里的事件。
启用客户门户(可选)
如果要让买家自己管理银行卡和取消订阅,打开 dashboard.stripe.com/test/settings/billing/portal,点击 Activate test link。如果有多套门户配置,复制要使用的那一套的 id,它以 bpc_ 开头。
Stripe 官方说明:Receive Stripe events in your webhook endpoint 和 Activate the customer portal。
填写后台配置
回到 Kernlift 后台。
打开支付配置
进入 设置 → 支付配置(/admin/config/payment),点选 Stripe 卡片。
填写跳转地址
在 Checkout 跳转 中,把 成功 URL 设为付款后买家的落地页,例如 https://<你的域名>/app/billing;把 取消 URL 设为其他情况下的落地页,例如 https://<你的域名>/pricing。API base URL 保持不动,Stripe 不使用它。
粘贴从 Stripe 复制的值
在 密钥配置 中,把每个值粘贴到对应的字段:
| Stripe 里的名称 | 后台表单里的字段 |
|---|---|
Secret key(sk_test_…) | Secret key |
Signing secret(whsec_…) | Webhook secret |
门户配置 id(bpc_…),可选 | Portal configuration ID |
密钥字段保存后不会再显示,留空保存会保留已保存的值。
把 Stripe 设为当前服务商
勾选 设为当前支付 provider,点击 保存 provider。卡片上会显示 启用中、已配置 和 Webhook 已配置。
验证
- 用普通用户登录,打开
/pricing,购买一个套餐。预期结果:跳转到 Stripe 的 Checkout 页面。 - 用测试卡
4242 4242 4242 4242付款,有效期填任意未来日期,CVC 任意(见 Stripe 测试卡)。预期结果:页面回到 成功 URL。回跳途中,/api/billing/callback/stripe会先向 Stripe 确认该会话已付款,再把订单标记为已付款。 - 打开 安全 → Webhooks(
/admin/billing-webhooks)。预期结果:有一条来自 Stripe 的checkout.session.completed事件,签名校验通过。 - 打开 商业化 → 订单(
/admin/orders)。预期结果:订单为已付款,买家在/app/billing看到发票,在/app/credits看到套餐附带的积分。
要测试退款,打开这笔订单并创建退款,见管理订单、退款和订阅。
切换到正式环境
- 打开 dashboard.stripe.com/apikeys(地址里没有
/test/),复制正式的 Secret key(sk_live_…)。 - 打开 dashboard.stripe.com/workbench/webhooks,重新添加目标,地址和事件与之前相同。复制它新的签名密钥;测试模式的密钥无法校验正式事件。
- 把这两项保存到
/admin/config/payment,并确认 成功 URL 和 取消 URL 指向正式域名。 - 真实购买一次,再退款。
常见问题
webhook 记录显示签名校验失败
保存的 Webhook secret 不是这个目标的签名密钥,或者来自另一种模式。事件时间戳与服务器时钟相差超过 300 秒时也会被拒绝,请检查服务器时间。改写请求体的代理同样会让签名失效。
付款成功后订单一直是待付款
经 /api/billing/callback/stripe 的回跳和 webhook 都没有到达站点。确认目标地址是公网地址,并且勾选了 checkout.session.completed,然后在 Stripe Dashboard 里重新发送事件。
结账被拒绝,原因是 plan_interval_mismatch
套餐按订阅计费,但周期不是月或年;或者按一次性计费,周期却是月或年。到 /admin/plans 重新保存这个套餐,表单会让两者保持一致。
退款失败,提示 "requires a PaymentIntent or Charge id"
这笔订单背后没有 Stripe 付款,通常是结账没有完成。只有已付款的订单才能退款。