Billing

Estratégia

PAYMENT_PROVIDER no env decide. A interface PaymentProvider abstrai checkout, webhooks, subscriptions. Trocar de provider = um commit.

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

Providers suportados

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. Pensado para LATAM — suporta Pix, wallet do Mercado Pago, parcelamento.

Polar

PAYMENT_PROVIDER=polar. Vars: POLAR_ACCESS_TOKEN, POLAR_WEBHOOK_SECRET. Ideal para developer tools — integra com GitHub.

Modelo

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

Subscription.status é a SSOT (active, past_due, canceled, trialing). Os webhooks atualizam; o frontend nunca assume.

PAYMENT_PROVIDER=fake. Var: FAKE_WEBHOOK_SECRET (qualquer string). Retorna planos estáticos, URLs falsas de checkout/portal e aceita webhooks assinados com HMAC-SHA256 (x-fake-signature: sha256=<hex>). Usado pela suite E2E — nunca fazer deploy em produção.

Teste de webhooks local

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

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

Operações de admin de plataforma

O Plano 05 adiciona cinco métodos cross-tenant de assinatura ao IPaymentProvider. Eles dão suporte à página /admin/billing/[orgId] e aos endpoints /api/v1/platform/organizations/:id/subscription/*.

Método	Descrição
`getSubscriptionSummary(customerInternalId)`	Retorna a assinatura atual (`null` se não houver).
`changePlan(customerInternalId, newPriceId)`	Troca a assinatura para outro preço.
`extendTrial(customerInternalId, days)`	Estende `trialEndsAt` em `[1, 90]` dias.
`cancelSubscription(customerInternalId, { immediate })`	Cancela agora ou ao fim do período.
`listInvoices(customerInternalId, { page, pageSize })`	Histórico paginado de invoices.

[!NOTE] Apenas o adapter Fake os implementa de saída (estado em memória, usado pelos testes E2E e smoke do admin). Stripe / Polar / MercadoPago retornam InfrastructureError("X is not implemented by the Y adapter; ...") via o helper compartilhado adminUnsupported em apps/server/src/modules/billing/infrastructure/providers/admin-unsupported.ts. Para produção, substitua cada stub pela chamada ao SDK correspondente (ex.: stripe.subscriptions.update, stripe.invoices.list).

Resolução org → customer

O modelo de billing do boilerplate é per-user: Subscription.customerInternalId === userId. As operações cross-tenant resolvem o alvo via org → userId do owner-member (ver application/use-cases/admin/resolve-org-customer.ts). Quando migrar para billing per-org, esse arquivo é o único que precisa mudar.

Eventos de auditoria

Cada mutação emite uma entrada de audit com o userId real do ator (consciente de impersonation):

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