> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paywithlocus.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Checkout integration example

> End-to-end examples for adding Locus Checkout to your app

Add checkout in two steps: create a session on your server and show it with the React component. Your API key stays server-side; the browser only needs a session ID.

Use the [merchant guide](/checkout/for-merchants#webhooks) to verify payment webhooks before fulfilling orders.

## Install

```bash title="Install the React SDK" theme={null}
npm install @withlocus/checkout-react
```

Requires React 17+.

## Create and show checkout

<Steps>
  <Step title="Create a session on your server" id="step-1-create-a-session">
    Call the Checkout API from your server with the price and order details. Keep the idempotency key stable for retries of this order; use a new key for each new purchase.

    ```typescript title="Server: create a session" theme={null}
    const LOCUS_API_BASE_URL =
      process.env.LOCUS_API_BASE_URL ?? 'https://api.paywithlocus.com/api';

    if (!process.env.LOCUS_API_KEY) {
      throw new Error('Missing LOCUS_API_KEY');
    }

    const response = await fetch(`${LOCUS_API_BASE_URL}/checkout/sessions`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Authorization: `Bearer ${process.env.LOCUS_API_KEY}`,
      },
      body: JSON.stringify({
        amount: '25.00',
        description: 'Pro plan - monthly',
        successUrl: 'https://yourapp.com/success',
        cancelUrl: 'https://yourapp.com/cancel',
        webhookUrl: 'https://yourapp.com/api/webhooks/locus',
        metadata: { orderId: 'order_123', userId: 'usr_123', plan: 'pro' },
        idempotencyKey: 'checkout_order_123',
      }),
    });

    const payload = await response.json();

    if (!response.ok || !payload.success) {
      throw new Error(payload.message ?? 'Failed to create checkout session');
    }

    const session = payload.data;

    // session.id          -> session ID (UUID)
    // session.checkoutUrl -> hosted checkout URL
    // session.expiresAt   -> session expiration (default 30 min)
    ```
  </Step>

  <Step title="Render checkout in your app" id="step-2-render-checkout">
    Pass the session ID to the `LocusCheckout` component on the client.

    ```tsx CheckoutPage.tsx theme={null}
    import { LocusCheckout } from '@withlocus/checkout-react';

    function CheckoutPage({ sessionId }: { sessionId: string }) {
      return (
        <LocusCheckout
          sessionId={sessionId}
          mode="embedded"
          onSuccess={(data) => {
            console.log('Payment confirmed:', data.txHash);
            window.location.href = '/success';
          }}
          onCancel={() => {
            console.log('Buyer cancelled');
            window.location.href = '/cancel';
          }}
          onError={(error) => {
            console.error('Checkout error:', error.message);
          }}
        />
      );
    }
    ```
  </Step>
</Steps>

## With receipt

Add `receiptConfig` when creating the session to show line items, tax, and seller information. The same React component displays the receipt automatically.

<Accordion title="Full receipt example">
  ```typescript title="Server: create a session with a receipt" theme={null}
  if (!process.env.LOCUS_API_KEY) {
    throw new Error('Missing LOCUS_API_KEY');
  }

  const response = await fetch('https://api.paywithlocus.com/api/checkout/sessions', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${process.env.LOCUS_API_KEY}`,
    },
    body: JSON.stringify({
      amount: '27.50',
      description: 'TechMart order #4821',
      successUrl: 'https://yourapp.com/success',
      cancelUrl: 'https://yourapp.com/cart',
      webhookUrl: 'https://yourapp.com/api/webhooks/locus',
      metadata: { orderId: 'order_4821' },
      idempotencyKey: 'checkout_order_4821',
      receiptConfig: {
        enabled: true,
        fields: {
          creditorName: 'TechMart Inc.',
          lineItems: [
            { description: 'Wireless Headphones', amount: '25.00' },
            { description: 'Shipping', amount: '0.00' },
          ],
          subtotal: '25.00',
          taxRate: '10%',
          taxAmount: '2.50',
          logoUrl: 'https://techmart.com/logo.png',
          companyAddress: '123 Market St, San Francisco, CA 94105',
          supportEmail: 'support@techmart.com',
        },
      },
    }),
  });

  const payload = await response.json();

  if (!response.ok || !payload.success) {
    throw new Error(payload.message ?? 'Failed to create checkout session');
  }

  const session = payload.data;

  // session.id -> pass to LocusCheckout on the client
  ```
</Accordion>

### `receiptConfig` fields

| Field | Type | Description |
| - | - | - |
| `enabled` | `boolean` | Enable the receipt on this session |
| `fields.creditorName` | `string` | Seller/company name shown on the receipt |
| `fields.lineItems` | `{ description: string, amount: string }[]` | Itemized charges |
| `fields.subtotal` | `string` | Subtotal before tax |
| `fields.taxRate` | `string` | Tax rate (e.g. `"10%"`) |
| `fields.taxAmount` | `string` | Tax amount in USDC |
| `fields.logoUrl` | `string` | URL to your company logo |
| `fields.companyAddress` | `string` | Company address |
| `fields.supportEmail` | `string` | Support email shown on receipt |

After payment, receipt details also appear in the buyer's **Purchases** tab on the Locus dashboard.

## Display modes

Set `mode` on `LocusCheckout` to choose the experience:

| Mode | Behavior |
| - | - |
| `embedded` | Shows checkout inside your page. |
| `popup` | Opens a separate window; closing it calls `onCancel`. |
| `redirect` | Sends the buyer to the hosted checkout page. |

For custom buttons, use [`useLocusCheckout`](/checkout/for-merchants#hook-uselocuscheckout). It provides `openPopup`, `redirectToCheckout`, and `getCheckoutUrl`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.