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