Payments
Payments use one active billing provider, local catalog configuration, checkout services, portal access, webhook projection, and provider-specific troubleshooting.
On this page
Billing module
Provider selection, catalog, checkout, webhooks, and billing rules.
Customer billing
Customer history, portal access, ledgers, exports, refunds, and disputes.
Production safety
Webhook idempotency, duplicate delivery, request ids, and cron safety.
Troubleshooting
Provider setup, webhook secrets, customer projection, and empty history checks.
Provider model
| Area | How the app handles it |
|---|---|
| Stripe | Supports checkout, portal, subscriptions, one-time purchases, usage, base-plus-usage, credits, invoices, refunds, disputes, and exports. |
| Lemon Squeezy | Supports checkout, subscriptions, one-time purchases, usage-oriented catalog setup, app-local prepaid-credit grants, portal-style customer flows, and provider webhooks. |
| Dodo Payments | Supports hosted checkout, portal, subscriptions, refunds, usage events, and provider webhooks. |
| Polar | Supports hosted checkout, portal, subscriptions, refunds, meters, and provider webhooks. |
| Creem | Supports hosted checkout, portal, signed webhooks, full transaction refunds, recurring licenses, one-time licenses, and prepaid credits; metered models are not supported. |
| One-time purchases | Use licensed_one_time catalog entries and provider price ids. |
| Customer portal | Use the active provider and current signed-in billing customer record. |
| Webhooks | Verify signature, claim event row, dispatch by event type, project local billing state, and mark event status. |
Recipe: choose a payment provider edition
Configure one provider edition without leaving catalog, setup, checkout, and webhook behavior inconsistent.
Implementation locations
Inspect
- src/features/billing/server/runtime/provider.ts
- src/features/billing/server/catalog/configuration.ts
- src/features/billing/server/runtime/readiness.ts
- src/config/product-distribution.ts
- src/features/billing/server/providers/stripe/checkout.ts
- src/features/billing/server/providers/lemonsqueezy/checkout.ts
- src/features/billing/server/providers/dodo/checkout.ts
- src/features/billing/server/providers/polar/checkout.ts
- src/features/billing/server/providers/creem/checkout.ts
Edit
- provider distribution branch
- BILLING_CATALOG_JSON
- BILLING_ENABLED_MODELS
- src/features/billing/server/catalog/configuration.ts
Steps
- Select the provider edition branch; do not change providers inside a buyer checkout.
- Replace catalog product and price ids with provider-compatible values.
- Configure the matching webhook endpoint, secret, and billing worker schedule.
- Open /billing/setup and resolve every readiness failure.
- Run a provider test checkout and confirm local billing projection updates.
Verify
- pnpm run test:features
- pnpm run quality
- Open /billing/setup and run provider test mode.
Common mistakes
- Do not mix provider product IDs or credentials across environments.
- Do not reuse webhook secrets from a different endpoint.
- Do not assume provider events arrive in order.
- Do not enable metered models on the Creem edition.