payments schema, and records verified webhook events.
Stripe model
Setup
Configuretest and live Stripe secret keys in Dashboard -> Payments -> Settings, the CLI, or the admin API.
Checkout
Create Checkout Sessions from frontend code with the current InsForge user token.payments.stripe_checkout_sessions using the caller’s InsForge token. Add RLS policies so users can only create sessions for subjects they are allowed to bill. PostgreSQL applies SELECT policies to rows returned by INSERT ... RETURNING and idempotent lookups, so retries also need a matching SELECT policy for the same subject and idempotency key.
Billing Portal
Use the hosted Billing Portal for an existing Stripe customer mapping.payments.customer_mappings row for the subject. Protect portal creation with RLS or a server-side membership check so users cannot open billing settings for a team or organization they do not manage.
Webhooks and fulfillment
Stripe webhooks are managed automatically when the backend has a public URL. InsForge listens for the events needed to keep checkout attempts, customers, subscriptions, refunds, and transaction projections current. Stripe also recommends fulfilling Checkout orders from webhooks instead of the success URL. In InsForge, attach fulfillment triggers topayments.webhook_events.
Event ordering
Webhook events are verified and processed independently. InsForge commits every row derived from an event before marking that eventprocessed, but Stripe gives no ordering guarantee across events: invoice.paid can be processed before checkout.session.completed, so rows created by another event (such as payments.customer_mappings) may not exist yet when your trigger fires.
For subscription events, resolve the billing subject from the event payload first — InsForge stamps insforge_subject_type and insforge_subject_id into subscription metadata at checkout, and Stripe snapshots it onto subscription-generated invoices as parent.subscription_details.metadata. Check invoice.metadata next, then fall back to payments.customer_mappings (the same order InsForge uses internally):
Sync and dashboard state
Stripe sync mirrors Products, Prices, Customers, and Subscriptions. Webhooks maintain session, subscription, customer, refund, and transaction state as Stripe emits events.payments.transactions is a reporting projection for the dashboard. It gives you provider reference IDs such as payment intent, charge, invoice, checkout session, and refund IDs so you can look up details in the Stripe Dashboard. Keep user-facing order, credit, or entitlement state in your own tables.