Merchant Integration

Install

npm install @withlocus/checkout-react

Requires React 17+.

Embed checkout

The LocusCheckout component takes a session ID and renders the full checkout experience. Buyers can pay with their Locus Wallet, an external wallet, or an AI agent — all handled by the component.

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

function CheckoutPage({ sessionId }: { sessionId: string }) {
  return (
    <LocusCheckout
      sessionId={sessionId}
      mode="embedded"
      onSuccess={(data) => {
        console.log('Paid!', data.txHash);
        // redirect to your success page, fulfill the order, etc.
      }}
      onCancel={() => {
        console.log('Buyer cancelled');
      }}
      onError={(error) => {
        console.error('Checkout error:', error.message);
      }}
    />
  );
}

Display modes

embedded

Renders an iframe inline in your page. Best for dedicated checkout pages. The iframe loads at minHeight: 700px.

popup

Opens checkout in a centered 450x650 popup window. Shows a branded loading placeholder in the parent. Calls onCancel if the popup is closed.

redirect

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

`LocusCheckout` props

Prop	Type	Required	Default	Description
`sessionId`	`string`	Yes	—	The checkout session ID
`mode`	`'embedded' \| 'popup' \| 'redirect'`	No	`'embedded'`	How to display the checkout UI
`onSuccess`	`(data: CheckoutSuccessData) => void`	No	—	Called when payment is confirmed. Receives the transaction hash, payer address, amount, and timestamps.
`onCancel`	`() => void`	No	—	Called when the buyer cancels, or when a popup is closed without completing payment
`onError`	`(error: Error) => void`	No	—	Called when an error occurs during checkout
`checkoutUrl`	`string`	No	`'https://checkout.paywithlocus.com'`	Override the hosted checkout URL. Must be `https:` or `http:`. Invalid URLs silently fall back to the default.
`style`	`React.CSSProperties`	No	—	Inline styles applied to the wrapper `<div>`
`className`	`string`	No	—	CSS class applied to the wrapper `<div>`

`CheckoutSuccessData`

The object passed to your onSuccess callback:

Field	Type	Description
`sessionId`	`string`	The checkout session ID
`amount`	`string`	Payment amount (e.g. `"25.00"`)
`currency`	`string`	Always `"USDC"`
`txHash`	`string`	On-chain transaction hash
`payerAddress`	`string`	Wallet address that paid
`paidAt`	`string`	ISO 8601 timestamp of payment confirmation

`CheckoutSession` type

Represents a checkout session’s current state:

Field	Type	Description
`id`	`string`	Session ID
`amount`	`string`	Payment amount in USDC
`currency`	`string`	Always `"USDC"`
`description`	`string?`	Description shown to the buyer
`status`	`'PENDING' \| 'PAID' \| 'EXPIRED' \| 'CANCELLED'`	Current session status
`expiresAt`	`string`	ISO 8601 expiration timestamp
`sellerWalletAddress`	`string`	Merchant’s receiving wallet address
`paymentTxHash`	`string?`	On-chain tx hash (set when `PAID`)
`paidAt`	`string?`	Payment timestamp (set when `PAID`)

Hook: `useLocusCheckout`

For more control over how you launch checkout, use the hook directly instead of the component.

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

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

  return (
    <div>
      <button onClick={() => openPopup(sessionId)}>Pay in Popup</button>
      <button onClick={() => redirectToCheckout(sessionId)}>Pay (Redirect)</button>
      <a href={getCheckoutUrl(sessionId)}>Direct Link</a>
    </div>
  );
}

Options

Option	Type	Default
`checkoutUrl`	`string`	`'https://checkout.paywithlocus.com'`

Return values

Method	Type	Description
`getCheckoutUrl(sessionId)`	`string`	Returns the full checkout URL for a session
`openPopup(sessionId)`	`Window \| null`	Opens a centered 450x650 popup to the checkout page
`redirectToCheckout(sessionId)`	`void`	Navigates the browser to the checkout page

All return values are stable across renders (wrapped in useCallback).

Brand constants

The SDK exports Locus brand tokens for styling surrounding UI to match:

import {
  LOCUS_BRAND_COLORS,
  LOCUS_CTA_GRADIENT,
  LOCUS_FONT_FAMILY,
} from '@withlocus/checkout-react';

All brand values

LOCUS_BRAND_COLORS

