跳轉到主要內容
當您想要 Stripe 託管的 Checkout、Stripe Products 和 Prices、Stripe Subscriptions 和託管的 Billing Portal 時,使用 Stripe 整合。 InsForge 在伺服器端儲存 Stripe 密鑰、從您的應用建立 Checkout 和 Billing Portal 工作階段、當您的後端可存取時自動管理 Stripe webhook 端點、將 Stripe 狀態鏡像到 payments 架構,並記錄已驗證的 webhook 事件。

Stripe 模型

Stripe 概念InsForge 資料表或 API
Productpayments.stripe_products
Pricepayments.stripe_prices
Checkout SessionPOST /api/payments/stripe/{environment}/checkout-sessionspayments.stripe_checkout_sessions
Billing Portal SessionPOST /api/payments/stripe/{environment}/customer-portal-sessionspayments.stripe_customer_portal_sessions
Subscriptionpayments.stripe_subscriptionspayments.stripe_subscription_items
Customer mappingpayments.customer_mappingsprovider = 'stripe'
Webhook eventpayments.webhook_eventsprovider = 'stripe'
Dashboard transaction rowpayments.transactionsprovider = 'stripe'

設定

在 Dashboard -> Payments -> Settings、CLI 或管理 API 中配置 testlive Stripe 密鑰。
連接密鑰後,InsForge 驗證帳戶、在祕密儲存中儲存密鑰、嘗試建立託管的 Stripe webhook 端點,並為 Products、Prices、Customers 和 Subscriptions 執行同步。

Checkout

從前端程式碼使用目前 InsForge 使用者令牌建立 Checkout Sessions。
對於訂閱 Checkout,傳遞計費主體。主體是您的應用擁有的計費所有者,如使用者、團隊、工作區、組織、租戶或群組。
Checkout 使用呼叫者的 InsForge 令牌在 payments.stripe_checkout_sessions 中插入一列。新增 RLS 原則,以便使用者只能為他們被允許計費的主體建立工作階段。PostgreSQL 對 INSERT ... RETURNING 傳回和等冪查詢的列應用 SELECT 原則,因此重試也需要相同主體和等冪密鑰的匹配 SELECT 原則。

Billing Portal

對現有 Stripe 客戶對應使用託管的 Billing Portal。
Portal 建立需要已驗證的使用者和主體的現有 payments.customer_mappings 列。使用 RLS 或伺服器端成員資格檢查保護 portal 建立,以便使用者無法為他們不管理的團隊或組織開啟計費設定。

Webhooks 和履行

當後端具有公開 URL 時,Stripe webhook 會自動管理。InsForge 侦聽保持 checkout 嘗試、客戶、訂閱、退款和交易投影最新所需的事件。 Stripe 還建議從 webhook 而不是成功 URL 履行 Checkout 訂單。在 InsForge 中,將履行觸發器附加到 payments.webhook_events

事件排序

Webhook 事件獨立驗證和處理。InsForge 在將事件標記為 processed 之前提交派生自事件的每一列,但 Stripe 不保證事件間的排序:invoice.paid 可以在 checkout.session.completed 之前處理,所以另一個事件建立的列(如 payments.customer_mappings)在觸發器觸發時可能不存在。 對於訂閱事件,首先從事件有效負荷解析計費主體 — InsForge 在 checkout 處將 insforge_subject_typeinsforge_subject_id 戳入訂閱中繼資料,Stripe 將其快照到訂閱產生的發票上,作為 parent.subscription_details.metadata。接下來檢查 invoice.metadata,然後回退到 payments.customer_mappings(InsForge 內部使用的相同順序):
永遠不要讓履行靜默跳過 — 記錄或死信您無法解析的事件,以便可以重播。

同步和儀表板狀態

Stripe 同步鏡像 Products、Prices、Customers 和 Subscriptions。Webhooks 在 Stripe 發出事件時維護工作階段、訂閱、客戶、退款和交易狀態。 payments.transactions 是儀表板的報告投影。它為您提供支付意圖、費用、發票、checkout 工作階段和退款 ID 等提供商參考 ID,以便您可以在 Stripe Dashboard 中查找詳細資料。將使用者面向的訂單、信用或權利狀態保留在您自己的資料表中。

參考