Stripe 收款
用 Keygate 接入 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 价格字段里。
- 订阅方案需要一个周期性价格,按月或按年。
- 按席位销售的方案需要一个单个席位的周期性价格,订阅的数量就是席位数。
- 永久方案需要一个一次性价格。
- 带更新期的永久方案可以再加一个一次性价格,用于续期。详见更新期。
按席位销售订阅
订阅方案可以按席位销售:买家自己决定买几个席位,许可证拥有这些席位对应的额度。创建方案时打开按席位销售。这个设置之后不能再改,如果想换一种卖法,请新建一个方案。
- 最少席位数和最多席位数决定买家可以选择的范围,最多可以设到 10,000。
- 在 SaaS 或混合型产品上,席位就是许可证上的人数,包括所有者在内:五个席位就是所有者加四名成员。详见团队与席位。
- 最大激活数会变成每席位设备数(浮动方案则是每席位并发数),再乘以席位数。在混合型产品上,这些设备由许可证上的所有人共用;在桌面产品上,席位数只用来乘设备数。
- 只有订阅方案可以按席位销售。
许可证会记录已付费的席位数,在后台的许可证上显示为已购席位。对由 Stripe 计费的许可证,这个数字始终来自订阅:每次变更后 Keygate 都会从 Stripe 读回,后台里不能修改。对没有任何计费的按席位许可证,例如你在后台签发的许可证,席位数由你在许可证上自己设置。方案设置的更多细节见按席位定价。
引导客户结账
每个方案都有一个结账链接,在后台的方案页面里可以看到。把它挂到定价页的购买按钮上:
https://licenses.example.com/pay/k3x9q2mf这个链接会为该方案新建一个 Stripe Checkout 会话,客户付完款后会跳回你 Keygate 地址下的确认页面。
免费方案没有 Stripe 价格,结账链接也就没有东西可卖。如果方案开启了自助注册,这个链接会打开一个领取表单,访客验证邮箱后即可领取一个免费许可证。详见自助注册。
你也可以用 Stripe Payment Links 或自己集成的 Checkout 来卖。Keygate 会根据客户买的价格找到使用这个价格的方案,所以这些渠道的订单同样会生成许可证。
在结账时选择席位数
对按席位销售的方案,Stripe Checkout 打开时默认是方案的最少席位数,买家可以在 Stripe 的页面上在方案范围内修改。如果想从别的数量开始,比如访客在你的定价页上选好的团队人数,在链接后加上 quantity:
https://licenses.example.com/pay/k3x9q2mf?quantity=5- 超出方案范围的数量会返回错误,不会打开结账页。
- 最少和最多席位数相同时,买家无法修改数量。
- 不按席位销售的方案不接受大于 1 的
quantity,结账时始终只卖一张许可证。
付款之后
- Stripe 通知 Keygate 结账已完成。
- Keygate 在所购方案下,用客户的邮箱创建许可证,席位数与订阅计费的数量一致。
- 客户收到一封带密钥的邮件;如果产品设置了下载链接,邮件里还会有下载按钮。
- 如果你订阅了 license.created 事件,你的 webhook 会收到它。
漏掉一次 webhook 不会丢单:Stripe 会重新发送;客户打开确认页面时,Keygate 也会确认这笔购买; 另外它每五分钟检查一次 Stripe,补上最近没收到的结账。不管有几条路径上报同一次结账,都只会创建一个许可证。
客户门户
客户用邮箱登录 BASE_URL/portal 上的门户,可以看到自己的许可证和密钥,并且可以:
- 释放不再使用的设备;
- 把订阅换到别的方案,比如从月付换成年付;在按席位销售的方案上调整席位数,详见更换方案与调整席位;
- 把免费方案上的许可证升级为付费方案,密钥保持不变,详见免费许可证升级;
- 取消订阅,可以在周期结束时取消,也可以立即取消;
- 通过 Stripe 的账单门户下载发票、更新银行卡;
- 为永久许可证续期更新期。
账单相关的操作只有许可证所有者能用,成员看不到。大部分本来会变成工单发到你邮箱的问题,客户在这里就能自己解决。门户的其他功能见客户门户页面。
更换方案与调整席位
这一节说明客户如何在门户里修改已有的 Stripe 订阅,以及每种变更怎样计费。用更换方案可以换到同一产品的另一个订阅方案;用调整席位可以修改按席位销售方案的席位数。换到按席位销售的方案时,也会要求选择席位数。
在任何变更生效之前,客户会先看到这次变更的费用,由 Stripe 计算,包含税费、折扣和账户余额,确认后才会提交。显示的价格一小时内有效;超过一小时,或者订阅在此期间发生了变化,客户需要重新查看。之后 Keygate 向 Stripe 提交变更,许可证按 Stripe 返回的订阅取得新的方案和席位。
增加席位或换到更大的方案
不降低任何上限的变更,比如增加席位、换到功能更多的方案、从月付换成年付,会按比例计费:Stripe 立即为本周期剩余时间开出差价账单,账单付清后变更立即生效。如果变更后更便宜,差额会进入客户在 Stripe 的账户余额,用于抵扣以后的账单,变更立即生效。
- 如果付款还需要额外步骤,比如验证银行卡,门户会显示需要付款,并附上支付账单的链接。在付款之前订阅保持不变;如果到显示的日期仍未付款,这次变更会被放弃,不会收费。
- 变更在等待付款期间,客户可以在门户里取消它,或者提交另一个变更来替换它。
- Stripe 只能为部分支付方式保留待付款的变更:银行卡、电子钱包、Link、PayPal 等,不包括银行扣款。用其他方式付款的订阅,或者账单不是自动扣款的订阅,不能在门户里做这类变更,客户会被提示换成银行卡或联系你。
减少席位或换到更小的方案
减少席位数或降低设备上限的变更属于降级。降级立即生效,不按比例计费:现在不收费也不退款,本周期剩余时间不退款,下一张账单按新条款收费。
- 降级不会移除任何人,所以只要使用中的数量超过降级后的额度,就会被拒绝:许可证上的人数(包括所有者和已邀请的人)多于新席位数时返回
SEATS_IN_USE;已激活的设备多于新上限时,或者浮动方案上运行中的会话多于新上限时,返回DEVICES_IN_USE。门户会提示需要先移除什么。 - 如果降级在降低一项上限的同时提高另一项、在本周期剩余时间里反而更贵,或者换到计费周期不同的价格,就不能在门户里完成,客户会被提示联系你。
变更被拒绝的情况
- 逾期的订阅要先付清,才能变更。
- 同一个订阅一次只能进行一个变更。
- 你在 Stripe 里手动配置的订阅,比如带订阅计划(schedule)、包含多个项目或使用按量计费价格的,不能在门户里变更,客户会被提示联系你。
- 要换到的方案必须是同一产品下启用中的订阅方案,席位数必须在它的范围内。
在 Stripe 里做的变更
订阅实际计费什么,以 Stripe 为准。如果你在 Stripe 后台修改了订阅的价格或数量,许可证会在 Stripe 的下一个事件到达时跟着变:换到使用新价格的方案,并采用新的席位数。你的 webhook 会收到 plan.changed 和 license.quantity_changed,详见Webhook 事件。
如果这样做让席位数少于许可证上已有的人数,不会移除任何人:最后加入的成员会被暂停,在有空余席位之前无法使用自己的密钥。超出新上限的设备继续可用,但在释放出足够名额之前不能激活新设备。
免费许可证升级
免费方案上的许可证,无论是在后台签发的还是通过自助注册领取的,都可以升级到同一产品的付费方案,密钥不变。满足以下全部条件时,许可证所有者会在客户门户的许可证上看到升级按钮:
- 已连接 Stripe。
- 许可证所在方案没有 Stripe 价格、更新期或续期,并且这张许可证还没有由 Stripe 计费。已由 Stripe 计费的许可证请用更换方案。
- 许可证没有被暂停或吊销。已过期或已取消的许可证也可以升级,付款就是让它恢复的方式。
- 产品里有可以升级到的方案:处于启用状态、设置了 Stripe 价格、不是试用方案,并且不销售更新期。
客户选好方案后在 Stripe Checkout 付款。付款确认后,同一张许可证会换到新方案上:密钥和已激活的设备都保留,应用在下一次 verify 时就能拿到新方案的功能。之后这张许可证像其他订阅许可证一样跟随 Stripe 订阅;如果是永久方案,则永不过期,并且终身可以获得更新。你的 webhook 会收到 plan.changed,客户也会收到一封方案变更邮件。
- 升级到按席位销售的方案时,结账会为许可证上现有的每个人各准备一个席位;如果方案的最少席位数更多,则从最少席位数开始。客户可以选更多席位,但不能更少。团队人数超过方案最多席位数时无法升级,门户会返回
409 SEATS_IN_USE。这个结账打开期间(最长一小时),不能邀请新成员。升级改变了席位数时,你的 webhook 还会收到license.quantity_changed。 - 发起新的升级结账时,之前打开的升级结账会被关闭,所以客户不会为同一张许可证付两次钱。如果之前那次已经付款、还在处理中,新的请求会返回
409 UPGRADE_IN_PROGRESS。 - 如果从结账到付款之间,许可证被暂停、吊销或发生了其他变化,升级就不会生效。确认页面会提示付款正在处理,服务器日志和审计日志会记录这件事。请在 Stripe 里退款;如果是订阅方案,还要取消订阅。
- 如果在升级生效之前付款就被退款,或者订阅已经结束,确认页面会提示升级未生效。
回到免费方案
升级过的许可证在付款不再有效时,不会被吊销或取消,而是回到原来的免费方案,恢复升级前的状态、日期和席位,密钥不变。以下情况会触发:
- 在 Stripe 里全额退还了升级的款项;
- 升级对应的订阅被取消,或变成 unpaid(未付)状态;
- 逾期已满 30 天;
- 订阅周期和方案的宽限天数都已用完,仍未续费;
- 管理员对它执行了取消订阅并吊销。
如果订阅还没有结束,Keygate 会先在 Stripe 里取消它。以上每种情况都会发送带 reason 的 plan.changed,具体取值见Webhooks 页面。如果原来的免费方案在此期间被删除,就没有可以回去的方案,许可证会像普通购买一样处理。
由 Stripe 计费的试用
这一节说明通过 Stripe 销售的试用转订阅。订阅处于试用期时,许可证的状态是试用中。试用结束时,Stripe 扣款并通知结果:许可证变为有效的订阅,扣款失败则变为逾期,此后跟随订阅变化。试用结束前几天,Stripe 会发出通知,客户会收到Stripe 试用即将结束邮件。
Stripe 的通知可能在试用结束日之后过一段时间才到。Keygate 会等待它,等待时长为方案的宽限天数,即使方案没有宽限天数也至少等一天,之后每小时的检查才会让试用过期。只有 Stripe 一直没有通知时才会这样,比如它的 webhook 彻底丢失了。等待期间密钥能否继续使用,取决于方案的宽限天数:没有宽限天数时,密钥在试用结束时停用,直到 Stripe 的通知到达。
试用方案可以指定一个免费方案,让许可证在试用结束时转过去,而不是过期。这种转移只适用于没有计费的试用。由 Stripe 计费的试用由 Stripe 决定结果,不会转到回退方案;如果 Keygate 不得不让它过期,它就会过期。
续费与扣款失败
订阅续费后,许可证的到期日会顺延到新周期结束。续费前一天,客户会收到即将扣款的提醒。
扣款失败时,许可证变为逾期状态,但在 Stripe 重试扣款期间仍然可以正常使用。Keygate 会在出问题后第 1 天、第 7 天和第 14 天分别给客户发邮件。只要有一次扣款成功,许可证就恢复为有效状态,同时通知客户。
已设置取消的订阅
不会续费的订阅收到的是到期提醒,而不是续费提醒,默认在到期前 7 天、3 天和 1 天发送。天数可以在邮件设置里修改。
取消与退款
- 客户取消订阅后,许可证在已付费的周期内仍然有效,周期结束后终止。
- 全额退还当期款项时,会在 Stripe 取消订阅并吊销许可证;如果是升级过的许可证,则让它回到免费方案。退还已经结束的周期,或者 Keygate 只能通过客户对应到许可证的款项,许可证不变,只记录到审计日志;客户确实要离开的话,请在 Stripe 取消订阅。续期款项全额退款时,续上的时间会从更新期里扣回。部分退款不会改变许可证,只会记录到审计日志。
- 争议败诉按全额退款处理,不论争议的是哪个周期:订阅会被取消,避免再从同一张卡扣款;许可证被吊销,升级过的则回到免费方案。银行扣款(SEPA、ACH、Bacs)的争议一提出就是终局,提出时就会处理。还在进行中或胜诉的争议不会改变任何东西。
- 结账时延迟到账的付款(SEPA、ACH)失败,不会开出许可证,Stripe 为它建的订阅也会被取消。
- 后台许可证上的取消订阅并吊销会先在 Stripe 取消订阅,再吊销许可证;升级过的许可证则回到免费方案。它不会退款,钱需要到 Stripe 后台退还。如果 Stripe 没有确认取消,许可证保持不变,后台会给出提示。一次性购买没有可取消的订阅,请改用吊销。
- 单独的吊销不会动 Stripe:对订阅许可证来说,客户会继续被扣款,而许可证一直是吊销状态。订阅许可证请用取消订阅并吊销。
后台里由 Stripe 计费的许可证
许可证绑定 Stripe 订阅期间,它的方案、席位和到期日都由 Stripe 决定。后台不会绕过 Stripe 修改它们,否则 Stripe 会继续按旧条款扣款:
- 许可证上的更换方案会返回
STRIPE_MANAGED。请在客户门户里更换方案,门户会同时修改 Stripe 里的订阅;或者在 Stripe 后台修改订阅,让许可证跟着变。 - 按席位许可证的席位数显示为由 Stripe 订阅决定,不能修改,只能在门户或 Stripe 里调整。
- 到期日同样不能修改,由续费来顺延。
如果想让许可证脱离 Stripe 管理,比如把它换到你用其他方式销售的方案,先在 Stripe 里取消订阅,再对许可证执行解绑。Keygate 会先询问 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 通过方案的结账链接下一单,就能看到许可证出现在后台里。
常见问题
怎样让买家带着指定的席位数进入结账?
在方案的结账链接后加上 quantity,例如 https://licenses.example.com/pay/k3x9q2mf?quantity=5。这个数必须在方案的最少和最多席位数之间,否则链接会返回错误,不会打开结账页。在 Stripe 的页面上,买家仍可以在这个范围内修改数量,除非最少和最多席位数相同。
在客户门户里调整席位或更换方案,会按比例计费吗?
增加席位或换到更大的方案会按比例计费:Stripe 立即为本周期剩余时间开出差价账单,账单付清后变更生效。减少席位或降低设备上限的变更立即生效,不按比例计费:现在不收费也不退款,下一张账单按新条款收费。
为什么客户无法减少席位?
Keygate 不会为了让降级生效而移除任何人或设备。只要许可证上的人数(包括所有者和已邀请的人)多于新的席位数,门户就会返回 SEATS_IN_USE;已激活的设备多于新上限时,返回 DEVICES_IN_USE。客户需要先移除成员、取消邀请或释放设备,再减少席位。逾期的订阅要先付清欠款,才能做任何变更。
能在后台修改由 Stripe 计费的许可证的方案或席位吗?
不能。许可证绑定 Stripe 订阅期间,它的方案、席位和到期日都由 Stripe 决定,后台会返回 STRIPE_MANAGED。请在客户门户里更换方案或调整席位,门户会同时修改 Stripe 里的订阅;或者直接在 Stripe 后台修改订阅,许可证会跟着变。如果想改由 Keygate 管理这张许可证,先在 Stripe 里取消订阅,再对许可证执行解绑。
Stripe 试用结束时,许可证会怎样?
Stripe 扣款并通知结果,许可证变为有效的订阅;扣款失败则变为逾期。Keygate 会等待这个通知,等待时长为方案的宽限天数,至少一天,之后每小时的检查才会让试用过期。由 Stripe 计费的试用不会转到试用方案设定的回退方案。
最后更新 2026年10月26日