npm package: @lavapayments/checkout
Description: Lava Checkout
Author: Lava
Latest version: 0.2.0

# Lava Checkout

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

## Installation

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

## Usage

### Basic Implementation

```jsx
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:

```jsx
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](https://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)

```ts
// 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`.