Billing Documentation

Stripe Billing Setup ForEVENTS Gateway

Use Stripe as the payment processor forEVENTS Gatewaysubscriptions, payment-method updates, invoices, webhook-driven status sync, reminder scheduling, and routing suspension after overdue billing.

Open Pricing Open Pricing Back to Docs

What It Covers

Stripe is the payment processor.EVENTS Gatewayis the billing control layer.

The platform stores billing state, reminders, subscription posture, and routing suspension policy, while Stripe stays responsible for card-sensitive payment operations.

Stripe Checkout is used to save or update a payment method without storing card data onEVENTS Gatewayinfrastructure.

Part of the commercial billing flow already implemented in the control plane and dashboard.

Stripe Billing Portal is used for customer-managed billing updates and payment method maintenance.

Part of the commercial billing flow already implemented in the control plane and dashboard.

Stripe webhooks keep invoices, transactions, customer billing details, and subscription status in sync with the platform control plane.

Part of the commercial billing flow already implemented in the control plane and dashboard.

If an invoice stays overdue for 15 days after due date,EVENTS Gatewaycan suspend routing automatically until payment is resolved.

Part of the commercial billing flow already implemented in the control plane and dashboard.

Environment

Variables you must configure.

These values are needed to let the API worker talk to Stripe and to return billing flows back to the dashboard.

STRIPE_SECRET_KEY

Private Stripe secret key used by the API worker for Checkout, Billing Portal, and Stripe API requests.

STRIPE_WEBHOOK_SECRET

Private webhook signing secret used to verify the Stripe signature header on incoming events.

STRIPE_BILLING_RETURN_URL

Dashboard base URL used as the return target after Checkout or Billing Portal flows complete.

VITE_STRIPE_PUBLISHABLE_KEY

Public Stripe key exposed in dashboard builds when client-side Stripe references are needed.

Recovery Flow

How overdue billing escalates.

This is the exact commercial posture implemented today for reminders, past-due status, and suspension.

Invoices receive reminder records at 7, 3, 1, and 0 days before due date when they remain unpaid.
When the due date passes, the invoice becomes past due and the dashboard starts showing a billing risk state.
After 15 overdue days, the subscription becomes suspended and the collector rejects new event routing for that site until billing is resolved.
Once payment clears, webhook events can move the invoice and subscription back to a healthy state and routing resumes.

Command Path

Minimal setup commands.

Use these commands and endpoint values to wire Stripe into the API worker and dashboard.

Set Stripe secrets in Cloudflare

cd apps/api-worker
npx wrangler secret put STRIPE_SECRET_KEY
npx wrangler secret put STRIPE_WEBHOOK_SECRET

Set dashboard public Stripe key

cd apps/dashboard
set VITE_STRIPE_PUBLISHABLE_KEY=pk_live_replace_with_your_publishable_key

Set Stripe billing return URL

apps/api-worker/wrangler.jsonc
STRIPE_BILLING_RETURN_URL=https://dash.eventsgateway.com

Create the Stripe webhook endpoint

Endpoint URL:
https://api.eventsgateway.com/v1/billing/stripe-webhook

Webhook Coverage

Events that should be enabled in Stripe.

These Stripe events are already meaningful to the platform and should be sent to the webhook endpoint.

Stripe Event	Purpose InEVENTS Gateway
`checkout.session.completed`	Marks payment-method setup as completed and updates billing profile notes.
`customer.updated`	Refreshes billing name and billing email in the control plane.
`invoice.created / updated / finalized`	Creates or updates hosted invoices, PDFs, invoice numbers, due dates, and invoice status.
`invoice.paid / invoice.payment_succeeded`	Marks invoices as paid and creates successful billing transactions.
`invoice.payment_failed`	Marks invoices as past due and creates failed billing transactions.
`customer.subscription.created / updated / deleted`	Keeps Stripe subscription identifiers, billing periods, and subscription status aligned.
`charge.succeeded / charge.failed`	Adds payment-method detail and charge-level transaction visibility when Stripe sends charge events.

Final Check