Metodos de Pagamento de Clientes

O sistema de metodos de pagamento permite que clientes armazenem e gerenciem seus cartoes de pagamento para usar os servicos Levy Fleets. Este guia cobre como administradores podem gerenciar metodos de pagamento em nome dos clientes atraves do painel, bem como como o sistema lida com cartoes nos bastidores.

Como Metodos de Pagamento Funcionam

Arquitetura de Armazenamento

Metodos de pagamento sao armazenados em dois locais por razoes de seguranca e eficiencia:

1. Stripe - Os dados reais do metodo de pagamento (numero do cartao, data de validade, CVC) sao armazenados de forma segura pelo Stripe
2. Banco de Dados Levy - Apenas metadados nao sensiveis sao armazenados localmente:
   • ID do metodo de pagamento Stripe
   • Bandeira do cartao (Visa, Mastercard, etc.)
   • Ultimos 4 digitos
   • Tipo do cartao
   • Status de padrao

Esta arquitetura garante conformidade PCI enquanto permite consultas locais eficientes.

Fluxo de Metodo de Pagamento

Quando um cliente adiciona um cartao:

Esquema do Banco de Dados

Tabela de Metodos de Pagamento

Gerenciando Metodos de Pagamento no Painel

Acessando Metodos de Pagamento

1. Navegue ate Painel > Clientes
2. Clique em um cliente para visualizar seu perfil
3. Encontre a secao Metodos de Pagamento

Visualizando Cartoes

A secao de metodos de pagamento mostra:

• Bandeira do cartao e ultimos 4 digitos (ex: "VISA **** 4242")
• Data em que o cartao foi adicionado
• Badge de padrao para o cartao primario
• Botao de excluir para cada cartao

Adicionando um Cartao

Indicacao de Modo de Teste

Ao adicionar cartoes para contas de teste:

• Um banner amarelo mostra "Modo de teste ativo"
• Use numeros de cartao de teste do Stripe (veja abaixo)
• Nenhuma cobranca real sera feita

Excluindo um Cartao

1. Clique no icone de lixeira ao lado do cartao
2. Confirme a exclusao no dialogo
3. O cartao e removido tanto do Stripe quanto do banco de dados

Modo de Teste

Quando o Modo de Teste Esta Ativo

O modo de teste e automaticamente ativado quando:

1. Usuarios Super Admin - Qualquer usuario com a funcao super_admin
2. E-mails Internos de Teste - Clientes com e-mail @levyelectric.com

Comportamento do Modo de Teste

No modo de teste:

• Usa chaves de API de teste do Stripe
• Cartoes sao armazenados no ambiente de teste do Stripe
• Nenhuma cobranca real e feita
• Setup Intents usam endpoints de teste
• Painel mostra "Modo de teste ativo"

Numeros de Cartao de Teste

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

Metodo de Pagamento Padrao

Selecao Automatica de Padrao

Quando um cliente adiciona seu primeiro metodo de pagamento, ele automaticamente se torna o padrao. Isso garante que sempre haja um metodo de pagamento utilizavel para:

• Recargas de carteira
• Cobrancas de recarga automatica
• Tentativas de pagamento

Como o Padrao e Determinado

1. Primeiro cartao adicionado e padrao
2. Se o cartao padrao for excluido, o cartao restante mais antigo se torna padrao

Como o Padrao e Usado

O metodo de pagamento padrao e usado para:

• Recarga Automatica - Reposicao automatica de carteira
• Tentativas de Pagamento - Recuperar saldos negativos de carteira
• Cobrancas Off-Session - Qualquer cobranca iniciada sem presenca do cliente

Integracao com Sistema de Tentativa de Pagamento

Metodos de pagamento desempenham um papel critico no sistema automatico de tentativa de pagamento para recuperar saldos negativos de carteira.

Como Metodos de Pagamento Sao Usados para Tentativas

Quando a carteira de um cliente fica negativa, o sistema cria um job de tentativa de pagamento que:

1. Primeiro Tenta o Metodo de Pagamento Padrao
2. Roda Atraves de Outros Cartoes ordenados por data de criacao (mais antigo primeiro)
3. Rastreia Quais Metodos Foram Tentados para evitar tentativas duplicadas dentro da mesma janela de agendamento
4. Reinicia o Ciclo ao mudar para um novo dia ou nova semana

Ordem de Rotacao de Metodos de Pagamento

1. Metodo de pagamento padrao (is_default = true)
2. Cartao nao-padrao mais antigo
3. Segundo cartao nao-padrao mais antigo
4. ... continua atraves de todos os cartoes

Importancia de Multiplos Cartoes

Clientes com multiplos metodos de pagamento tem maiores taxas de recuperacao de pagamento porque:

• Se um cartao for recusado, outros sao tentados automaticamente
• Cartoes diferentes podem ter limites de credito diferentes
• Problemas especificos de banco (bloqueios temporarios, alertas de fraude) nao bloqueiam completamente o pagamento

Integracao de Webhook

Metodos de pagamento tambem podem ser criados via webhooks do Stripe quando clientes adicionam cartoes atraves do app movel:

setup_intent.succeeded

Quando um SetupIntent e concluido do app movel:

