> ## 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-tw/docs/web/setup-database.md)

[為移動端購買設定 RevenueCat](https://supastack.dev/zh-tw/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-tw/docs/web/setup-payments.md)

[接下來新增 Resend 郵件](https://supastack.dev/zh-tw/docs/web/resend-email.md)

[移動端購買使用 RevenueCat](https://supastack.dev/zh-tw/docs/mobile/revenuecat.md)


如果你想繼續完成設定，可以閱讀《[新增 Resend 郵件](https://supastack.dev/zh-tw/docs/web/resend-email.md)》。


## 下一篇

[新增 Resend 郵件](https://supastack.dev/zh-tw/docs/web/resend-email.md)