Checkout integration example

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 to verify payment webhooks before fulfilling orders.

Install

Install the React SDK

npm install @withlocus/checkout-react

Requires React 17+.

Create and show checkout

Create a session on your server

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.

Server: create a session

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)

Render checkout in your app

Pass the session ID to the LocusCheckout component on the client.

CheckoutPage.tsx

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);
      }}
    />
  );
}

With receipt

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

Full receipt example

Server: create a session with a receipt

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: '[email protected]',
      },
    },
  }),
});

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

`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. It provides openPopup, redirectToCheckout, and getCheckoutUrl.

Getting started

Features

Agent tools

Build with Locus

Checkout

Checkout integration example

Install

Create and show checkout

With receipt

`receiptConfig` fields

Display modes

​Install

​Create and show checkout

​With receipt

​receiptConfig fields

​Display modes

Install

Create and show checkout

With receipt

`receiptConfig` fields

Display modes