Carrier Payouts and the Wallet

When a Levy Cover claim is approved and paid, the funds come from the carrier, not from Levy. The carrier chooses the destination (card, bank, PayPal, or Levy wallet) based on the rider's selection at claim time. This page describes what happens for each destination - especially the Levy wallet case, which has strict accounting rules.

Payout destinations

The carrier supports four payout destinations:

For the first three, Levy receives a payout.completed webhook for visibility only - the funds go from the carrier to the rider directly, and Levy's ledger is unaffected. The status on insurance_claims moves to paid and the operator sees it in the claims queue.

The Levy wallet case is different. Funds flow from the carrier to Levy, and Levy posts a wallet credit to the rider. This page focuses on that case.

The wallet payout rule

Why the strict requirement:

1. Audit. Every wallet credit must trace back to a documented event. Premium refunds trace to a ride_refunds row; claim payouts trace to an insurance_claims row. Both paths require their reference to exist.
2. Anti-abuse. Without the guard, a misconfigured cron, a typo in a script, or a malicious operator could create wallet credits typed as insurance payouts but not corresponding to any actual claim. The DB-level enforcement prevents this.
3. Settlement reconciliation. Levy reconciles wallet payouts against the carrier's settlement file monthly. Mismatches indicate misposted credits and are surfaced as ops tasks.

What insurance_claim_payout is for

wallet_transactions.reference_type = 'insurance_claim_payout' is specifically for carrier-issued claim payouts. It is not for:

• Premium refunds. Those reference ride_refunds rows. See Premium Refunds via the Ride.
• Goodwill credits. Those have their own reference type and are explicitly not insurance.
• Operator-initiated wallet credits to make a rider whole for an off-platform issue.

If you find yourself reaching for insurance_claim_payout but you do not have an approved insurance_claims row with status IN ('approved', 'paid'), the credit is the wrong type. Stop and choose the correct path.

The flow for a wallet-destined payout

1. The carrier (Cover Genius) approves the claim and the rider elected Levy wallet as the destination.
2. The carrier issues a payout.completed webhook with:
   • claim_id matching the carrier's claim ID stored on insurance_claims.carrier_claim_id
   • payout_amount and payout_currency
   • payout_destination = "levy_wallet"
3. The webhook handler in src/lib/insurance/webhook-handlers.ts:
   • Verifies the signature.
   • Looks up insurance_claims by carrier_claim_id. If no row exists, the webhook is rejected (this is the guard).
   • Inserts an insurance_payouts row referencing the claim.
   • Calls creditWalletForRefund with reference_type = 'insurance_claim_payout' and reference_id = insurance_claims.id.
4. The wallet helper verifies the insurance_claims row exists with the expected status and posts the credit.
5. The rider receives a push notification: "Your Levy Cover payout of $X has been added to your wallet."

What rides.net_deposited does NOT do

Claim payouts do not touch rides.net_deposited on the underlying ride. The ride was already accounted correctly:

• Premium was charged.
• Carrier net was set aside.
• Levy and operator commissions were recorded.
• The ride is closed.

The claim payout is a downstream insurance event. It happens because a valid policy did its job. The original ride accounting was correct and stays correct.

This is the opposite of a premium refund, which does touch net_deposited because the underlying ride needs correction (the premium should not have been kept).

Side-by-side comparison

The two paths look superficially similar - both end in a wallet credit referencing some other row - but the meaning and the accounting downstream are completely different.

Failed wallet posts

If the wallet credit fails (e.g. the rider account is closed):

1. The insurance_payouts row is created with wallet_transaction_id = NULL.
2. The payout.completed event is logged in insurance_webhook_log with processed_at IS NULL.
3. Ops investigates - typically the rider must reach out to recover, or Levy reports the wallet path as unavailable so the carrier reroutes to card/bank.

The carrier handles the reroute. Levy does not initiate a refund on a failed payout - those funds are the carrier's to redirect, not Levy's to refund.

Levy's settlement with the carrier

Wallet payouts post immediately for the rider. Behind the scenes, Levy settles with the carrier monthly via the carrier's reconciliation system (XPay for Cover Genius). The cash flow is:

• Carrier owes Levy: the sum of wallet-destined payouts in the month.
• Levy owes carrier: the sum of carrier-net premiums collected on bound policies in the month.
• These net out, and Levy or the carrier pays the difference.

This settlement is handled at the platform level; individual subaccounts see only the per-claim payout events, not the netting.

---