Carteira e Pagamentos

Este guia cobre o sistema de carteira de clientes, metodos de pagamento, funcionalidade de recarga automatica e processamento de pagamentos. Compreender estes sistemas e essencial para operadores na solucao de problemas de cobranca e para clientes no gerenciamento de suas preferencias de pagamento.

---

Visao Geral

O sistema de pagamento consiste em tres componentes principais:

1. Carteira do Cliente - Uma conta de saldo para pagamentos de viagens
2. Metodos de Pagamento - Cartoes de credito/debito armazenados vinculados ao Stripe
3. Recarga Automatica - Reabastecimento automatico de carteira quando o saldo esta baixo

Viagens sao pagas pelo saldo da carteira. Se o saldo for insuficiente, o sistema pode cobrar automaticamente o metodo de pagamento padrao do cliente.

---

Carteira do Cliente

Como a Carteira Funciona

Cada cliente tem um saldo de carteira que:

• Armazena saldo em reais
• E usado para pagar viagens
• Pode ser recarregado manual ou automaticamente
• Recebe creditos de codigos promocionais, indicacoes e resgate de pontos de fidelidade

Fluxo de Saldo da Carteira:

Creditos ENTRANDO:
  - Recarga manual (cliente adiciona saldo)
  - Recarga automatica (automatica quando baixo)
  - Resgate de codigo promocional
  - Bonus de indicacao
  - Resgate de pontos de fidelidade
  - Creditos de atendimento ao cliente

Debitos SAINDO:
  - Cobrancas de viagem
  - Compras de assinatura
  - Compras de pacotes

Exibicao do Saldo da Carteira

Clientes veem seu saldo de carteira:

• Na tela inicial do app movel
• Antes de iniciar uma viagem
• Em recibos de viagem
• Nas configuracoes da conta

Formato: Sempre exibido em reais com 2 casas decimais (ex: "R$ 25,00")

Requisitos de Saldo Minimo

Para iniciar uma viagem, clientes devem ter:

• Saldo positivo na carteira, OU
• Metodo de pagamento valido para recarga automatica, OU
• Assinatura/pacote ativo cobrindo a viagem

---

Recarga Manual

Fluxo de Recarga do Cliente

1. Cliente abre secao de Carteira/Pagamento
2. Seleciona ou insere valor de recarga
3. Escolhe metodo de pagamento
4. Confirma pagamento
5. Saldo da carteira e atualizado imediatamente

Valores de Recarga

Operadores podem configurar valores predefinidos:

Processamento de Recarga

Recargas sao processadas via Stripe:

1. Criar PaymentIntent com valor
2. Confirmar com metodo de pagamento do cliente
3. Em caso de sucesso: Aumentar saldo da carteira
4. Criar registro de transacao de carteira
5. Enviar confirmacao (e-mail/push)

---

Recarga Automatica

Como a Recarga Automatica Funciona

A recarga automatica cobra automaticamente o cliente quando seu saldo de carteira cai abaixo de um limite:

Se wallet_balance ≤ limite:
  Cobrar metodo de pagamento padrao com valor de recarga
  Adicionar saldo a carteira

Quando e acionada:

• Antes do inicio da viagem (se saldo insuficiente)
• Apos fim da viagem (se saldo ficou negativo)
• Durante a viagem (para cobranca em tempo real)

Requisitos de Configuracao

A recarga automatica requer AMBOS:

1. Opt-in do cliente - Cliente ativa recarga automatica em suas configuracoes
2. Subconta ativada - Operador ativa recarga automatica para o local

Opcoes de Configuracao

Configuracoes da Subconta:

Configuracao de Exemplo:

• Limite: R$ 5,00 (500 centavos)
• Valor de recarga: R$ 15,00 (1500 centavos)

Quando a carteira cai para R$ 5 ou menos, o sistema cobra automaticamente R$ 15.

Fluxo de Recarga Automatica

1. Verificar se cliente permite recarga automatica (customer.auto_topup_enabled)
2. Verificar se subconta permite recarga automatica (subaccount.auto_topup_enabled)
3. Obter limite e valor das configuracoes da subconta
4. Se wallet_balance ≤ limite:
   a. Adquirir bloqueio (evitar cobrancas duplicadas)
   b. Obter metodo de pagamento padrao do cliente
   c. Criar PaymentIntent Stripe
   d. Confirmar pagamento (off_session)
   e. Aumentar saldo da carteira
   f. Registrar transacao
   g. Liberar bloqueio

Protecao contra Concorrencia

O sistema evita cobrancas duplicadas atraves de bloqueio de banco de dados:

Fluxo de Bloqueio:

1. Tentar adquirir bloqueio (TTL de 2 minutos)
2. Se bloqueio adquirido, prosseguir com cobranca
3. Se bloqueio existe (outro processo cobrando), aguardar e verificar aumento de saldo
4. Liberar bloqueio apos conclusao

Tratamento de Erros

---

Metodos de Pagamento

Armazenando Metodos de Pagamento

Metodos de pagamento sao armazenados via Stripe:

1. Cliente insere detalhes do cartao
2. Cartao e tokenizado pelo Stripe.js (compativel com PCI)
3. PaymentMethod e anexado ao cliente Stripe
4. Referencia e armazenada no banco de dados local

Tabela de Metodos de Pagamento

Metodo de Pagamento Padrao

Um metodo de pagamento e marcado como padrao:

• Usado para recarga automatica
• Usado para recarga manual (a menos que outro seja selecionado)
• Usado para cobrancas de assinatura

Definindo padrao:

1. Cliente seleciona "Definir como padrao" no app
2. Sistema atualiza flag is_default
3. Sincroniza com invoice_settings.default_payment_method do Stripe

Gerenciando Metodos de Pagamento

