Two-Layer Financial Architecture
Lava uses a sophisticated two-layer financial model that separates product concepts from implementation reality:Layer 1: Internal Ledger (Transfers)
All financial obligations are tracked instantly in the transfer ledger. Each transfer records:totalAmount: The full liability (what should be paid)settledAmount: What was actually paid at creation
Layer 2: External Money Movement (Stripe)
Actual money flows happen through Stripe:- User payments: Real money goes from user to Lava’s Stripe account
- Merchant payouts: Stripe Connect Express transfers money from Lava to merchants on a schedule
Transfer-Based Ledger
Every usage event creates three types of transfers:1. Base Cost Transfer
- From: Wallet
- To: AI Provider (conceptual)
- Amount: Provider’s standard rate for the usage
- Purpose: Track cost of AI service itself
2. Fee Transfer
- From: Wallet
- To: Merchant
- Amount: Merchant’s configured markup (fixed or percentage)
- Purpose: Merchant revenue from the service
3. Service Charge Transfer
- From: Wallet
- To: Lava Platform
- Amount: 1.9% of fee transfer (Lava’s platform fee)
- Purpose: Platform operation and support
Settlement Priority
Transfers are settled in chronological order (oldest first):- User adds 50`
- User makes API call costing $60 (insufficient funds)
- Transfer created:
totalAmount = $60,settledAmount = $50 - User adds 10
- New transfer:
settledAmount = $60(now fully settled)
Prepaid Wallet System
Wallets are the core of Lava’s billing model:Active Balance
The active balance is the spendable amount currently available:- Increases when users add funds via Stripe
- Decreases when AI requests are made
- Shown in real-time in user dashboard
- Tracked via internal ledger (not exposed in response headers)
Balance Management
Users can manage their balance through:- Manual top-ups: Add funds anytime via Stripe checkout
- Autopay: Auto-top-up when balance falls below threshold
- Subscriptions: Recurring monthly credits added to wallet
- Multiple connections: Same balance used across merchants
Wallets are user-owned, not merchant-specific. A user creates one wallet and uses it across all Lava merchants.
Fee Structure
Merchant-Configured Fees
Merchants control their pricing through two models: Fixed Fee:Service Charge
Lava applies a 1.9% platform fee on the merchant’s fee (not the base cost):Cost Attribution
Merchants can configure who pays for different cost components:| Cost Component | Can Be Paid By |
|---|---|
| Base Costs | Wallet (default) or Merchant |
| Merchant Fees | Wallet only |
| Service Charge | Follows merchant fees |
- Pass-through: Wallet pays base costs, wallet pays fees
- Merchant Absorbs Base: Merchant pays base costs, wallet pays fees
- Freemium: Merchant pays base costs AND fees (wallet pays nothing)
Merchant Payouts
Merchants earn from settled fee transfers. Revenue is tracked in real-time but paid out on a schedule:Payout Schedule
- Default: Weekly automatic payouts via Stripe Connect
- Custom: Merchants can configure daily or monthly
- On-demand: Manual payout request available
Revenue Tracking
Merchants see in their dashboard:- Pending earnings: From unsettled transfers
- Available for payout: From settled transfers
- Paid out: Historical payout records
Payment Processing
User Payments
When users add funds to their wallet:- Stripe Checkout: User enters payment method details
- Payment Intent: Stripe processes payment securely
- Webhook: Lava receives payment confirmation
- Balance Update: Wallet’s active balance increases
- Settlement: System settles oldest under-settled transfers
Supported Payment Methods
Via Stripe, Lava supports:- Credit and debit cards (Visa, Mastercard, Amex)
- Digital wallets (Apple Pay, Google Pay)
- Bank transfers (ACH, wire)
- Buy now, pay later (Klarna, Afterpay)