如何用 Stripe 加入訂閱：計劃、試用期、Webhook 同付款失敗

用 Stripe 加入訂閱，首先喺 Stripe Dashboard 建立一個附有定期價格嘅產品，然後由你嘅伺服器將客戶帶去訂閱模式嘅 Stripe Checkout，並由 Webhook 通知你嘅 App 每次付款成功、失敗、更改或結束。將訂閱狀態儲存喺用戶或帳戶紀錄上，並根據該狀態開通存取權，唔好根據成功頁面決定。加入一個管理帳單按鈕，開啟 Stripe 託管嘅客戶入口網站，客戶就可以更換信用卡、轉換計劃同取消訂閱，而你唔需要自己建立呢啲畫面。

本指南建基於如何為你的 App 加入付款功能，該指南涵蓋一次性 Checkout、測試模式同正式上線。本文集中講定期收費嘅不同之處。Stripe 嘅詳細資料取自其 2026 年 9 月嘅官方文件。

點解訂閱比一次性付款難處理

一次性付款發生喺客戶仍然身處你嘅 App 時。訂閱則會喺客戶離開之後繼續發生：每月續期、信用卡到期、計費週期中途升級，以及於期末生效嘅取消。你嘅 App 只會透過 Webhook 得知呢啲事件。大部分訂閱相關嘅錯誤，都來自將首次付款當作全部故事。

你嘅選擇

對大部分 App 來說，Checkout 加客戶入口網站係合適嘅取捨。如果你擔心稅務處理，可以比較 Stripe、Paddle 同 Lemon Squeezy。

先喺 Stripe 規劃定價

喺 Stripe 入面，產品係你賣嘅嘢（「Pro 計劃」），而價格係你收費嘅方式（「每月 $20」、「每年 $200」）。一個產品可以有多個價格。你需要決定：

• 你提供邊幾個層級，以及每個層級喺你嘅 App 入面開通咩功能
• 按月、按年，定兩者都提供
• 會唔會提供試用期，以及需唔需要預先提供信用卡

先喺 Stripe 測試模式建立產品同價格，並記錄其價格 ID；你嘅 App 會引用呢啲 ID。如果你仲未決定定價，可以閱讀如何為 SaaS 產品定價同免費增值 vs 免費試用。

你必須處理嘅訂閱生命週期

Stripe 嘅訂閱概覽列出訂閱可以有嘅狀態。以下幾個同存取權最有關係：

將狀態儲存喺你嘅用戶或帳戶紀錄上，並根據該狀態開通存取權。每次收到相關 Webhook 時都要更新。

要處理嘅 Webhook 事件

Stripe Webhook 文件嘅處理規則仍然適用：使用原始內容驗證簽名，儘快回傳 2xx，處理重複同亂序嘅事件，並預期會有重試。什麼是 Webhook 解釋咗基本概念，而付款指南則列出詳細規則。

逐步做法

1. 喺 Stripe 測試模式建立產品同價格。
2. 加入機密：私密金鑰、價格 ID，之後再加入 Webhook 簽名金鑰。絕對唔可以放入前端程式碼。
3. 定價頁面：每個計劃嘅按鈕呼叫你嘅伺服器，由伺服器為已登入用戶建立訂閱模式嘅 Checkout 會話。傳入你嘅用戶 ID，令 Webhook 可以將付款配對到該帳戶。
4. Webhook 端點：驗證簽名並處理以上事件，每位用戶只更新一筆訂閱紀錄。
5. 根據已儲存嘅狀態同計劃開通功能，並喺伺服器上為每個受保護操作檢查，唔可以只隱藏按鈕。
6. 客戶入口網站：喺 Stripe Dashboard 設定（客戶可以轉到邊啲計劃、可唔可以取消），然後加入管理帳單按鈕，由伺服器建立入口網站會話並將客戶導向該處。
7. 付款失敗：喺 Stripe 帳單設定中，選擇重試行為，以及最後一次重試之後會發生咩事。當狀態為 past_due 時，喺 App 內顯示提示橫幅。
8. 測試整個生命週期，然後發布並登記正式 Webhook。

俾 AI 生成工具嘅提示詞

