Skip to main content
Create a checkout session on your server, then pass its ID to the React component. That one integration lets buyers pay with Locus Wallet, an external wallet, or an agent.

How it works

When a buyer pays, Locus tells your app twice: a callback updates the page, and a signed webhook tells your server it’s safe to fulfill.

Embed checkout

Install @withlocus/checkout-react (React 17+), then render LocusCheckout with the session ID. The integration example shows session creation, the component, and optional receipts.

Display modes

Use style or className to style the component’s wrapper. The SDK also exports LOCUS_BRAND_COLORS, LOCUS_CTA_GRADIENT, and LOCUS_FONT_FAMILY for the surrounding UI.

Payment callbacks

  • onSuccess receives sessionId, amount, currency, txHash, payerAddress, and paidAt. Use it to show confirmation.
  • onCancel runs when the buyer cancels.
  • onError reports failures.
Use callbacks to update the UI. Verify payment on your server before fulfilling an order.

Webhooks

Set webhookUrl when you create the session. Locus sends checkout.session.paid when a payment confirms and checkout.session.expired when a session expires. Verify each request’s signature before fulfilling the order. See payment webhooks.

Hook: useLocusCheckout

Use the hook for your own payment buttons:
PayButton.tsx

Merchant dashboard

1

Open Merchant

In the dashboard, open Services → Merchant to see revenue, session count, conversion, and payment methods.
2

Filter

Filter by time range or checkout instance.
3

Open a session

Open any session for its payment details.
Use an instance ID to group sessions by integration point; Locus creates the instance on first use. Buyers find their receipts in Purchases.
Revenue and checkout conversion analytics

Checkout analytics by instance

API reference

Next steps

Payment webhooks

Verify signatures and fulfill each order once.

Buyer and agent guide

See checkout from the buyer’s side.