Stripe 产品与支付配置

这篇文章系统复盘了我在实际项目中配置 Stripe 产品体系的完整流程，重点覆盖 私钥管理、Webhook 事件配置、产品与价格创建、本地调试与沙盒测试。内容以真实操作顺序展开，保留所有关键字段、事件名称、测试卡号与配置细节，适合第一次接入 Stripe、或者对订阅/一次性收费逻辑不够熟的人，直接按步骤落地，不容易踩坑。

主要围绕 Stripe 后台的基础配置，不涉及代码实现，重点解决三个问题：

私钥如何正确使用
Webhook 怎么配置、监听哪些事件
产品和价格如何创建，才能被代码正确识别

一、Stripe 私钥的配置方式

1. 私钥在哪里找

进入 Stripe 后台后：

在页面左下角找到「开发人员」
进入后可以看到 API Keys

这里会有两类 key：

Publishable key（前端用）
Secret key（私钥，后端用）

2. 私钥的正确使用方式

不要把私钥写死在代码里。

标准做法是：

复制 Secret key
配置到环境变量中
由后端在运行时读取

这样做的目的只有一个： 避免私钥泄露，一旦代码仓库公开就翻车。

二、Webhook 的配置流程

Webhook 是 Stripe 支付体系里非常关键的一环，所有支付成功、订阅变化，本质上都靠它驱动。

1. 进入 Webhook 配置入口

路径是：

Stripe 后台
左下角「开发人员」
Webhooks

点击进入后，选择 添加事件 / 创建 Webhook 端点

2. 需要监听的事件

在创建 Webhook 时，需要手动筛选你要监听的事件。我这里使用的是：

invoice.paid
checkout.session.completed
customer.subscription.created
customer.subscription.updated
customer.subscription.deleted

这些事件基本覆盖了：

一次性支付完成
订阅创建
订阅更新
订阅取消

3. 创建 Webhook 端点

创建时需要填写两个核心信息：

Webhook 名称（自己识别用）
Webhook URL（后端提供的接口地址）

确认后创建。

4. 保存 Webhook 密钥

Webhook 创建完成后，Stripe 会生成一个：

Webhook Signing Secret

这个值非常重要：

用于校验请求是否真的来自 Stripe
防止被伪造请求攻击

同样的处理方式：

复制
存入环境变量
后端校验时使用

三、创建 Stripe 产品与价格

Webhook 配好后，下一步是创建可以被用户购买的产品。

1. 创建产品入口

在 Stripe 后台：

进入「产品目录」
选择「创建产品」

2. 产品的关键配置项

创建产品时，主要需要关注以下几个点：

产品名称
收费类型
- 订阅（Subscription）
- 一次性收费（One-time）
币种（非常重要，后期不好改）
收费周期
- 按月
- 按年

这些选项会直接决定你后端逻辑怎么写。

3. Price ID 的作用

产品创建完成后，Stripe 会生成一个：

Price ID

这个 ID 才是真正用于：

创建 Checkout Session
创建订阅
发起支付

标准做法：

复制 Price ID
放入环境变量
不要在代码里硬编码

四、本地开发与测试方案

1. Stripe CLI 本地转发

在本地开发时，Webhook 最大的问题是：

Stripe 无法直接访问你的 localhost

解决方案是：

使用 Stripe CLI
将 Stripe 的 Webhook 事件转发到本地接口

这样可以完整模拟真实支付回调流程。

五、Stripe 沙盒环境与测试卡号

Stripe 提供了完整的 测试环境（Sandbox），可以用虚拟卡反复测试支付流程。

官方测试文档： https://docs.stripe.com/testing

常用测试卡号整理

测试卡号	场景
4242 4242 4242 4242	成功支付
4000 0000 0000 3220	需要 3D 安全认证
4000 0000 0000 9995	资金不足，支付失败

这些卡号可以直接在测试环境使用，不会产生真实扣款。

六、整体配置逻辑总结

整个 Stripe 的配置顺下来，本质是三件事：

私钥、Webhook 密钥全部放环境变量
Webhook 事件选全，不然后期一定补
Price ID 才是代码真正依赖的核心字段

只要这三点没问题，后面的代码接入、订阅管理、支付状态同步，都会顺很多。