用 Stripe 加入訂閱付款。計劃：Starter（價格 ID 放喺 STRIPE_PRICE_STARTER）同 Pro（STRIPE_PRICE_PRO）。定價頁面由伺服器使用 STRIPE_SECRET_KEY 建立訂閱模式嘅 Checkout 會話，並附上已登入用戶嘅 ID。將 Stripe 客戶 ID、訂閱 ID、計劃同狀態儲存喺用戶紀錄上。絕對唔可以將私密金鑰暴露俾瀏覽器。

加入 POST /api/stripe/webhook。使用 STRIPE_WEBHOOK_SECRET 並以原始請求內容驗證簽名。處理 checkout.session.completed、invoice.paid、invoice.payment_failed、customer.subscription.updated、customer.subscription.deleted 同 customer.subscription.trial_will_end。記錄已處理嘅事件 ID，令重複事件會被忽略。用戶狀態要根據 subscription 物件更新，而唔係根據事件送達嘅次序。

喺伺服器上限制 Pro 功能：只有當狀態為 active 或 trialing，而且計劃為 Pro 時先允許使用。當狀態為 past_due 時，顯示「付款失敗，請更新信用卡」橫幅。加入一個管理帳單按鈕，為該用戶開啟 Stripe 客戶入口網站。

升級、降級同按比例計費

客戶轉換計劃時，Stripe 文件指出，更改通常會產生按比例計費（proration）：新價格會套用到目前帳單期間嘅剩餘時間。你可以預覽按比例計費，或者將其關閉。如果兩個計劃嘅週期相同，帳單日期會保持不變；由按月轉為按年，帳單日期會改為轉換當日。讓客戶喺入口網站自行更改計劃可以省去你自行編寫呢啲邏輯，但你需要喺入口網站設定中決定容許邊啲轉換。

測試清單

使用 Stripe 測試模式同測試卡，並逐一測試每個狀態：

• 新訂閱將正確計劃開通俾正確用戶
• 付款後立即關閉分頁，仍然可以開通存取權（證明 Webhook 有效）
• 註冊時信用卡被拒，唔會開通任何嘢
• 續期失敗會令帳戶進入 past_due，並顯示橫幅
• 喺入口網站更新信用卡後，狀態恢復為 active
• 升級同降級後，功能正確更改
• 於期末取消後，存取權會保留到結束日期，然後移除
• 試用用戶可以使用功能、收到提醒，並正確轉為付費或失去存取權
• 同一個 Webhook 事件發送兩次，結果冇改變

Stripe 嘅測試時鐘可以模擬時間流逝，令你唔使等一個月就可以測試續期。請查閱 Stripe 目前嘅測試文件，了解如何使用。

常見錯誤

• **喺成功頁面開通存取權。**客戶可能付咗款，但從來冇到達該頁面。應該使用 Webhook。
• **只處理首次付款。**續期、失敗同取消之後都會以事件形式到達。
• **只喺前端檢查計劃狀態。**任何人都可以直接呼叫你嘅 API。
• **意外令一位用戶擁有多個訂閱。**建立新 Checkout 會話之前，先檢查是否已有訂閱，或者將現有客戶導向入口網站。
• **首次續期失敗就撤銷存取權。**信用卡失敗通常只是小問題。一段短暫寬限期加上清楚嘅提示，可以保留客戶。
• **忘記正式環境嘅 Webhook。**測試同正式端點有唔同嘅簽名金鑰。
• **忽略稅務同退款。**上線之前要決定退款政策，並向會計師查詢你嘅稅務責任。

Mythex 中嘅訂閱

你喺 Mythex 建立嘅 App 會使用你自己嘅 Stripe 帳戶同金鑰；你嘅 App 冇一鍵連接 Stripe 功能。將測試金鑰同價格 ID 加入專案機密，用上面類似嘅提示詞，並喺 Preview 中用 Stripe 測試卡測試。Webhook 需要 App 嘅公開網址，所以要先發布，然後才喺 Stripe 登記端點；轉用正式金鑰之後，亦要再發布一次，令正式版 App 讀取新金鑰。參閱使用 Stripe 收款同喺後端處理 Webhook。至於整個產品中圍繞帳單嘅其他部分，可以參閱如何建立 SaaS MVP。

常見問題