Carteiras e Creditos de Bonus de Clientes

Cada cliente tem um unico saldo de carteira (wallet_balance) que financia as corridas. Este guia cobre como a carteira funciona, como os operadores podem ajusta-la, como a recarga automatica e configurada e como os reembolsos interagem com a carteira.

O Saldo da Carteira

Cada cliente tem exatamente um saldo efetivo: o saldo da carteira. Todos os ajustes manuais (creditos, bonus, taxas, debitos) e fluxos automatizados (cobrancas de corrida, reembolsos, recargas automaticas) aumentam ou reduzem esse unico saldo.

Voce tambem vera uma coluna Bonus na lista de clientes e na pagina de detalhes do cliente. Este e um campo de exibicao legado preenchido por importacoes de clientes — ele nao e consumido separadamente durante o pagamento da corrida e nao e modificado pela acao "Adicionar Bonus" do painel. Trate-o como contexto historico, nao como um saldo ativo.

Como os Pagamentos sao Aplicados a uma Corrida

Saldo Minimo para Iniciar uma Corrida

Clientes precisam ter pelo menos $0,50 na carteira para iniciar uma corrida, a menos que se qualifiquem para uma isencao.

Isencao da verificacao de saldo (iniciar corrida com $0 na carteira): o cliente deve ter ambos

1. Uma assinatura ativa ou um pacote de corridas ativo com corridas/minutos restantes, e
2. Um metodo de pagamento salvo.

Saldos Negativos

A carteira pode ficar negativa. Isso acontece quando:

• Uma Cobranca de Taxa (Charge Fee) e aplicada e excede o saldo atual.
• O custo da corrida excede o saldo da carteira e a cobranca do cartao falha.
• O operador usa Reduzir Saldo (Reduce Balance) por um valor maior que o saldo atual.

Quando uma Cobranca de Taxa faz o saldo passar de positivo para negativo, o cliente recebe automaticamente uma notificacao push informando sobre o saldo negativo.

Acessando Informacoes da Carteira

Lista de Clientes

A lista mostra o saldo da carteira de cada cliente e o valor legado de bonus (se houver) em colunas separadas.

Pagina de Detalhes do Cliente

Navegue ate Dashboard > Clientes > [Cliente] para ver:

• Saldo atual da carteira e valor de bonus
• Um menu suspenso Carteira na barra de acoes com: Adicionar Bonus, Cobrar Taxa, Reduzir Saldo
• Um link Ver Atividade da Carteira para o historico completo de transacoes

Pagina de Atividade da Carteira

A pagina de atividade lista cada linha de wallet_transactions do cliente, incluindo:

• Data e descricao
• Tipo de referencia (ride, topup, manual_bonus, manual_charge, manual_reduce_balance, stripe_charge, etc.)
• Valor (creditos em verde, debitos em vermelho)
• balance_after corrente

Adicionando Creditos a Carteira

O painel expoe tres acoes no menu suspenso Carteira do cliente. Todas as tres gravam no unico wallet_balance e registram uma linha em wallet_transactions.

Adicionar Bonus

Credito promocional ou de cortesia. Aumenta o saldo da carteira.

• Transacao: type: 'credit', reference_type: 'manual_bonus'
• Notificacao: nenhuma
• API: POST /api/customers/bonus

{
  "customer_uuid": "customer-uuid",
  "amount_usd": 5.00
}

Campos de identificacao aceitos (forneca pelo menos um): customer_uuid, customer_number, auth_uid, email ou customer_identifier.

Motivos Comuns para Adicionar Creditos

Cobrando Taxas e Reduzindo Saldo

Cobrar Taxa (Charge Fee)

Para danos, equipamento perdido, violacoes de estacionamento e penalidades similares.

• Transacao: type: 'debit', reference_type: 'manual_charge'
• Pode ficar negativo: sim
• Notificacao: notificacao push enviada quando o saldo passa de positivo para negativo
• Permissao: requer customer:charge — analistas e tecnicos de servico sao bloqueados
• API: POST /api/customers/charge

{
  "customer_uuid": "customer-uuid",
  "amount_usd": 25.00
}

Reduzir Saldo (Reduce Balance)

Para correcoes silenciosas e ajustes que nao devem notificar o cliente.

• Transacao: type: 'debit', reference_type: 'manual_reduce_balance'
• Pode ficar negativo: sim (mesmo comportamento que Charge Fee)
• Notificacao: nunca
• Permissao: requer customer:charge
• API: POST /api/customers/reduce-balance

{
  "customer_uuid": "customer-uuid",
  "amount_usd": 10.00
}

Charge Fee vs. Reduce Balance

Reembolsos: Sempre Contra a Corrida

Use um destes dois endpoints dependendo da situacao:

Ajuste de tarifa — quando a corrida foi cobrada em excesso (por exemplo, cobraram o cliente por tempo que ele nao usou):

POST /api/rides/[id]/adjust-fare
{
  "newTotalCost": 8.50,
  "reason": "Ajustado para refletir a duracao real da corrida"
}

Isto recalcula o imposto, ajusta a corrida, credita a carteira se o cliente pagou a mais e atualiza net_deposited.

Reembolso — quando a tarifa esta correta mas o cliente merece o dinheiro de volta (ma experiencia, compensacao, etc.):

POST /api/rides/[id]/refunds
{
  "destination": "wallet",
  "mode": "full",
  "reason": "Compensacao ao passageiro"
}

destination pode ser wallet ou card. mode pode ser full ou partial (com um amount). A API reembolsa contra o que foi efetivamente pago (cartao ou carteira), registra em ride_refunds e atualiza net_deposited.

