Skip to main content
Use the Stripe integration when you want Stripe-hosted Checkout, Stripe Products and Prices, Stripe Subscriptions, and the hosted Billing Portal. InsForge stores Stripe secret keys server-side, creates Checkout and Billing Portal sessions from your app, automatically manages the Stripe webhook endpoint when your backend is reachable, mirrors Stripe state into the payments schema, and records verified webhook events.

Stripe model

Setup

Configure test and live Stripe secret keys in Dashboard -> Payments -> Settings, the CLI, or the admin API.
After a key is connected, InsForge validates the account, stores the key in the secret store, tries to create the managed Stripe webhook endpoint, and runs sync for Products, Prices, Customers, and Subscriptions.

Checkout

Create Checkout Sessions from frontend code with the current InsForge user token.
For subscription Checkout, pass a billing subject. The subject is your app-owned billing owner, such as a user, team, workspace, organization, tenant, or group.
Checkout inserts a row in 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.
Portal creation requires an authenticated user and an existing 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 to payments.webhook_events.

Event ordering

Webhook events are verified and processed independently. InsForge commits every row derived from an event before marking that event processed, 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):
Never let fulfillment skip silently — log or dead-letter events you cannot resolve so they can be replayed.

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.

References