Plataforma de Integração de Pagamentos
Stripe event-driven: checkout, assinaturas e gestão de ciclo de vida
O produto precisava suportar pagamentos recorrentes com múltiplos planos, upgrades/downgrades em tempo real e recuperação automática de inadimplência.
- 01Garantir idempotência no processamento de webhooks Stripe (eventos podem chegar duplicados)
- 02Sincronizar estado de assinatura entre Stripe e o banco de dados local sem inconsistência
- 03Gerenciar transições de plano (upgrade/downgrade) com pró-rata correto
- 04Recuperar pagamentos falhos com retry inteligente sem spam ao cliente
Event-driven via webhooks com idempotência
Cada evento Stripe é processado exatamente uma vez usando o event ID como chave de idempotência no banco. Garante consistência mesmo com retentativas do Stripe.
Estado local como fonte de verdade para a aplicação
A aplicação mantém seu próprio modelo de assinatura sincronizado via webhooks. Isso permite consultas rápidas sem dependência de latência da API Stripe.
Checkout Session vs. Payment Intent
Checkout Session para fluxos novos (UI hospedada pelo Stripe, menor surface de PCI). Payment Intent apenas para renovações automáticas já autorizadas.
Manter estado local duplicado requer reconciliação periódica com a API Stripe para detectar deriva. Um job diário de reconciliação foi suficiente para o volume atual.
FastAPI recebe webhooks Stripe com verificação de assinatura HMAC. Cada tipo de evento tem um handler dedicado. Estado de assinatura salvo em PostgreSQL com enum de status (active, past_due, canceled, trialing).
Integração completa com Stripe: webhooks, checkout automático, gestão de assinaturas e recuperação de pagamentos falhos.
- ›Testar webhooks localmente com Stripe CLI antes de produzir economiza horas de debugging
- ›Logar o payload completo do evento (truncado) facilita auditoria de disputas de pagamento
- ›Implementar webhook delivery log permite reprocessar eventos manualmente quando necessário