Para creditos de cortesia nao vinculados a uma corrida especifica, use Adicionar Bonus na pagina de detalhes do cliente.

Processamento em Massa de Carteiras

A acao Bulk Wallet Processing na lista de clientes nao e uma ferramenta de upload de creditos. E uma ferramenta de cobranca que debita os metodos de pagamento salvos de clientes com saldo de carteira negativo.

• Selecione clientes manualmente, ou use Selecionar Todos para atingir todos que correspondem aos filtros atuais com saldo negativo e cliente Stripe cadastrado.
• Clique em Process — o sistema tenta cobrar o metodo de pagamento salvo de cada cliente pelo valor necessario para zerar a carteira.
• Os resultados mostram cada cliente como scheduled, skipped, already_exists ou error.

Nao ha hoje um fluxo de upload via CSV para adicionar creditos em massa — adicione-os um cliente por vez pelo painel ou use o endpoint /api/customers/bonus via script.

Transacoes da Carteira

Cada mudanca em wallet_balance grava uma linha em wallet_transactions. Transacoes tem um type (credit ou debit) e um reference_type que categoriza a origem.

Valores comuns de reference_type

A UI de atividade da carteira agrupa e rotula esses itens para os operadores — os valores brutos acima sao o que voce vera no banco de dados e nas respostas da API.

Recarga Automatica (Auto Top-up)

A recarga automatica reabastece a carteira do cliente automaticamente quando o saldo cai abaixo de um limite, cobrando seu metodo de pagamento padrao.

Como Funciona

1. O saldo da carteira do cliente cai abaixo do limite (tipicamente durante uma verificacao no inicio ou pagamento da corrida).
2. O sistema cobra o metodo de pagamento padrao pelo valor de recarga configurado.
3. A carteira e creditada.
4. O cliente recebe uma notificacao push confirmando a recarga.

Configuracao (ambos devem ser verdadeiros)

• Configuracao do cliente: auto_topup_enabled no registro do cliente — os clientes optam durante o cadastro (apresentamos a recarga automatica como forma de evitar que o veiculo seja desabilitado no meio da corrida; quase todos os clientes ativam).
• Configuracao da subconta: auto_topup_enabled na subconta, com auto_topup_amount_cents e auto_topup_threshold_cents.

Valores Padrao

Exemplo: quando o saldo do cliente cai abaixo de $5,00, o sistema cobra $15,00 e credita a carteira.

Seguranca

• Locks no banco de dados evitam que tentativas simultaneas de recarga automatica cobrem duas vezes.
• Chaves de idempotencia do Stripe evitam cobrancas duplicadas em retries de rede.
• O limite e re-verificado apos adquirir o lock.
• Contas @levyelectric.com usam o modo de teste do Stripe.

Solucao de Problemas da Recarga Automatica

1. Verifique que o cliente tem auto_topup_enabled.
2. Verifique que a subconta tem auto_topup_enabled e valores coerentes de amount/threshold.
3. Confirme que o cliente tem um metodo de pagamento padrao valido.
4. Verifique recusas no Stripe.
5. Procure em wallet_transactions por entradas recentes de topup.

Relatorios

Metricas de Resumo

O cabecalho da lista de clientes mostra o valor total em carteiras e o valor total de bonus na visao filtrada.

Auditoria de Mudancas na Carteira

• Abra a pagina de Atividade da Carteira do cliente para ver todas as transacoes com timestamps e balance_after.
• Compare debitos de ride com o registro da corrida — o net_deposited da corrida deve conciliar com debito da carteira + cobranca no cartao menos quaisquer reembolsos.
• Para ajustes manuais, o user.id do operador e registrado como reference_id nas transacoes manual_bonus / manual_charge; o painel resolve isso para o nome do funcionario.

Boas Praticas

Para Operadores

1. Documente cada ajuste manual — a identidade do operador e armazenada, mas um motivo na descricao ajuda em auditorias futuras.
2. Use o fluxo de reembolso de corrida para problemas de corrida — nunca compense problemas de corrida com um credito direto na carteira, ou os repasses aos parceiros e a contabilidade de impostos ficarao errados.
3. Reserve Adicionar Bonus para promocoes e cortesia nao vinculadas a uma corrida especifica.
4. Restrinja permissoes — apenas roles de admin e acima devem ter customer:charge.

Para o Atendimento ao Cliente

1. Verifique o saldo atual e a atividade recente da carteira antes de adicionar ou remover credito.
2. Ao ajustar por um problema de corrida, abra a corrida e use Ajustar Tarifa ou Reembolso em vez do menu suspenso Carteira.
3. Alinhe expectativas com o cliente: creditos sao aplicados automaticamente na proxima corrida.

Solucao de Problemas

Credito nao aparece no app do cliente

• Confirme que a transacao esta na atividade da carteira do cliente.
• Peca ao cliente para fechar e reabrir o app.
• Verifique que voce ajustou o cliente correto (verifique customer_number / email).

Saldo da carteira parece errado

• Revise transacoes recentes por debitos inesperados ou creditos duplicados.
• Verifique o historico de corridas por deducoes automaticas (reference_type: 'ride').
• Se o saldo nao bater com a soma das transacoes, a coluna customers.wallet_balance pode estar fora de sincronia com wallet_transactions — escale.

Cliente diz que seu reembolso de corrida nao foi aplicado

• Abra a pagina de detalhes da corrida e verifique a secao Reembolsos.
• Confirme que o reembolso foi processado via /api/rides/[id]/refunds ou /api/rides/[id]/adjust-fare (nao um credito direto na carteira).
• Compare a atividade da carteira do cliente com uma entrada ride_refund correspondente.