Configurar Integracao Stripe

Levy Fleets usa o Stripe como processador de pagamentos principal para todas as transacoes financeiras. Este guia abrangente cobre a configuracao e configuracao completa da integracao Stripe para operadores de frota, incluindo chaves de API, webhooks, modo de teste e recursos avancados.

O Que o Stripe Processa

O Stripe suporta todos os recursos relacionados a pagamentos no Levy Fleets:

• Pagamentos e cobrancas de viagens - Cobrando clientes por viagens
• Recargas de carteira - Reabastecimento manual e automatico de saldo
• Armazenamento de metodos de pagamento - Armazenamento seguro de cartoes de clientes
• Verificacao de identidade - KYC via Stripe Identity
• Processamento de reembolsos - Devolvendo fundos aos clientes
• Tentativas de pagamento - Recuperando pagamentos falhados

Pre-requisitos

Antes de configurar a integracao Stripe, certifique-se de ter:

1. Uma conta Stripe - Crie uma em stripe.com se ainda nao tiver
2. Acesso de admin ao seu Dashboard Levy Fleets
3. Acesso a variaveis de ambiente - Dashboard Vercel ou configuracao do servidor
4. Compreensao do seu modelo de pagamento - Baseado em carteira ou pos-pagamento

Variaveis de Ambiente

Variaveis Obrigatorias

Configure estas variaveis de ambiente para o Stripe funcionar:

Variaveis Opcionais (Modo de Teste)

Para desenvolvimento e testes:

Variaveis Adicionais

Obtendo Suas Chaves Stripe

Configuracao de Webhook

Webhooks permitem que o Stripe notifique o Levy Fleets sobre eventos de pagamento. Configure seu endpoint de webhook para receber estes eventos:

Eventos de Webhook Obrigatorios

Eventos de Cobranca

• charge.succeeded - Capturar pagamentos bem-sucedidos
• charge.failed - Rastrear tentativas de pagamento falhadas
• charge.captured - Registrar pre-autorizacoes capturadas
• charge.updated - Sincronizar atualizacoes de cobranca
• charge.refunded - Rastrear reembolsos
• charge.expired - Tratar cobrancas expiradas
• charge.pending - Rastrear cobrancas pendentes

Eventos de Disputa

• charge.dispute.created
• charge.dispute.updated
• charge.dispute.closed
• charge.dispute.funds_withdrawn
• charge.dispute.funds_reinstated

Eventos de Payment Intent

• payment_intent.succeeded - Processar pagamentos concluidos

Eventos de Setup Intent

• setup_intent.succeeded - Salvar novos metodos de pagamento

Eventos de Cliente

• customer.created - Vincular clientes Stripe ao seu banco de dados
• customer.updated - Sincronizar mudancas de cliente
• customer.deleted - Tratar exclusao de cliente

Eventos de Identidade (se usar verificacao de ID)

• identity.verification_session.requires_input
• identity.verification_session.processing
• identity.verification_session.canceled
• identity.verification_session.verified

Seguranca de Webhook

Todos os webhooks sao automaticamente verificados atraves do mecanismo de assinatura do Stripe. O sistema tambem registra todos os eventos de webhook na tabela stripe_webhook_logs para fins de auditoria e depuracao.

Modo de Teste vs. Modo ao Vivo

Selecao Automatica de Modo de Teste

O sistema usa automaticamente o modo de teste para:

1. Usuarios super admin - Todos os usuarios com a funcao super_admin usam automaticamente o modo de teste
2. E-mails internos - Qualquer cliente com e-mail @levyelectric.com usa modo de teste

Isso permite testes seguros sem risco de cobrancas de producao.

Comportamento do Modo de Teste

No modo de teste:

• Todas as chamadas de API Stripe usam a chave secreta de teste
• Metodos de pagamento usam numeros de cartao de teste
• Nenhum dinheiro real e cobrado
• O modo de teste e indicado na interface do dashboard

Numeros de Cartao de Teste

Use estes cartoes de teste para desenvolvimento:

Use qualquer data de validade futura valida e qualquer CVC de 3 digitos (4 digitos para Amex).

Configuracao do Sistema de Pagamento

Configuracoes de Pagamento da Subconta

Cada subconta pode configurar seu sistema de pagamento em Configuracoes > Pagamentos:

Sistema de Carteira vs. Pos-pagamento

Sistema de Recarga Automatica

A recarga automatica cobra automaticamente o cartao do cliente quando o saldo da carteira cai abaixo de um limite.

Requisitos

Para que a recarga automatica funcione:

1. Configuracao da subconta - Recarga automatica ativada na subconta
2. Preferencia do cliente - Cliente deve optar pela recarga automatica
3. Metodo de pagamento - Cliente deve ter um metodo de pagamento padrao
4. Cliente Stripe - Cliente deve ter um ID de cliente Stripe vinculado

Como Funciona

1. Viagem termina ou verificacao periodica e executada
2. Sistema verifica se saldo da carteira esta no ou abaixo do limite
3. Sistema adquire um bloqueio para evitar cobrancas duplicadas
4. PaymentIntent Stripe e criado com chave de idempotencia
5. Em caso de sucesso, saldo da carteira e creditado
6. Bloqueio e liberado

Prevencao de Cobranca Duplicada

O sistema usa dois mecanismos para prevenir cobrancas duplicadas:

