Enabling Cover Genius

Cover Genius (XCover platform, Gig Cover product family) is the primary carrier behind Levy Cover. It already underwrites embedded insurance for Uber, Ola, Booking Holdings, and Hopper. It is licensed in 60+ countries and all 50 US states, and exposes a REST API for quote -> bind -> claim -> payout with signed webhooks and a sandbox.

This page covers the operator-facing and engineering-facing steps to enable Cover Genius for a Levy Fleets deployment.

How Levy fits into the Cover Genius model

Cover Genius operates a carrier-distributor model. Cover Genius holds the producer license; Levy Fleets is registered as a distributor partner under that license. This means:

• Levy is not an insurance carrier, MGA, or producer in its own right.
• Cover Genius owns underwriting, capital reserves, and claims adjudication.
• Levy is responsible for transparent disclosure to riders, accurate KYC (handled by Stripe Identity), and correct premium accounting.
• The distributor agreement defines commission, jurisdictions covered, payout terms, and termination rights.

Environment variables

Levy Cover reads two environment variables at runtime:

COVER_GENIUS_API_KEY=<your API key from the Cover Genius portal>
COVER_GENIUS_PARTNER_ID=<your partner ID from the Cover Genius portal>

Both are required. If either is missing, CoverGeniusClient throws CarrierNotConfiguredError and falls back to the mock client in non-production environments. In production, the missing-credentials state results in available: false for every quote, and the opt-in card never appears to riders.

See Carrier Credentials Setup for full credential lifecycle (rotation, sandbox vs production, Vercel env scopes).

Endpoints Levy uses

Every Levy POST to Cover Genius carries an Idempotency-Key header keyed on ride_id + operation. This protects against duplicate bindings or claims if a network retry happens mid-call.

Webhook registration

In the Cover Genius portal, register the webhook receiver URL:

https://fleets.levyelectric.com/api/webhooks/insurance/cover-genius

Levy verifies the webhook signature using Cover Genius's shared secret on every inbound event. Verification failures land in insurance_webhook_log with signature_verified = false and processed_at IS NULL, where ops can inspect them.

Duplicate deliveries are deduplicated by UNIQUE (carrier, event_id) - the router catches the duplicate-key error and returns { duplicate: true } so the carrier stops retrying.

Sandbox UAT

Cover Genius provides a full sandbox. To exercise it:

1. Set sandbox COVER_GENIUS_API_KEY in a preview environment.
2. Register the preview environment's webhook URL with the sandbox.
3. Run end-to-end:
   • Unlock a vehicle, accept the opt-in card.
   • Confirm ride_insurance_policies has a row with carrier_policy_id populated.
   • End the ride. Confirm the receipt shows the premium line item.
   • File a test claim from ride history.
   • Trigger sandbox webhooks for claim.approved and payout.completed.
   • Confirm insurance_claims.status transitions correctly.
   • If the payout destination is levy_wallet, confirm the wallet credit references the insurance_claims row, not a ride_refunds row.

Production cutover

When sandbox UAT is clean and Cover Genius has confirmed go-live:

1. Set production COVER_GENIUS_API_KEY and COVER_GENIUS_PARTNER_ID in Vercel production env.
2. Register the production webhook URL.
3. Flip the subaccount toggles you want live at /dashboard/insurance/settings.
4. Monitor the first 100 insured rides:
   • insurance_webhook_log should show signature_verified = true on every event.
   • The nightly carrier reconciliation cron (/api/cron/insurance-carrier-reconciliation) should report zero mismatches.
   • Claims queue at /dashboard/insurance/claims should be populated with any real claims.

Outage behavior

If the Cover Genius API is unreachable at unlock, Levy fails open: the ride is marked insurance_offered = false, no premium is charged, and the ride proceeds normally. This is deliberate. Blocking unlock on a carrier outage is unacceptable.

For more on what happens to bound policies and pending claims during an outage, see Troubleshooting.

Switching carriers per jurisdiction

The jurisdiction matrix can route different regions to different carriers. v2 introduces Slice as a fallback - jurisdictions where Cover Genius is not licensed, or where pricing is uncompetitive, can be flipped to Slice without code changes. See Jurisdiction Matrix.

---