跳转到主要内容
当您想要 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 中查找详细信息。将用户面向的订单、信用或权利状态保留在您自己的表中。

参考