Configuracao de Recarga Automatica

A recarga automatica reabastece automaticamente o saldo de carteira dos clientes quando cai abaixo de um limite configuravel. Isso garante que os clientes sempre possam iniciar e concluir viagens sem adicionar saldo manualmente.

Visao Geral

Quando ativado, o sistema monitora o saldo da carteira e cobra automaticamente o metodo de pagamento armazenado do cliente quando o saldo fica muito baixo. Isso cria uma experiencia de viagem sem interrupcoes onde os clientes nao precisam se preocupar em ficar sem saldo no meio de uma viagem.

Principais Recursos

• Cobranca automatica - Cobra o metodo de pagamento armazenado quando o saldo esta baixo
• Limite configuravel - Defina o ponto de acionamento para recargas automaticas
• Valor configuravel - Defina quanto e adicionado a cada vez
• Consentimento duplo obrigatorio - Tanto o operador quanto o cliente devem ativar
• Integracao Stripe - Pagamentos seguros off-session via Stripe
• Protecao contra concorrencia - Bloqueios de banco de dados impedem cobrancas duplicadas

Como Funciona

Saldo da carteira: R$ 4,50
Limite: R$ 5,00
Valor de recarga: R$ 15,00

1. Cliente inicia viagem
2. Sistema verifica: R$ 4,50 ≤ limite de R$ 5,00
3. Recarga automatica acionada
4. Stripe cobra R$ 15,00 no cartao padrao
5. Novo saldo: R$ 19,50
6. Viagem continua normalmente

Requisitos

A recarga automatica requer TODOS os seguintes:

Configuracao do Operador

Ativar Recarga Automatica

Opcoes de Configuracao

Nivel de Acionamento (Limite)

O saldo de carteira no qual a recarga automatica e ativada.

Recomendacoes:

• Defina o limite ligeiramente acima do custo medio de viagem
• Considere taxa de desbloqueio + duracao tipica de viagem
• Limites mais altos = cobrancas pequenas mais frequentes

Valor de Recarga

Quanto e adicionado a carteira cada vez.

Recomendacoes:

• Deve cobrir 2-4 viagens tipicas
• Equilibre conveniencia e taxas de transacao
• Valores maiores = menos transacoes

Melhores Praticas

1. Defina limite acima do custo da viagem - Garanta que os clientes possam completar pelo menos uma viagem
2. Equilibre valor vs. frequencia - Valores maiores significam menos taxas Stripe
3. Comunique aos clientes - Garanta que os clientes saibam que a recarga automatica esta disponivel
4. Monitore cobrancas recusadas - Verifique regularmente recargas automaticas falhadas

Experiencia do Cliente

Ativar Recarga Automatica

Clientes ativam a recarga automatica no app movel:

1. Abrir tela de Carteira
2. Tocar no botao de Recarga Automatica
3. Confirmar ativacao
4. Garantir que um metodo de pagamento padrao esteja salvo

O Que os Clientes Veem

• Botao para ativar/desativar recarga automatica
• Notificacao quando cobrancas de recarga automatica ocorrem
• Historico de transacoes mostra entradas de "Recarga Automatica"
• Saldo atual da carteira sempre visivel

Quando a Recarga Automatica Aciona

A recarga automatica e verificada nestes momentos:

Fluxo de Inicio de Viagem

1. Cliente toca em "Desbloquear" no veiculo
2. Sistema verifica saldo da carteira
3. Se saldo ≤ limite E recarga automatica ativada:
   a. Bloqueio adquirido para evitar cobrancas duplicadas
   b. PaymentIntent Stripe criado
   c. Metodo de pagamento padrao cobrado
   d. Saldo da carteira atualizado
   e. Bloqueio liberado
4. Viagem inicia normalmente

Fluxo de Fim de Viagem

1. Viagem termina, custo calculado: R$ 8,50
2. Carteira atual: R$ 4,00
3. Carteira insuficiente, recarga automatica acionada
4. R$ 15,00 adicionados -> Novo saldo: R$ 19,00
5. Custo da viagem deduzido: R$ 19,00 - R$ 8,50 = R$ 10,50
6. Cliente ve saldo final: R$ 10,50

Detalhes Tecnicos

Campos do Banco de Dados

Tabela Subaccounts:

Tabela Customers:

Protecao contra Concorrencia

O sistema usa bloqueios de banco de dados para evitar cobrar clientes multiplas vezes:

1. Antes de cobrar, adquirir bloqueio via RPC acquire_auto_topup_lock
2. Bloqueio tem TTL de 2 minutos (expira automaticamente se o processo falhar)
3. Se bloqueio ja estiver retido, aguardar e verificar se o saldo aumentou
4. Apos cobranca, liberar bloqueio via RPC release_auto_topup_lock
5. Chave de idempotencia impede cobrancas duplicadas no Stripe

Tratamento de Erros

Solucao de Problemas

Recarga Automatica Nao Funciona

1. Verificar configuracao da subconta - Verificar se auto_topup_enabled esta true nas configuracoes
2. Verificar configuracao do cliente - Verificar se cliente ativou no app
3. Verificar metodo de pagamento - Cliente precisa de cartao padrao armazenado
4. Verificar cliente Stripe - Cliente precisa de stripe_customer_id
5. Verificar saldo - Pode ja estar acima do limite

Cobrancas Duplicadas

O sistema impede duplicatas atraves de:

• Bloqueio de banco de dados no registro do cliente
• Chave de idempotencia do Stripe
• Re-verificacao de saldo apos aquisicao do bloqueio

Se duplicatas ocorrerem, verificar:

1. Falhas na liberacao de bloqueio nos logs
2. Processamento de webhook do Stripe
3. Problemas de conexao com banco de dados

Cobrancas Falhadas

Razoes comuns para falha na recarga automatica:

Modo de Teste

Para testes internos, o sistema usa automaticamente o modo de teste Stripe para enderecos de e-mail @levyelectric.com. Isso permite testar fluxos de recarga automatica sem cobrancas reais.

E-mail do cliente: test@levyelectric.com
-> Usa STRIPE_TEST_SECRET_KEY
-> Cartoes de teste funcionam (4242 4242 4242 4242)
-> Nenhuma cobranca real processada

Referencia da API

Verificar Capacidade de Recarga Automatica

import { canProcessAutoTopup } from '@/lib/auto-topup'

const canTopup = await canProcessAutoTopup(customerId, vehicleId)
// Retorna: boolean

Processar Recarga Automatica

import { processAutoTopup } from '@/lib/auto-topup'

const result = await processAutoTopup(customerId, vehicleId, skipThresholdCheck)
// Retorna: { success, amountCents, error?, newWalletBalance? }

Alternar Preferencia do Cliente (API Mobile)

POST /api/mobile/payment
{
  "action": "toggle-auto-topup",
  "enabled": true
}