1. Bloqueio de banco de dados - Colunas rastreiam status e expiracao do bloqueio
2. Chave de idempotencia Stripe - Chave unica por tentativa de recarga automatica

Sistema de Tentativa de Pagamento

Quando a carteira de um cliente fica negativa, o sistema tenta automaticamente cobrar o valor pendente.

Cronograma de Tentativas

Rotacao de Metodos de Pagamento

Ao tentar novamente, o sistema roda por todos os metodos de pagamento armazenados:

1. Metodo de pagamento padrao primeiro - Tenta o cartao preferido do cliente
2. Depois outros cartoes por idade - Cartoes mais antigos sao tentados primeiro
3. Ciclo reinicia - Em cada nova janela de agendamento, todos os metodos sao tentados novamente

Cancelamento Automatico

Saldos abaixo de R$ 0,50 sao automaticamente cancelados (minimo do Stripe e R$ 0,50 para cobrancas em BRL).

Verificacao de Identidade (Stripe Identity)

Levy Fleets integra com Stripe Identity para verificacao de identidade de clientes.

Modos de Verificacao

Configure a verificacao de identidade no nivel da subconta:

Verificacao Baseada em Risco

Ao usar o modo baseado em risco:

1. Stripe Radar pontua pagamentos (0-100)
2. Niveis de risco: normal (10), elevated (50), highest (75)
3. Se pontuacao >= limite, verificacao e obrigatoria
4. Cliente e bloqueado ate verificacao

Cobrancas de Verificacao (Bloqueios Temporarios)

O sistema pode colocar bloqueios de autorizacao temporarios em cartoes de clientes para verificar a validade do metodo de pagamento.

Politicas de Bloqueio

Como Bloqueios Funcionam

1. Autorizacao criada - Nenhuma cobranca real, apenas um bloqueio
2. Cartao validado - Confirma que cartao esta ativo e tem saldo
3. Bloqueio liberado - Automaticamente apos a viagem ou dentro de 7 dias
4. Nunca capturado - Bloqueios de verificacao nunca sao convertidos em cobrancas reais

Integracao com Banco de Dados

Tabelas Principais

Cron Jobs

Varios cron jobs suportam o sistema de pagamento:

Todos os endpoints cron requerem o header CRON_SECRET para autenticacao.

Desenvolvimento Local

Testando com Stripe CLI

Disparar Eventos de Teste

# Disparar um evento charge.succeeded
stripe trigger charge.succeeded

# Disparar um evento payment_intent.succeeded
stripe trigger payment_intent.succeeded

Monitoramento e Depuracao

Verificar Logs de Webhook

Visualize atividade recente de webhook no seu banco de dados:

SELECT
  event_type,
  status,
  COUNT(*) as count,
  MAX(processed_at) as last_seen
FROM stripe_webhook_logs
WHERE processed_at > NOW() - INTERVAL '24 hours'
GROUP BY event_type, status
ORDER BY last_seen DESC;

Analisar Pagamentos Falhados

SELECT
  decline_reason,
  COUNT(*) as count,
  SUM(amount) / 100.0 as total_brl
FROM stripe_charges
WHERE status = 'failed'
  AND created_at > NOW() - INTERVAL '7 days'
GROUP BY decline_reason
ORDER BY count DESC;

Solucao de Problemas

Problemas Comuns

"Verificacao de assinatura de webhook falhou"

Causa: STRIPE_WEBHOOK_SECRET incorreto ou corpo da requisicao modificado

Solucao:

1. Verifique se o segredo corresponde ao seu Dashboard Stripe
2. Garanta que nenhum middleware modifique o corpo da requisicao
3. Verifique o nome correto do header: stripe-signature

"Cliente nao encontrado" no Stripe

Causa: Cliente foi excluido no Stripe ou nunca sincronizado

Solucao:

1. Verifique stripe_customer_id na tabela customers
2. Verifique se o ID existe no Dashboard Stripe
3. Limpe o ID e deixe o sistema recria-lo

Pagamentos nao estao sincronizando

Causa: Endpoint de webhook mal configurado ou falhando

Solucao:

1. Verifique stripe_webhook_logs para erros
2. Verifique a URL do webhook no Dashboard Stripe
3. Reenvie eventos falhados do Dashboard Stripe
4. Verifique logs da aplicacao para erros

Modo de teste nao funciona

Causa: Chaves de teste nao configuradas

Solucao:

1. Adicione STRIPE_TEST_SECRET_KEY e STRIPE_TEST_PUBLISHABLE_KEY
2. Verifique se as chaves comecam com sk_test_ e pk_test_
3. Verifique se o usuario tem e-mail @levyelectric.com ou funcao super_admin

Melhores Praticas de Seguranca

1. Nunca registre numeros de cartao completos - Apenas last4 e armazenado
2. Rotacione segredos de webhook - Mude regularmente
3. Use chaves de teste/ao vivo separadas - Nunca misture ambientes
4. Ative Radar - Deteccao de fraude do Stripe
5. Monitore anomalias - Configure alertas para atividade incomum
6. Conformidade PCI - Nunca processe dados brutos de cartao no servidor

Proximos Passos

• Metodos de Pagamento - Gerenciar metodos de pagamento de clientes
• Reembolsos Automaticos - Como reembolsos automaticos funcionam
• Cobrancas de Danos - Cobrar clientes por danos