Pular para conteúdo

ADR-005: Eduzz em vez de Stripe (Brasil)

Status: ✅ Accepted (2026-05)

Contexto

Para vender QuantFX como SaaS B2C no Brasil, precisamos de gateway de pagamento que suporte:

  1. PIX recorrente — método dominante no Brasil (>60% das transações digitais B2C em 2026)
  2. Boleto recorrente — preferência de muitos compradores tradicionais
  3. Cartão de crédito recorrente — fallback
  4. Webhook de eventos — pagamento confirmado, cancelado, reembolsado, chargeback
  5. Compliance fiscal brasileiro — emissão de NF (nota fiscal) automática
  6. Suporte em português — pra resolver chargebacks e disputas

Decisão

Adotar Eduzz como gateway oficial.

# app/api/routers/webhooks.py
EDUZZ_SECRET = os.environ.get("EDUZZ_SECRET", "")
PRODUCT_MAP = {
    "3031067": "telegram",  # produto pai
    "3031357": "telegram",  # Mensal
    "3031358": "telegram",  # Único
    "3031074": "basic",
    "3031361": "basic",
    "3031365": "basic",
    "3031078": "pro",
    "3031367": "pro",
    "3031368": "pro",
}

Webhook POST /webhooks/eduzz recebe myeduzz.invoice_paid, myeduzz.invoice_canceled, myeduzz.invoice_refunded, myeduzz.invoice_chargeback.

Alternativas consideradas

1. Stripe (líder global)

Vantagens: - Melhor documentação técnica do mercado - SDK em todas as linguagens - Stripe Tax (cálculo de impostos automático) - Stripe Billing (recorrência sofisticada) - Webhooks signed com HMAC-SHA256 nativos - Dashboard de gestão de assinantes maduro

Desvantagens: - ❌ Não suporta PIX recorrente no Brasil (apenas PIX single-payment) - ❌ Não emite NF brasileira — você precisa de provider terceiro (ex: NFE.io) - ❌ Taxa 3.99% + R$0.39 por transação (vs Eduzz 4.99%, mas Eduzz inclui boleto+PIX+cartão sem custo extra) - Saque para conta brasileira em USD (precisa cambiar) - Suporte em inglês

Decisão: rejeitado. PIX recorrente é deal-breaker. >60% dos compradores brasileiros usam PIX em transações até R$300.

2. Mercado Pago (alternativa local forte)

Vantagens: - PIX recorrente nativo - Boleto recorrente - Saque imediato em BRL - Cartão internacional aceito - API REST documentada

Desvantagens: - Não emite NF automaticamente (precisa integrar com 3rd party) - Webhook documentação inferior à Eduzz - Dashboard de gestão de assinantes limitado (foco é checkout, não SaaS) - Sem painel "afiliados" — Eduzz tem programa de afiliados pronto

Decisão: rejeitado. Sem NF automática = friction operacional alto (preciso emitir manualmente cada NF).

3. Hotmart (concorrente direto da Eduzz)

Vantagens: - Plataforma brasileira focada em produtos digitais - PIX, boleto, cartão recorrente - NF automática - Programa de afiliados forte - Marketplace integrado (descoberta orgânica)

Desvantagens: - Taxa mais alta (9.9% + R$1.00 vs Eduzz 4.99% + R$0.99) - Webhook documentação inferior - Foco em info-produtos, não SaaS recorrente (tem mas é secundário) - Branding pesado "Hotmart" no checkout (Eduzz é mais white-label)

Decisão: rejeitado. Taxa 2× maior corrói margem em ticket baixo (R$97-R$297).

4. Pagar.me / Iugu / Vindi (gateways puros)

Vantagens: - Taxas competitivas (2.5%-3.5%) - API muito flexível - Sem markup de plataforma

Desvantagens: - Sem checkout pronto — precisaria construir página de pagamento do zero - Sem emissão de NF (preciso integrar nfe.io ou similar) - Sem programa de afiliados pronto - Mais código pra manter (validação de cartão, antifraud, etc.)

Decisão: rejeitado. Build vs buy — não vale construir do zero pra economizar 1-2% em taxas. Tempo é mais caro.

5. Kirvano (alternativa moderna que considerei)

Vantagens: - PIX recorrente nativo - NF automática - Taxa competitiva (4.99% similar a Eduzz) - Webhook moderno - UX de checkout boa

