Billing

Strategy

PAYMENT_PROVIDER in env decides. The PaymentProvider interface abstracts checkout, webhooks, subscriptions. Switching providers = one commit.

interface PaymentProvider {
  createCheckout(input): Promise<Result<CheckoutSession, BillingError>>;
  handleWebhook(req): Promise<Result<DomainEvent, BillingError>>;
  cancelSubscription(id): Promise<Result<void, BillingError>>;
}

Supported providers

Stripe

PAYMENT_PROVIDER=stripe. Vars: STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET. Webhook: POST /webhooks/stripe.

Mercado Pago

PAYMENT_PROVIDER=mercado-pago. Vars: MERCADO_PAGO_ACCESS_TOKEN, MERCADO_PAGO_WEBHOOK_SECRET. Built for LATAM — supports Pix, MercadoPago wallet, installments.

Polar

PAYMENT_PROVIDER=polar. Vars: POLAR_ACCESS_TOKEN, POLAR_WEBHOOK_SECRET, optional POLAR_SERVER (sandbox | production; defaults to sandbox, but is required when NODE_ENV=production).

The Polar adapter is fully wired against @polar-sh/sdk. Implements:

• createCheckoutSession() — polar.checkouts.create with externalCustomerId keyed on the boilerplate's user/org id (Polar lazy-creates the customer)
• createCustomerPortalLink() — polar.customerSessions.create returns a hosted portal URL
• parseWebhook() — validateEvent from @polar-sh/sdk/webhooks, maps subscription.created/updated/active/uncanceled/canceled/revoked and order.paid to the boilerplate's normalized BillingEvent
• listPlans() — paginates polar.products.list({ isArchived: false }), maps to the Plan DTO. Recognizes metadata.features (newline-separated) and metadata.highlight === 'true'
• getSubscriptionSummary / changePlan / cancelSubscription / listInvoices — wired to polar.subscriptions.* and polar.orders.list
• extendTrial — returns adminUnsupported. Polar trials are configured at the product level, not per-subscription, so there's no API to call

[!NOTE] Polar's checkout flow uses a single successUrl for both completed and abandoned sessions — it doesn't accept a separate cancel URL. The IPaymentProvider port still requires both fields for Stripe parity; the Polar adapter ignores cancelUrl and uses successUrl exclusively.

Model

Subscription ─→ Plan ─→ Feature
     │
     └──→ Organization

Subscription.status is the SSOT (active, past_due, canceled, trialing). Webhooks update it; the frontend never assumes.

Fake (E2E / testing only)

PAYMENT_PROVIDER=fake. Var: FAKE_WEBHOOK_SECRET (any string). Returns static plans, fake checkout/portal URLs, and accepts HMAC-SHA256 signed webhooks (x-fake-signature: sha256=<hex>). Used by the E2E suite — never deploy to production.

Local webhook testing

stripe listen --forward-to localhost:3005/api/v1/billing/webhook

For Mercado Pago / Polar use ngrok. For E2E tests: PAYMENT_PROVIDER=fake FAKE_WEBHOOK_SECRET=<secret>.

Platform admin operations

Plan 05 adds five cross-tenant subscription methods to IPaymentProvider. They power the /admin/billing/[orgId] page and the /api/v1/platform/organizations/:id/subscription/* endpoints.

[!NOTE] The Fake adapter implements all five (in-memory state for E2E + admin smoke tests). The Polar adapter implements four of five — extendTrial returns adminUnsupported because Polar trials are configured at the product level, not the subscription level, so there's no per-subscription extension API. Stripe and MercadoPago still return adminUnsupported for all five and need their SDK methods wired (e.g. stripe.subscriptions.update, stripe.invoices.list).

Org → customer resolution

Subscription.customerInternalId is either a userId (personal billing, and legacy org subscriptions keyed on the org owner) or org:<organizationId> (org-scoped checkouts). Every org-scoped read resolves the target via application/resolve-org-customer.ts: the org:<id> customer first, then — if it has no live subscription — the legacy org → owner-member's userId fallback. Cross-tenant admin operations and the usage module's active-subscription port both go through it. Provider-side customers can't be migrated, so existing owner-keyed subscriptions keep working through the fallback.

[!NOTE] subscriptions.customerInternalId / purchases.customerInternalId have no FK to users any more (an org:<id> key isn't a user). A DB trigger on users preserves the GDPR purge cascade.

Audit events

Every mutation emits an audit row with the actor's real userId (impersonation-aware):

• platform.org.plan_changed — { previousPriceId, newPriceId }
• platform.org.trial_extended — { days, newTrialEndsAt }
• platform.org.subscription_cancelled — { mode: 'immediate' | 'at_period_end' }

One-shot purchases

Beyond recurring Subscriptions, the billing module also tracks one-shot Purchases — single immutable receipts populated from the same webhook stream (invoice.paid events). Same IPaymentProvider port; same adapters; different read model.

The dashboard's /downloads page consumes useMyPurchases() to render the user's purchase history with re-download links. See the Polar deploy guide for the end-to-end setup.

Cancellation, ordering and customer keys

• Polar cancel at period end. subscription.canceled is mapped to a subscription.updated that sets canceledAt (pending cancel) and keeps status = active; only subscription.revoked ends access. subscription.uncanceled clears canceledAt. Admin cancelSubscription({ immediate: false }) uses Polar's cancel_at_period_end; immediate: true revokes.
• Out-of-order events. Subscription.providerUpdatedAt stores the provider's modification time; older events arriving late are ignored. Unknown statuses default to incomplete, and subscription.updated never wipes metadata.
• Polar renewals (order.paid with billing_reason other than purchase) are not recorded as Purchase rows.
• Customer key. Checkout from an organization context (x-organization-id) requires billing:update and is attributed to the org's own customer org:<organizationId>; without it, checkout is personal (userId). The org portal (POST /billing/portal) opens the customer the org's live subscription is on: for an org:<id> subscription any member with billing:update may open it; for a legacy owner-keyed subscription it stays limited to the billing owner (403 otherwise).
• Mercado Pago. The checkout price, currency and product come from the BillingPlan catalog (priceId = plan id), never from client metadata. Webhook signatures older than 5 minutes are rejected.