Example implementations

Full working examples using the Checkout API and @withlocus/checkout-react. Create sessions on your server, then render checkout on the client.

Install

npm install @withlocus/checkout-react

Use the Checkout API on your server to create sessions. Use @withlocus/checkout-react on the client to render checkout. Requires React 17+.

Quick start (without receipt)

Step 1: Create a session

There is no separate server-side npm package for checkout session creation. Call POST https://api.paywithlocus.com/api/checkout/sessions from your server with your Locus API key.

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: { userId: 'usr_123', plan: 'pro' },
    idempotencyKey: 'checkout_usr_123_pro_monthly',
  }),
});

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 2: Render checkout

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

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

Full example (Next.js)

A complete Next.js flow — API route creates the session, page renders the checkout.

import { NextResponse } from 'next/server';

export async function POST(req: Request) {
  if (!process.env.LOCUS_API_KEY) {
    return NextResponse.json(
      { error: 'Missing LOCUS_API_KEY' },
      { status: 500 },
    );
  }

  const { plan, userId } = await req.json();

  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: plan === 'pro' ? '25.00' : '10.00',
      description: `${plan} plan - monthly`,
      successUrl: `${process.env.NEXT_PUBLIC_URL}/success`,
      cancelUrl: `${process.env.NEXT_PUBLIC_URL}/pricing`,
      webhookUrl: `${process.env.NEXT_PUBLIC_URL}/api/webhooks/locus`,
      metadata: { userId, plan },
      idempotencyKey: `checkout_${userId}_${plan}_monthly`,
    }),
  });

  const payload = await response.json();

  if (!response.ok || !payload.success) {
    return NextResponse.json(
      { error: payload.message ?? 'Failed to create checkout session' },
      { status: response.status || 500 },
    );
  }

  return NextResponse.json({ sessionId: payload.data.id });
}

'use client';

import { useSearchParams } from 'next/navigation';
import { LocusCheckout } from '@withlocus/checkout-react';

export default function CheckoutPage() {
  const sessionId = useSearchParams().get('session');

  if (!sessionId) return <p>Missing session ID.</p>;

  return (
    <div style={{ maxWidth: 500, margin: '0 auto', padding: '2rem' }}>
      <LocusCheckout
        sessionId={sessionId}
        mode="embedded"
        onSuccess={(data) => {
          window.location.href = `/success?tx=${data.txHash}`;
        }}
        onCancel={() => {
          window.location.href = '/pricing';
        }}
        onError={(error) => {
          console.error(error.message);
        }}
      />
    </div>
  );
}

With receipt

Pass receiptConfig in the request body when you create the session to attach line items, tax, and company info. The client-side LocusCheckout component stays exactly the same. It automatically renders receipt details when the session has them.

Create a session with 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' },
    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

Render checkout

import { LocusCheckout } from '@withlocus/checkout-react';

// Same component — receipt details come from the session, not the client
function CheckoutPage({ sessionId }: { sessionId: string }) {
  return (
    <LocusCheckout
      sessionId={sessionId}
      mode="embedded"
      onSuccess={(data) => {
        console.log('Paid:', data.txHash);
        window.location.href = '/success';
      }}
      onCancel={() => {
        window.location.href = '/cart';
      }}
    />
  );
}

The LocusCheckout component is identical whether the session uses receipts or not. All receipt configuration happens in your POST /checkout/sessions request.

`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

The mode prop controls how the checkout UI appears.

Embedded

Renders inline in your page. Best for dedicated checkout pages.

<LocusCheckout
  sessionId={sessionId}
  mode="embedded"
  style={{ maxWidth: '450px', margin: '0 auto' }}
  onSuccess={handleSuccess}
/>

Opens checkout in a centered popup window. Calls onCancel if the popup is closed.

<LocusCheckout
  sessionId={sessionId}
  mode="popup"
  onSuccess={handleSuccess}
  onCancel={handleCancel}
/>

Redirect

Navigates the browser to the hosted checkout page. Renders nothing.

<LocusCheckout
  sessionId={sessionId}
  mode="redirect"
/>

Using the hook

For custom checkout buttons or non-standard flows, use useLocusCheckout instead of the LocusCheckout component.

import { useLocusCheckout } from '@withlocus/checkout-react';

function PayButton({ sessionId }: { sessionId: string }) {
  const { openPopup, redirectToCheckout } = useLocusCheckout();

  return (
    <div>
      <button onClick={() => openPopup(sessionId)}>
        Pay in Popup
      </button>
      <button onClick={() => redirectToCheckout(sessionId)}>
        Pay (Full Page)
      </button>
    </div>
  );
}

The hook gives you openPopup, redirectToCheckout, and getCheckoutUrl — see the full API in the Merchant Integration reference.

Getting started

Features

Agent tools

Build with Locus

Checkout

Example implementations

Install

Quick start (without receipt)

Step 1: Create a session

Step 2: Render checkout

Full example (Next.js)

With receipt

Create a session with receipt

Render checkout

`receiptConfig` fields

Display modes

Embedded

Redirect

Using the hook

​Install

​Quick start (without receipt)

​Step 1: Create a session

​Step 2: Render checkout

​Full example (Next.js)

​With receipt

​Create a session with receipt

​Render checkout

​receiptConfig fields

​Display modes

​Embedded

​Popup

​Redirect

​Using the hook

Install

Quick start (without receipt)

Step 1: Create a session

Step 2: Render checkout

Full example (Next.js)

With receipt

Create a session with receipt

Render checkout

`receiptConfig` fields

Display modes

Embedded

Popup

Redirect

Using the hook