Checkout Modes

​

The Three Modes

​

Subscription Mode

const session = await lava.checkoutSessions.create({
  checkout_mode: 'subscription',
  origin_url: 'https://yourapp.com',
  subscription_config_id: 'subconf_your_plan_id',
  reference_id: 'user_123'
});

1. Customer verifies phone number
2. Customer adds payment method
3. Customer is charged the plan amount (e.g., $25)
4. Subscription is created with automatic monthly renewal
5. You receive a connection_id to use for billing

• Balance resets monthly to the plan amount
• Overages auto-charge to the customer’s card
• Customer can cancel anytime

​

Topup Mode

const session = await lava.checkoutSessions.create({
  checkout_mode: 'topup',
  origin_url: 'https://yourapp.com',
  connection_id: 'conn_existing_customer_id' // Required
});

1. Customer sees their current balance
2. Customer chooses an amount to add
3. Customer is charged immediately
4. Balance increases by that amount

• “Add Credits” button in your app
• Low balance warning with recharge CTA
• Letting power users pre-fund larger amounts

​

Onboarding Mode (Legacy)

const session = await lava.checkoutSessions.create({
  checkout_mode: 'onboarding',
  origin_url: 'https://yourapp.com',
  reference_id: 'user_123'
});

1. Customer verifies phone number
2. Customer adds payment method
3. Customer adds an initial balance (one-time charge)
4. You receive a connection_id

• No automatic renewal
• Customer must manually top up when balance runs low
• No plan attached

​

Which Mode Should I Use?

Is this a new customer?
├── Yes → Do you want recurring monthly billing?
│   ├── Yes → subscription
│   └── No → onboarding (legacy)
└── No → topup

1. New customers → subscription mode
2. Existing customers adding credits → topup mode

​

Checkout Flow Summary

• Phone verification via SMS OTP
• Payment method collection via Stripe
• Wallet creation (for new customers)
• Balance funding

​

Next Steps