payments 架構,並記錄已驗證的 webhook 事件。
Stripe 模型
設定
在 Dashboard -> Payments -> Settings、CLI 或管理 API 中配置test 和 live Stripe 密鑰。
Checkout
從前端程式碼使用目前 InsForge 使用者令牌建立 Checkout Sessions。payments.stripe_checkout_sessions 中插入一列。新增 RLS 原則,以便使用者只能為他們被允許計費的主體建立工作階段。PostgreSQL 對 INSERT ... RETURNING 傳回和等冪查詢的列應用 SELECT 原則,因此重試也需要相同主體和等冪密鑰的匹配 SELECT 原則。
Billing Portal
對現有 Stripe 客戶對應使用託管的 Billing 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_type 和 insforge_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 中查找詳細資料。將使用者面向的訂單、信用或權利狀態保留在您自己的資料表中。