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_ 开头。

选择事件

勾选下面三个事件,然后继续:

事件在这里的作用
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 已配置。

Stripe 支付配置的密钥字段

验证

  1. 用普通用户登录,打开 /pricing,购买一个套餐。预期结果:跳转到 Stripe 的 Checkout 页面。
  2. 用测试卡 4242 4242 4242 4242 付款,有效期填任意未来日期,CVC 任意(见 Stripe 测试卡)。预期结果:页面回到 成功 URL。回跳途中,/api/billing/callback/stripe 会先向 Stripe 确认该会话已付款,再把订单标记为已付款。
  3. 打开 安全 → Webhooks(/admin/billing-webhooks)。预期结果:有一条来自 Stripe 的 checkout.session.completed 事件,签名校验通过。
  4. 打开 商业化 → 订单(/admin/orders)。预期结果:订单为已付款,买家在 /app/billing 看到发票,在 /app/credits 看到套餐附带的积分。

要测试退款,打开这笔订单并创建退款,见管理订单、退款和订阅。

切换到正式环境

  1. 打开 dashboard.stripe.com/apikeys(地址里没有 /test/),复制正式的 Secret key(sk_live_…)。
  2. 打开 dashboard.stripe.com/workbench/webhooks,重新添加目标,地址和事件与之前相同。复制它新的签名密钥;测试模式的密钥无法校验正式事件。
  3. 把这两项保存到 /admin/config/payment,并确认 成功 URL 和 取消 URL 指向正式域名。
  4. 真实购买一次,再退款。

常见问题

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 付款,通常是结账没有完成。只有已付款的订单才能退款。

下一步