> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

# 添加 Stripe 支付

创建免费的 Stripe 账户、带周期价格的产品、密钥，以及结账后发放权益的签名 webhook。

## 初学者演练

前提条件：应用在本地运行（5 分钟启动）以及已迁移、能存真实账户的数据库（设置数据库）。你需要一个邮箱来注册 Stripe 账户——不需要卡，也不会扣款。本指南的一切都在测试模式下进行：假钱、测试卡号、上线前无限重试。

快速术语：测试模式是 Stripe 的沙盒——仪表板上的 Test mode 开关在你关掉之前让每个密钥、产品和付款都保持假的。密钥（`sk_test_…`）是服务器对 Stripe 的密码。带价格的产品是客户购买的东西；price id（`price_…`）在代码中指名它。Webhook 是付款成功或订阅变更时 Stripe 对服务器的回调；签名密钥（`whsec_…`）证明调用确实来自 Stripe。

你要创建的：一个 Stripe 账户、一个带周期价格的产品、一个 API 密钥和一个 webhook 端点——大约二十分钟。Stripe 自己托管结账页；套件在服务端创建会话并跳转，所以不需要可公开的浏览器密钥。

记住边界：本指南只销售 Web 订阅。iOS/Android 应用内购买必须走 Apple 和 Google 的计费——绝不能走 Stripe Checkout——这就是移动端用 RevenueCat 的原因。

[设置数据库](https://supastack.dev/zh/docs/web/setup-database.md)

[为移动端购买设置 RevenueCat](https://supastack.dev/zh/docs/mobile/revenuecat.md)


## 创建 Stripe 账户

1. 打开 [stripe.com](https://stripe.com) → Start now，用你的邮箱注册。

2. 引导流程会问你的业务情况——测试模式下每个问题都可以跳过，照样使用完整沙盒；只在准备收真实付款前完成激活。

预期结果：进入仪表板，顶栏可见 Test mode 开关。下面的一切都保持它开启——正式密钥稍后放进生产密钥存储，绝不放进笔记本上的 env 文件。


## 复制 API 密钥

1. 在仪表板打开 Developers → API keys。

2. 你会看到两个测试密钥：Publishable key `pk_test_…` 和被打码的 Secret key。点击密钥旁的 Reveal test key，复制 `sk_test_…` 值。

套件只需要密钥：结账会话在服务端创建，用户被跳转到 Stripe 托管的页面，所以可公开密钥不会进 env 变量。你以后做的产品若引入 Stripe.js，才会在客户端用到可公开密钥；套件的计费流程不用它。

`sk_test_…` 是沙盒账户的完整凭据：它放在 `apps/web/.env.local` 或密钥存储中，绝不进 `NEXT_PUBLIC_`/`EXPO_PUBLIC_` 变量，也绝不进 Git。


## 创建产品和价格

1. 打开 Product catalog → Add product。

2. 用你的方案命名——`Pro` 与套件自带的方案一致——给出价格并选择 Recurring（如每月）：套件的结账创建订阅模式会话，需要周期价格而不是一次性价格。

3. 保存，打开产品，复制 price id——以 `price_…` 开头（不是 `prod_…`，那是产品 ID）。

自带的 `pro` 方案已经显示 Monthly/Yearly 切换：月付用 `STRIPE_PRICE_ID` 结账，年付选项需要 `STRIPE_PRICE_ID_PRO_YEARLY` 中的第二个周期价格——没有它年付结账会以 `price-unconfigured` 失败。方案名、金额以及购买授予什么，都在 `apps/web/src/product-plans.ts` 中修改——Stripe 管钱的一侧，方案文件管权益的一侧。


## 添加 webhook 端点

webhook 才是真正授予访问权的东西：套件只在签名的 Stripe 事件到达后才翻转权益，所以仅靠结账跳转什么也证明不了。

1. 打开 Developers → Webhooks → Add endpoint。

2. Endpoint URL：你的公开 URL 加 `/api/billing/webhook`——如 `https://yourdomain.com/api/billing/webhook`。其他计费提供商在该目录下各有自己的路径；Stripe 的接收器在根部。

3. 在 Select events 中选择套件处理的事件：`checkout.session.completed`、`checkout.session.async_payment_succeeded`、`checkout.session.async_payment_failed`、`invoice.paid`、`invoice.payment_failed`、`customer.subscription.created`、`customer.subscription.updated` 和 `customer.subscription.deleted`。

4. 创建端点，打开它的页面，在 Signing secret 下点击 Reveal，复制 `whsec_…` 值——每个端点有自己的密钥。

本地开发收不到 Stripe 的服务器，所以改用 Stripe CLI：先 `stripe login` 一次，然后在第二个终端运行 `stripe listen --forward-to localhost:3000/api/billing/webhook`。它会打印一个临时 `whsec_…`——`stripe listen` 运行期间，`.env.local` 里放的是这个值，而不是仪表板上的值。


## 把值加入应用

在 `apps/web/.env.local` 中设置下面几行。`BILLING_PROVIDER=stripe` 选择适配器；其余三个分别是密钥、价格和签名密钥。缺少任何一个就启用提供商会让启动失败并指出变量名。

三个 `STRIPE_*` 值都仅限服务端——绝不 `NEXT_PUBLIC_`/`EXPO_PUBLIC_`，绝不提交；生产环境通过托管方的密钥管理器提供（部署指南介绍 Secret Manager）。编辑后重启开发服务器。

```
# apps/web/.env.local
BILLING_PROVIDER=stripe
STRIPE_SECRET_KEY=sk_test_…
STRIPE_PRICE_ID=price_…
STRIPE_WEBHOOK_SECRET=whsec_…   # `stripe listen` value locally; endpoint signing secret in production
# STRIPE_PRICE_ID_PRO_YEARLY=price_…   # required for the shipped Yearly toggle
```


## 验证与排错

启动 `stripe listen --forward-to localhost:3000/api/billing/webhook` 并保持运行，重启开发服务器，然后打开 `/billing`，选择 Pro 方案，用测试卡 `4242 4242 4242 4242`、未来的有效期和任意 CVC 完成 Stripe 托管的结账。

预期结果：应用回到 `/billing?checkout=success`，工作区权益翻转为激活——listen 终端记录了送达的事件，仪表板的 Developers → Webhooks → 你的端点显示绿色送达。

想不点结账就测试接收器，`stripe trigger checkout.session.completed` 会通过 listen 转发器发一个合成事件。

常见失败：每次送达都 400 表示签名密钥与该端点不匹配——为正确的端点重新复制 `whsec_…` 并更新 env；毫无动静表示 `BILLING_PROVIDER` 仍是 `local`；测试配置里混进 `sk_live_` 密钥表示复制了错误模式的密钥——测试与正式严格分开。

套件也为 Lemon Squeezy、Creem、Polar、Whop、Paddle、Dodo 和 PayPal 提供同样的单合同适配器——流程相同，只是控制台和 env 名不同——而移动端购买始终走 RevenueCat，不走 Stripe。

[比较计费提供商](https://supastack.dev/zh/docs/web/setup-payments.md)

[接下来添加 Resend 邮件](https://supastack.dev/zh/docs/web/resend-email.md)

[移动端购买使用 RevenueCat](https://supastack.dev/zh/docs/mobile/revenuecat.md)


如果你想继续完成设置，可以阅读《[添加 Resend 邮件](https://supastack.dev/zh/docs/web/resend-email.md)》。


## 下一篇

[添加 Resend 邮件](https://supastack.dev/zh/docs/web/resend-email.md)