1. Sistema busca o cliente por ID Stripe
2. Recupera detalhes do metodo de pagamento do Stripe
3. Salva metadados do cartao no banco de dados
4. Define como padrao se for o primeiro cartao

payment_intent.succeeded

Quando um pagamento e concluido com um novo metodo de pagamento:

1. Sistema verifica se o metodo de pagamento ja existe
2. Se nao, salva o novo metodo de pagamento
3. Atualiza o padrao do cliente se necessario

Integracao com App Movel

Adicionando Cartoes pelo App

O app movel usa o SDK nativo do Stripe:

1. App solicita uma Ephemeral Key do servidor
2. Stripe CustomerSheet ou PaymentSheet e apresentado
3. Cliente insere detalhes do cartao na UI nativa do Stripe
4. Em sucesso, webhook setup_intent.succeeded e disparado
5. Metodo de pagamento e salvo no banco de dados

Acoes de Pagamento no App

Consideracoes de Seguranca

Conformidade PCI

O sistema de metodos de pagamento mantem conformidade PCI atraves de:

1. Nunca Processar Dados Brutos de Cartao - Toda captura de cartao usa Stripe Elements/SDK
2. Armazenar Apenas Tokens - Apenas IDs de metodos de pagamento Stripe sao armazenados
3. Mascarar Numeros de Cartao - Apenas ultimos 4 digitos sao armazenados
4. Transmissao Segura - Todas as chamadas de API usam HTTPS
5. Verificacao de Webhook - Todos os webhooks do Stripe sao verificados por assinatura

Controle de Acesso

Operacoes de metodos de pagamento requerem usuarios autenticados com funcoes apropriadas:

Comportamento de Exclusao

Ao excluir um metodo de pagamento:

1. Desanexar do Stripe - Cartao e desanexado do cliente Stripe
2. Exclusao Local - Registro removido do banco de dados
3. Reatribuicao de Padrao - Se padrao foi excluido, o proximo mais antigo se torna padrao
4. Ambos Ambientes Tentados - Sistema tenta tanto Stripe ao vivo quanto de teste para limpeza

Solucao de Problemas

Problemas Comuns

"Falha ao inicializar formulario Stripe"

Causa: Criacao do Setup Intent falhou

Solucoes:

1. Verifique se as chaves de API do Stripe estao corretas
2. Verifique se o cliente tem um ID de cliente Stripe
3. Verifique o painel Stripe para limites de taxa

Cartao Nao Aparece Apos Adicionar

Causa: Registro falhou apos SetupIntent

Solucoes:

1. Verifique console do navegador para erros
2. Verifique se o webhook setup_intent.succeeded esta sendo recebido
3. Verifique banco de dados para metodos de pagamento orfaos

"Nenhum metodo de pagamento registrado" na Recarga Automatica

Causa: Cliente nao tem metodos de pagamento ou nenhum padrao

Solucoes:

1. Verifique tabela payment_methods para o cliente
2. Verifique se pelo menos um cartao tem is_default = true
3. Adicione um metodo de pagamento se nenhum existir

Modo de Teste Nao Funcionando

Causa: Chaves de teste nao configuradas

Solucoes:

1. Verifique se STRIPE_TEST_SECRET_KEY esta definida
2. Verifique se STRIPE_TEST_PUBLISHABLE_KEY esta definida
3. Garanta que usuario e super_admin ou cliente tem e-mail @levyelectric.com

Consultas de Diagnostico

Listar Metodos de Pagamento de um Cliente

SELECT
  pm.id,
  pm.brand,
  pm.last4,
  pm.is_default,
  pm.created_at,
  c.email
FROM payment_methods pm
JOIN customers c ON c.id = pm.customer_uuid
WHERE c.id = 'uuid-do-cliente-aqui'
ORDER BY pm.created_at;

Encontrar Clientes Sem Metodos de Pagamento

SELECT
  c.id,
  c.email,
  c.full_name,
  c.stripe_customer_id
FROM customers c
LEFT JOIN payment_methods pm ON pm.customer_uuid = c.id
WHERE pm.id IS NULL
  AND c.stripe_customer_id IS NOT NULL
ORDER BY c.created_at DESC
LIMIT 50;

Verificar Metodos de Pagamento Duplicados

SELECT
  stripe_payment_method_id,
  COUNT(*) as count
FROM payment_methods
GROUP BY stripe_payment_method_id
HAVING COUNT(*) > 1;

Melhores Praticas

Para Operadores

1. Incentivar Multiplos Cartoes - Clientes com cartoes de backup tem menos falhas de pagamento
2. Monitorar Cartoes Recusados - Acompanhar clientes cujos cartoes falham
3. Usar Modo de Teste - Sempre testar fluxos de cartao com cartoes de teste antes de producao

Para Suporte ao Cliente

1. Verificar Antes de Adicionar - Confirmar identidade do cliente antes de adicionar metodos de pagamento
2. Explicar o Processo - Ajudar clientes a entender por que cartoes sao necessarios
3. Documentar Problemas - Registrar problemas relacionados a cartao para solucao de problemas

Proximos Passos

• Configuracao Stripe - Configurar integracao Stripe
• Reembolsos Automaticos - Como reembolsos automaticos funcionam
• Cobrancas de Danos - Cobrar clientes por danos