Integracao Stripe (checkout + webhooks + portal de billing)

Setup

1. Stripe Dashboard

1. https://dashboard.stripe.com > Developers > API Keys > copie Secret Key
2. Webhooks > Add endpoint > URL: https://[tenant].studeia.com/api/webhooks/stripe
3. Events to send:
   • checkout.session.completed
   • customer.subscription.created
   • customer.subscription.updated
   • customer.subscription.deleted
   • invoice.payment_succeeded
   • invoice.payment_failed
4. Copie Webhook signing secret

2. Criar produtos + prices

Para cada plano B2B do Studeia (mini, growth, pro_100):

1. Products > Add product > nome (ex: "Studeia Mini")
2. Pricing: Recurring monthly + BRL R$ 250.00
3. Copie price_id (ex: price_1TZk...)
4. Repita para USD se quiser suportar clientes internacionais

3. Env vars

STRIPE_SECRET_KEY=sk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...
STRIPE_PRICE_MINI=price_...
STRIPE_PRICE_GROWTH=price_...
STRIPE_PRICE_PRO_100=price_...
STRIPE_PRICE_MINI_USD=price_...
STRIPE_PRICE_GROWTH_USD=price_...
STRIPE_PRICE_PRO_100_USD=price_...

Fluxo de checkout

Admin clica "Contratar Mini" em /institution/billing
  ↓
POST /api/institution/billing/checkout
  Body: { planSlug: "mini" }
  ↓
Studeia createCheckoutSession() (lib/billing/create-checkout.ts):
  1. resolveCustomerIdForProvider() — pega/cria stripeCustomerId
  2. Detect currency via getCurrencyFromHeaders() (server-side, anti-fraud)
  3. Stripe Checkout Session com line_items=[price_id correto]
  4. Retorna { url } do Stripe Checkout
  ↓
Frontend redireciona: window.location.href = data.url
  ↓
Admin paga no Stripe Checkout
  ↓
Stripe envia webhook checkout.session.completed
  ↓
Studeia applyWebhookEvent():
  1. Valida HMAC signature
  2. stripe.subscriptions.retrieve(subscriptionId) — sempre re-fetch (nao confia em metadata)
  3. Valida price_id contra allowlist
  4. Cross-check tenantId entre session.metadata e subscription.metadata
  5. Cria/atualiza TenantSubscription com currentPeriodEnd REAL
  6. Promove Tenant.plan
  7. Cria PaymentLog (idempotente via [provider, externalEventId])

Hardening (regras 129-139)

• Webhook retorna 5xx em falha: Stripe re-tenta 3 dias
• Ordering guard: lastEventAt + lastEventId em TenantSubscription. Eventos fora de ordem sao pulados com warning + PaymentLog
• Idempotencia: unique [provider, externalEventId] em PaymentLog
• Schema Zod: z.enum(PAID_PLAN_SLUGS) no body do checkout (anti-typo)
• PII redact: PaymentLog.rawPayload passa por redactPaymentPayload() (remove email/name/address/billing_details/cpfCnpj/card.last4 antes de persistir)
• Past_due gate: isAccessBlocked(status) em layouts (substitui status === "suspended"). Cron /api/cron/billing-grace-expire transiciona apos grace 7d

Portal Stripe self-manage

POST /api/institution/billing/portal retorna URL temporaria do Stripe portal:

• Admin troca plano (upgrade/downgrade)
• Atualiza cartao
• Ve invoices
• Cancela subscription
• Sem passar pelo suporte Studeia

Multi-currency

Veja tambem

• Integration Asaas (PIX)
• Plataforma overview