Desvantagens: - Plataforma mais nova (2023) — menos histórico em chargebacks/disputas - Sem programa de afiliados maduro - Menos integrações de 3rd party (calendly, email tools, etc.) - Risco de descontinuação (startup early-stage)

Decisão: adiado para Fase 2. Vamos com Eduzz primeiro (estabilidade), Kirvano fica como fallback se Eduzz aumentar taxas ou degradar serviço.

Consequências

✅ Positivas

  • PIX recorrente nativo — 60%+ dos clientes pagam por PIX
  • NF automática — Eduzz emite NF Eletrônica para cada venda (compliance OK)
  • Programa de afiliados pronto — ativaremos na Fase 2 (50% comissão recorrente)
  • Webhooks com HMAC — app/api/routers/webhooks.py valida fail-closed
  • 9 produtos configurados — 3 planos × 3 modalidades (Mensal/Único/Pai)
  • Suporte em português — chargebacks resolvidos rápido
  • Dashboard de assinantes — vejo MRR, churn, LTV no painel Eduzz

❌ Negativas

  • Taxa 4.99% + R$0.99 — em R$197 = R$10.83 por venda (~5.5%)
  • Trade-off: aceita-se em troca de NF + PIX + boleto sem custo extra
  • Lock-in moderado — productIds da Eduzz hardcoded em webhooks.py
  • Mitigação: PRODUCT_MAP dict é fácil de migrar
  • Branding "Eduzz" no checkout — comprador vê eduzz.com no fluxo
  • Mitigação: domain personalizado disponível em planos superiores
  • Saque em D+14 (vs Stripe D+7)
  • Mitigação: aceitável para projeto B2C com baixo capital de giro

🎯 Trade-offs aceitos

Custo Benefício
Taxa 4.99% (vs Pagar.me 2.5%) NF automática + checkout pronto + afiliados
Lock-in nos productIds PIX recorrente que Stripe não oferece
Saque D+14 (vs D+0) Suporte em PT-BR para chargebacks
Branding Eduzz visível Menos código pra manter (sem checkout próprio)

Implementação

Webhook

  • app/api/routers/webhooks.py:294-457 — endpoint POST /webhooks/eduzz
  • HMAC-SHA256 validation com fail-closed
  • Suporta 4 eventos: paid, canceled, refunded, chargeback

Provisionamento automático

  • Webhook valida assinatura → identifica plano via PRODUCT_MAP → cria UUID em api_keys → envia email com instruções

Revogação automática

  • Eventos cancel/refund/chargeback → UPDATE api_keys SET active=FALSE WHERE email=$1
  • Email de notificação ao cliente (revogação)

Idempotência

  • Eduzz reenvia webhooks em caso de timeout
  • Verifica api_keys WHERE email=$1 AND active=TRUE AND expires_at > NOW() antes de criar nova
  • Evita duplicar chave em renovação mensal

Plano B (se Eduzz degradar)

Se em 12 meses houver: - Aumento de taxa >6% sem justificativa - Disputa de chargeback mal resolvida (perdemos sem motivo) - Webhook downtime >2h em 1 mês - Mudança na ToS desfavorável

→ Migração planejada para Kirvano (ADR-005-bis a ser criado quando ocorrer): 1. Cadastrar produtos na Kirvano 2. Criar PRODUCT_MAP_KIRVANO em webhooks.py 3. Adicionar handler POST /webhooks/kirvano 4. Migrar tráfego de checkout gradualmente (50/50 → 100% Kirvano) 5. Manter handler Eduzz ativo por 90d para renovações antigas

Métricas de monitoramento

Tracker em app/api/routers/webhooks.py:

  • Webhooks recebidos / hora
  • Assinaturas HMAC inválidas (alerta se >5/h → ataque)
  • Taxa de provisionamento bem-sucedido (objetivo: 99.9%)
  • Latência do webhook (objetivo: <500ms p95)

Referências

  • Eduzz API Docs: https://api.eduzz.com/docs
  • Banco Central do Brasil — Estatísticas PIX 2025
  • Stripe — PIX support roadmap (Brasil, sem ETA para recorrente)
  • Lei Geral de Proteção de Dados (LGPD) — Art. 7º, X (legítimo interesse)