Lava Checkout

A React package that provides hooks for integrating Lava's wallet-based checkout experience into your AI application.

Installation

npm install --save @lavapayments/checkout
# or
yarn add @lavapayments/checkout

Usage

Basic Implementation

import { useLavaCheckout } from '@lavapayments/checkout';
import { useState } from 'react';

function CheckoutButton() {
  const [customerId, setCustomerId] = useState(null);

  const { open } = useLavaCheckout({
    onSuccess: ({ customerId }) => {
      console.log('Checkout successful!');
      setCustomerId(customerId);
      // Store the customerId for your application
      saveCustomerIdToDatabase(userId, customerId);
    },
    onCancel: ({ checkoutSessionId }) => {
      console.log('Checkout cancelled:', checkoutSessionId);
    }
  });

  return (
    <button
      onClick={() => {
        // Request a checkout session token from your backend
        fetch('/api/create-checkout-session')
          .then(res => res.json())
          .then(data => {
            // Open the checkout modal with the session token
            open(data.checkout_session_token);
          });
      }}
    >
      Connect Wallet
    </button>
  );
}

Credit Bundle Implementation

To allow existing subscribers to buy a credit pack:

import { useLavaCheckout } from '@lavapayments/checkout';

function BuyCreditBundleButton({ customerId, creditBundleId }) {
  const { open } = useLavaCheckout({
    onSuccess: () => {
      console.log('Credit bundle purchase successful!');
      // Refresh balance display
    },
    onCancel: () => {
      console.log('Purchase cancelled');
    }
  });

  return (
    <button
      onClick={() => {
        // Request a credit bundle checkout session token from your backend
        fetch('/api/create-bundle-session', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({ customerId, creditBundleId })
        })
          .then(res => res.json())
          .then(data => {
            // Open the checkout modal with the session token
            open(data.checkout_session_token);
          });
      }}
    >
      Buy Credits
    </button>
  );
}

Related Documentation

For complete documentation on Lava's usage-based billing system and backend integration, visit www.lava.so.

Recommended Subscription Pattern (Logged In + Logged Out)

Use the same subscription CTA for both states. Your backend should pass customer_id only when you already know the customer.

• Logged-out/new customer: omit customer_id (checkout collects identity and creates customer)
• Logged-in/returning customer: include customer_id (checkout reuses existing customer)

// backend example
app.post('/api/create-subscription-session', async (req, res) => {
  const { planId, customerId } = req.body;

  const body: Record<string, string> = {
    checkout_mode: 'subscription',
    origin_url: 'https://your-app.com',
    plan_id: planId,
  };

  // Include only for known/returning customers
  if (customerId) {
    body.customer_id = customerId;
  }

  const lavaRes = await fetch('https://api.lavapayments.com/v1/checkout_sessions', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.LAVA_SECRET_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(body),
  });

  const session = await lavaRes.json();
  res.json({ checkoutSessionToken: session.checkout_session_token });
});

Then in your frontend, always call open(checkoutSessionToken) from useLavaCheckout.