Key	Value
`violetPrimary`	`#4101F6`
`violetLight`	`#5934FF`
`violetSoft`	`#F4F0FF`
`violetMuted`	`#E4DEFF`
`textPrimary`	`#1B1B1C`
`border`	`#DDDEE0`
`borderStrong`	`#C7C8CA`
`surface`	`#F4F4F6`
`surfacePage`	`#FDFDFD`

LOCUS_CTA_GRADIENT

linear-gradient(180deg, #5934FF 0%, #4101F6 100%)

LOCUS_FONT_FAMILY

'Suisse Intl', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif

PostMessage events

If you embed the checkout page in an iframe or popup manually (without the SDK), listen for these postMessage events from the checkout origin:

Event type	Payload	Description
`locus:checkout:success`	`CheckoutSuccessData`	Payment confirmed
`locus:checkout:cancel`	—	Buyer cancelled
`locus:checkout:error`	`{ message: string }`	Error occurred

Webhooks

When a session is paid or expires, Locus sends a POST request to your webhook URL.

Events

Event	Trigger
`checkout.session.paid`	Payment confirmed on-chain
`checkout.session.expired`	Session TTL exceeded without payment

Payload

{
  "event": "checkout.session.paid",
  "data": {
    "sessionId": "SESSION_ID",
    "amount": "25.00",
    "currency": "USDC",
    "paymentTxHash": "0x...",
    "payerAddress": "0x...",
    "paidAt": "2026-03-01T12:00:00.000Z",
    "metadata": { "userId": "usr_123", "plan": "pro" }
  },
  "timestamp": "2026-03-01T12:00:01.000Z"
}

Headers

Header	Description
`X-Signature-256`	`sha256={hmac}` — HMAC-SHA256 of the JSON body
`X-Webhook-Event`	Event name (e.g. `checkout.session.paid`)
`X-Session-Id`	The session ID

Signature verification

Every webhook includes an X-Signature-256 header. The webhook secret (starts with whsec_) is returned when you create a session with a webhook URL. Verify it to ensure the request came from Locus.

import crypto from 'crypto';

function verifyWebhook(payload: string, signature: string, secret: string): boolean {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected),
  );
}

Always verify the webhook signature before fulfilling orders.

Merchant dashboard

Manage sessions, view analytics, and track purchases from the Locus dashboard.

Checkout instances

Group sessions by integration point using an instance ID. Each instance tracks its own revenue, session count, and conversion rate. Instances are auto-created on first use.

Analytics

Four stats filterable by time range (7d / 30d / 90d / all time) and by instance:

Total Revenue — sum of USDC across paid sessions
Total Sessions — count with paid/expired breakdown
Conversion Rate — paid / total sessions
Payment Methods — breakdown of Locus Wallet, External Wallet, and Agent payments

Analytics stats — Analytics — revenue, sessions, conversion rate, and payment method breakdown

Recent sessions

A paginated table of checkout sessions filterable by status (PAID, PENDING, EXPIRED, CANCELLED). Shows session ID, amount, status, payment method, and creation time.

Purchases

The buyer-side view. Shows purchases made via any Locus checkout session, with expandable rows showing full receipt details (seller info, line items, tax, on-chain transaction link).

Getting started

Features

Agent tools

Build with Locus

Checkout

Merchant Integration

Install

Embed checkout

Display modes

embedded

popup

redirect

`LocusCheckout` props

`CheckoutSuccessData`

`CheckoutSession` type

Hook: `useLocusCheckout`

Options

Return values

Brand constants

PostMessage events

Webhooks

Events

Payload

Headers

Signature verification

Merchant dashboard

Checkout instances

Analytics

Recent sessions

Purchases

​Install

​Embed checkout

​Display modes

embedded

popup

redirect

​LocusCheckout props

​CheckoutSuccessData

​CheckoutSession type

​Hook: useLocusCheckout

​Options

​Return values

​Brand constants

​PostMessage events

​Webhooks

​Events

​Payload

​Headers

​Signature verification

​Merchant dashboard

​Checkout instances

​Analytics

​Recent sessions

​Purchases

Install

Embed checkout

Display modes

`LocusCheckout` props

`CheckoutSuccessData`

`CheckoutSession` type

Hook: `useLocusCheckout`

Options

Return values

Brand constants

PostMessage events

Webhooks

Events

Payload

Headers

Signature verification

Merchant dashboard

Checkout instances

Analytics

Recent sessions

Purchases