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, POLAR_SERVER (sandbox | production; default sandbox, mas obrigatória com NODE_ENV=production). 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.

Fake (somente E2E / testing)

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/*.

[!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

Subscription.customerInternalId é um userId (billing pessoal e assinaturas de org legadas chaveadas no owner) ou org:<organizationId> (checkouts org-scoped). Toda leitura org-scoped resolve o alvo via application/resolve-org-customer.ts: primeiro o customer org:<id> e, se não tiver assinatura viva, o fallback legado org → userId do owner-member. Tanto as operações cross-tenant de admin quanto o port de assinatura ativa do módulo usage passam por ali. Os customers do provider não podem ser migrados, então as assinaturas existentes chaveadas no owner continuam funcionando pelo fallback.

[!NOTE] subscriptions.customerInternalId / purchases.customerInternalId não têm mais FK para users (uma key org:<id> não é um usuário). Um trigger de DB em users preserva o cascade do purge GDPR.

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' }

Cancelamento, ordem dos eventos e chaves de cliente

• Polar, cancelar no fim do período. subscription.canceled é mapeado para um subscription.updated que define canceledAt (cancelamento pendente) e mantém status = active; apenas subscription.revoked encerra o acesso. subscription.uncanceled limpa canceledAt. cancelSubscription({ immediate: false }) do admin usa cancel_at_period_end da Polar; immediate: true revoga.
• Eventos fora de ordem. Subscription.providerUpdatedAt guarda a data de modificação do provider; eventos mais antigos que chegam atrasados são ignorados. Status desconhecido vira incomplete e subscription.updated nunca apaga metadata.
• Renovações da Polar (order.paid com billing_reason diferente de purchase) não são registradas como Purchase.
• Chave de cliente. O checkout a partir de um contexto de organização (x-organization-id) exige billing:update e é atribuído ao customer próprio da org org:<organizationId>; sem contexto é pessoal (userId). O portal da org (POST /billing/portal) abre o customer em que está a assinatura viva da org: para uma assinatura org:<id> qualquer membro com billing:update pode abri-lo; para uma assinatura legada chaveada no owner continua restrito ao billing owner (403 caso contrário).
• Mercado Pago. Preço, moeda e produto do checkout vêm do catálogo BillingPlan (priceId = id do plano), nunca de metadata do cliente. Assinaturas de webhook com mais de 5 minutos são rejeitadas.