Stripe 收款

接入 Stripe 后，卖许可证不需要自己写任何代码。客户在 Stripe Checkout 付款，Keygate 创建许可证并把密钥发到客户邮箱。之后许可证跟着订阅走：续费时自动延期，扣款失败会发提醒，取消订阅后在合适的时间点终止。

连接 Stripe#

从 Stripe 后台复制 secret key，填到 .env 里，然后重启 Keygate：

STRIPE_SECRET_KEY=sk_live_...

Keygate 启动时会自动在 Stripe 注册自己的 webhook 端点，地址是 BASE_URL/api/v1/webhook/stripe，并保存签名密钥，不需要你手动创建 webhook。Stripe 必须能访问到这个地址，所以 BASE_URL 要设成公网可访问的 HTTPS 地址；如果要在自己电脑上测试，参考下面的本地开发。

用测试密钥（sk_test_...）时，这套部署处于测试模式，只接受测试事件。正式上线时，要么另起一套部署，要么换成正式密钥。

关联套餐与价格#

照常在 Stripe 里创建产品和价格。然后在 Keygate 里逐个打开套餐，把对应的价格 ID（price_...）粘贴到 Stripe 价格字段里。

• 订阅套餐需要一个周期性价格，按月或按年。
• 永久套餐需要一个一次性价格。
• 带更新期的永久套餐可以再加一个一次性价格，用于续期。详见更新期。

引导客户结账#

每个套餐都有一个结账链接，在后台的套餐页面里可以看到。把它挂到定价页的购买按钮上：

https://licenses.example.com/pay/k3x9q2mf

这个链接会为该套餐新建一个 Stripe Checkout 会话，客户付完款后会跳回你 Keygate 地址下的确认页面。

你也可以用 Stripe Payment Links 或自己集成的 Checkout 来卖。Keygate 会根据客户买的价格找到使用这个价格的套餐，所以这些渠道的订单同样会生成许可证。

付款之后#

1. Stripe 通知 Keygate 结账已完成。
2. Keygate 在所购套餐下，用客户的邮箱创建许可证。
3. 客户收到一封带密钥的邮件；如果产品设置了下载链接，邮件里还会有下载按钮。
4. 如果你订阅了 license.created 事件，你的 webhook 会收到它。

漏掉一次 webhook 不会丢单：Stripe 会重新发送；客户打开确认页面时，Keygate 也会确认这笔购买； 另外它每五分钟检查一次 Stripe，补上最近没收到的结账。不管有几条路径上报同一次结账，都只会创建一个许可证。

客户门户#

客户用邮箱登录 BASE_URL/portal 上的门户，可以看到自己的许可证和密钥，并且可以：

• 释放不再使用的设备；
• 切换套餐，比如从月付换成年付，差价由 Stripe 计算；
• 取消订阅；
• 通过 Stripe 的账单门户下载发票、更新银行卡；
• 为永久许可证续期更新期。

大部分本来会变成工单发到你邮箱的问题，客户在这里就能自己解决。

续费与扣款失败#

订阅续费后，许可证的到期日会顺延到新周期结束。续费前一天，客户会收到即将扣款的提醒。

扣款失败时，许可证变为逾期状态，但在 Stripe 重试扣款期间仍然可以正常使用。Keygate 会在出问题后第 1 天、第 7 天和第 14 天分别给客户发邮件。只要有一次扣款成功，许可证就恢复为有效状态，同时通知客户。

已设置取消的订阅

不会续费的订阅收到的是到期提醒，而不是续费提醒，默认在到期前 7 天、3 天和 1 天发送。天数可以在邮件设置里修改。

取消与退款#

• 客户取消订阅后，许可证在已付费的周期内仍然有效，周期结束后终止。
• 在 Stripe 里全额退款会吊销许可证。部分退款不影响使用，只会记录到审计日志。
• 后台里许可证上的 Refund 按钮会一步完成两件事：在 Stripe 取消订阅，并吊销许可证。钱本身需要到 Stripe 后台退还。

本地开发#

Stripe 无法把 webhook 发到 localhost。可以用 Stripe CLI 转发：

stripe listen --forward-to localhost:9000/api/v1/webhook/stripe

它会输出一个以 whsec_ 开头的签名密钥。把它和测试密钥一起写进 .env，然后重启 Keygate：

STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

现在用测试卡号 4242 4242 4242 4242 通过套餐的结账链接下一单，就能看到许可证出现在后台里。