Pagamentos da Seguradora e a Carteira

Quando um sinistro Levy Cover e aprovado e pago, os fundos vem da seguradora, nao da Levy. A seguradora escolhe o destino (cartao, banco, PayPal ou carteira Levy) com base na selecao do ciclista no momento do sinistro. Esta pagina descreve o que acontece para cada destino - especialmente o caso da carteira Levy, que tem regras contabeis estritas.

Destinos de pagamento

A seguradora suporta quatro destinos de pagamento:

Para os tres primeiros, a Levy recebe um webhook payout.completed apenas para visibilidade - os fundos vao da seguradora para o ciclista diretamente, e o livro razao da Levy nao e afetado. O status em insurance_claims se move para paid e o operador o ve na lista de sinistros.

O caso da carteira Levy e diferente. Os fundos fluem da seguradora para a Levy, e a Levy lanca um credito na carteira para o ciclista. Esta pagina foca nesse caso.

A regra de pagamento na carteira

Por que o requisito estrito:

1. Auditoria. Cada credito na carteira deve rastrear de volta a um evento documentado. Reembolsos de premio rastreiam para uma linha ride_refunds; pagamentos de sinistro rastreiam para uma linha insurance_claims. Ambos os caminhos exigem que sua referencia exista.
2. Anti-abuso. Sem a protecao, um cron mal configurado, um erro de digitacao em um script ou um operador malicioso poderia criar creditos na carteira tipados como pagamentos de seguro, mas nao correspondendo a nenhum sinistro real. A imposicao no nivel de BD previne isso.
3. Reconciliacao de liquidacao. A Levy reconcilia pagamentos na carteira contra o arquivo de liquidacao da seguradora mensalmente. Discrepancias indicam creditos mal lancados e sao expostas como tarefas de operacoes.

Para que serve insurance_claim_payout

wallet_transactions.reference_type = 'insurance_claim_payout' e especificamente para pagamentos de sinistro emitidos pela seguradora. Nao e para:

• Reembolsos de premio. Esses referenciam linhas ride_refunds. Veja Reembolsos de Premio via Viagem.
• Creditos de cortesia. Estes tem seu proprio tipo de referencia e explicitamente nao sao seguro.
• Creditos na carteira iniciados pelo operador para tornar um ciclista inteiro por um problema fora da plataforma.

Se voce se ver alcancando insurance_claim_payout mas nao tem uma linha insurance_claims aprovada com status IN ('approved', 'paid'), o credito e do tipo errado. Pare e escolha o caminho correto.

O fluxo para um pagamento destinado a carteira

1. A seguradora (Cover Genius) aprova o sinistro e o ciclista elegeu a carteira Levy como destino.
2. A seguradora emite um webhook payout.completed com:
   • claim_id correspondendo ao ID de sinistro da seguradora armazenado em insurance_claims.carrier_claim_id
   • payout_amount e payout_currency
   • payout_destination = "levy_wallet"
3. O handler do webhook em src/lib/insurance/webhook-handlers.ts:
   • Verifica a assinatura.
   • Procura insurance_claims por carrier_claim_id. Se nenhuma linha existir, o webhook e rejeitado (esta e a protecao).
   • Insere uma linha insurance_payouts referenciando o sinistro.
   • Chama creditWalletForRefund com reference_type = 'insurance_claim_payout' e reference_id = insurance_claims.id.
4. O helper de carteira verifica se a linha insurance_claims existe com o status esperado e lanca o credito.
5. O ciclista recebe uma notificacao push: "Seu pagamento Levy Cover de X USD foi adicionado a sua carteira."

O que rides.net_deposited NAO faz

Pagamentos de sinistro nao tocam rides.net_deposited na viagem subjacente. A viagem ja foi contabilizada corretamente:

• O premio foi cobrado.
• A rede da seguradora foi reservada.
• Comissoes Levy e operador foram registradas.
• A viagem esta fechada.

O pagamento do sinistro e um evento de seguro a jusante. Acontece porque uma apolice valida fez seu trabalho. A contabilidade original da viagem estava correta e permanece correta.

Isso e o oposto de um reembolso de premio, que toca net_deposited porque a viagem subjacente precisa de correcao (o premio nao deveria ter sido mantido).

Comparacao lado a lado

Os dois caminhos parecem superficialmente similares - ambos terminam em um credito na carteira referenciando alguma outra linha - mas o significado e a contabilidade a jusante sao completamente diferentes.

Lancamentos de carteira falhados

Se o credito na carteira falhar (por ex. a conta do ciclista esta fechada):

1. A linha insurance_payouts e criada com wallet_transaction_id = NULL.
2. O evento payout.completed e registrado em insurance_webhook_log com processed_at IS NULL.
3. Operacoes investiga - tipicamente o ciclista deve entrar em contato para se recuperar, ou a Levy relata o caminho da carteira como indisponivel para que a seguradora redirecione para cartao/banco.

A seguradora lida com o redirecionamento. A Levy nao inicia um reembolso em um pagamento falhado - esses fundos pertencem a seguradora redirecionar, nao a Levy reembolsar.

Liquidacao da Levy com a seguradora

Pagamentos na carteira sao lancados imediatamente para o ciclista. Nos bastidores, a Levy liquida com a seguradora mensalmente atraves do sistema de reconciliacao da seguradora (XPay para Cover Genius). O fluxo de caixa e:

• Seguradora deve a Levy: a soma dos pagamentos destinados a carteira no mes.
• Levy deve a seguradora: a soma dos premios liquidos da seguradora cobrados em apolices vinculadas no mes.
• Estes se compensam, e Levy ou a seguradora paga a diferenca.

Esta liquidacao e tratada no nivel da plataforma; subcontas individuais veem apenas os eventos de pagamento por sinistro, nao a compensacao.

---