For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /zh-tw/docs/web/stripe-payments.md (or send Accept: text/markdown).

新增 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 的原因。

建立 Stripe 賬戶

1. 開啟 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。