Adicionar cartao:

1. Cliente toca em "Adicionar metodo de pagamento"
2. Stripe Elements captura detalhes do cartao
3. Cartao e validado e tokenizado
4. PaymentMethod e criado e armazenado

Remover cartao:

1. Cliente seleciona cartao a remover
2. Sistema verifica se nao e o unico cartao (se recarga automatica ativada)
3. PaymentMethod e desanexado do cliente Stripe
4. Registro local e deletado

Atualizar cartao: Cartoes nao podem ser atualizados - cliente deve adicionar novo cartao e remover o antigo.

---

Transacoes de Carteira

Tipos de Transacao

Registro de Transacao

Visualizando Historico de Transacoes

Clientes podem ver seu historico de transacoes:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  HISTORICO DA CARTEIRA

  Hoje
  ─────
  Viagem concluida              -R$ 7,35
  Saldo: R$ 17,65

  Ontem
  ─────────
  Recarga automatica            +R$ 15,00
  Saldo: R$ 25,00

  Viagem concluida              -R$ 8,50
  Saldo: R$ 10,00

  23 Dez.
  ─────────
  Codigo promocional NATAL10    +R$ 10,00
  Saldo: R$ 18,50

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

---

Fluxo de Pagamento de Viagem

Verificacao de Saldo no Inicio da Viagem

Quando um cliente inicia uma viagem:

1. Verificar saldo da carteira - Esta acima de R$ 0?
2. Verificar elegibilidade de recarga automatica - Esta ativada e tem metodo de pagamento?
3. Verificar cobertura - Assinatura/pacote cobre a viagem?

Se nenhum dos acima for satisfeito, a viagem nao pode iniciar.

Pagamento no Fim da Viagem

Quando uma viagem termina:

1. Calcular cobranca final da viagem
2. Verificar saldo atual da carteira
3. Se saldo >= cobranca:
   - Debitar da carteira
   - Registrar transacao
4. Se saldo < cobranca E recarga automatica ativada:
   - Processar recarga automatica primeiro
   - Depois debitar cobranca da viagem
5. Se saldo < cobranca E sem recarga automatica:
   - Debitar saldo disponivel
   - Registrar valor pendente
   - Agendar tentativa de pagamento

Sistema de Tentativa de Pagamento

Quando um cliente tem valor pendente:

1. Agendar tentativa - Adicionar a fila de tentativas em segundo plano
2. Tentar cobrar - Tentar coletar ao longo do tempo
3. Notificacao - Alertar cliente sobre pagamento falhado
4. Restricao de conta - Bloquear novas viagens ate saldo pago

Cronograma de Tentativas:

---

Dashboard do Operador

Visualizando Carteira do Cliente

Na visualizacao de detalhes do cliente:

Ajustes Manuais de Carteira

Operadores podem ajustar o saldo da carteira:

Adicionar saldo:

• Gestos de atendimento ao cliente
• Reembolsos por problemas de servico
• Creditos promocionais

Remover saldo:

• Correcoes de fraude
• Correcoes de erros

Todos os ajustes requerem:

• Valor
• Motivo/descricao
• Autenticacao do operador

Exportacao de Transacoes

Exportar transacoes de carteira para:

• Reconciliacao contabil
• Disputas de clientes
• Fins de auditoria

---

Integracao Stripe

Modo de Teste vs. Ao Vivo

O sistema suporta ambos os modos Stripe:

Selecao de Modo de Teste:

• E-mails @levyelectric.com usam modo de teste
• Todos os outros clientes usam modo ao vivo

Objetos Stripe Usados

Webhooks

Webhooks do Stripe atualizam registros locais:

---

Consideracoes de Seguranca

Conformidade PCI

• Numeros de cartao nunca tocam nossos servidores
• Toda captura de cartao via Stripe.js/Elements
• Apenas referencias tokenizadas sao armazenadas

Privacidade de Dados

• Saldo de carteira criptografado em repouso
• Acesso ao historico de transacoes controlado
• Acesso a metodos de pagamento restrito

Prevencao de Fraude

• Limites de taxa para recargas
• Deteccao de atividade incomum
• Limites de revisao manual

---

Referencia Tecnica

Tabelas de Banco de Dados

customers (Campos de Carteira)

payment_methods

wallet_transactions

subaccounts (Campos de Recarga Automatica)

Funcoes Principais

Endpoints de API

---

Solucao de Problemas

Recarga Automatica Nao Funciona

1. Verificar configuracao do cliente - auto_topup_enabled esta true?
2. Verificar configuracao da subconta - Recarga automatica ativada para local?
3. Verificar metodo de pagamento - Existe cartao padrao?
4. Verificar cliente Stripe - stripe_customer_id e valido?
5. Revisar status de bloqueio - Existe bloqueio obsoleto bloqueando?

Pagamento Falhou

1. Verificar erro Stripe - Cartao recusado? Expirado? 3DS necessario?
2. Verificar metodo de pagamento - Ainda e valido no Stripe?
3. Verificar status da conta - Conta Stripe esta ativa?
4. Verificar idempotencia - Mesma cobranca foi tentada duas vezes?

Saldo de Carteira Incorreto

1. Revisar historico de transacoes - Quais transacoes ocorreram?
2. Verificar cobrancas pendentes - Existem pagamentos em andamento?
3. Verificar cobrancas de viagem - Viagens foram cobradas corretamente?
4. Verificar duplicatas - Existem transacoes duplicadas?

Nao Consegue Iniciar Viagem

1. Verificar saldo da carteira - Esta R$ 0 ou negativo?
2. Verificar recarga automatica - Esta ativada e funcional?
3. Verificar metodo de pagamento - Existe cartao valido?
4. Verificar saldo pendente - Existem cobrancas nao pagas?

---