Checkout React SDK

@meru.app/checkout-react embeds Meru Checkout in your React app. Your backend creates a checkout session; the SDK embeds or redirects to it by id or url.

The secret key (sk_live_…) is server-side only. The React SDK never sees it. Your backend creates the session with the secret key; the SDK only embeds or redirects to the resulting session id or url.

Install

npm install @meru.app/checkout-react

react >= 17 is a peer dependency.

Prerequisite: create a session on your backend

Create the session server-side and pass the returned id (or url) to your frontend. See Create a session for the full reference.

Server-side (Node.js)

const res = await fetch("https://checkout-api.meru.com/v1/checkouts", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MERU_CHECKOUT_SECRET_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    amountFiat: 50,
    reference: "order_123",
    paymentMethod: "qr-bolivia",
  }),
});

const { id, url } = await res.json();
// Send `id` (or `url`) to your frontend.

Embed the checkout

The <MeruCheckout> component renders the hosted checkout as a modal overlay or an inline iframe. Alternatively, redirectToCheckout sends the customer to the hosted page full-screen. The SDK sets the iframe allow="payment; clipboard-write; clipboard-read" automatically and verifies the message origin.

Modal
Inline
Redirect

The modal renders a fixed overlay with a close button. With autoClose (default true), it closes ~1.5s after success and immediately on cancel.

import { useState } from "react";
import { MeruCheckout, type CheckoutMessage } from "@meru.app/checkout-react";

export function PayButton({ checkoutId }: { checkoutId: string }) {
  const [open, setOpen] = useState(false);

  return (
    <>
      <button onClick={() => setOpen(true)}>Pay $50.00</button>

      {open && (
        <MeruCheckout
          checkoutId={checkoutId}
          display="modal"
          onSuccess={(m: CheckoutMessage) => {
            // UX only — confirm server-side before fulfilling.
            console.log("paid", m.checkoutId, m.txHash);
          }}
          onCancel={() => console.log("canceled")}
          onClose={() => setOpen(false)}
        />
      )}
    </>
  );
}

Inline mode renders just the iframe, sized with height.

import { MeruCheckout } from "@meru.app/checkout-react";

export function CheckoutPanel({ checkoutId }: { checkoutId: string }) {
  return (
    <MeruCheckout
      checkoutId={checkoutId}
      display="inline"
      height={680}
      onSuccess={(m) => console.log("paid", m.checkoutId)}
    />
  );
}

redirectToCheckout performs a full-page redirect to the hosted checkout. Pass a checkoutId or a full url.

import { redirectToCheckout } from "@meru.app/checkout-react";

export function PayButton({ checkoutId }: { checkoutId: string }) {
  return (
    <button onClick={() => redirectToCheckout({ checkoutId })}>
      Pay $50.00
    </button>
  );
}

The client success event is for UX only. Always confirm the payment server-side — via GET /checkouts/{id} or your own reconciliation — before fulfilling anything of value.

Track status (optional)

useCheckoutStatus polls the session and stops at a terminal status. It’s handy for inline flows where you want to reflect progress in your own UI.

import { useCheckoutStatus } from "@meru.app/checkout-react";

export function OrderStatus({ checkoutId }: { checkoutId: string }) {
  const { status, checkout, error, isSettled } = useCheckoutStatus(checkoutId);

  if (error) return <p>Couldn't load status.</p>;

  return (
    <p>
      Status: {status ?? "loading…"}
      {isSettled ? " (final)" : ""}
    </p>
  );
}

This hook reflects status for your UI. It is not a substitute for server-side confirmation before fulfillment.

`<MeruCheckout>` props

string

Session id from your backend. Provide this or url.

string

Full session URL. Alternative to checkoutId.

string

default:"https://checkout.meru.com"

Hosted checkout origin. Override for sandbox/self-hosted environments.

"modal" | "inline"

default:"modal"

Render as a modal overlay or an inline iframe.

number | string

default:"640"

Inline iframe height.

boolean

default:"true"

Close the modal automatically on success (~1.5s) or cancel (immediately).

(m: CheckoutMessage) => void

Fired when the embedded checkout has loaded.

(m: CheckoutMessage) => void

Fired when the customer starts paying.

(m: CheckoutMessage) => void

Fired when the checkout reports a successful payment (client-side).

(m: CheckoutMessage) => void

Fired when the payment fails.

(m: CheckoutMessage) => void

Fired when the customer cancels.

(m: CheckoutMessage) => void

Catch-all for every checkout message.

() => void

Fired when the modal closes (manual dismiss or auto-close).

string

Accessible title for the modal/iframe.

string

Class name applied to the container.

React.CSSProperties

Inline styles applied to the container.

`CheckoutMessage`

Every event handler receives a CheckoutMessage:

"meru-checkout"

Always "meru-checkout". Verify this before trusting a message.

"ready" | "processing" | "success" | "failed" | "cancel"

The event type.

string

The session id.

string

The session status at the time of the event.

string | null

Your order reference, echoed back.

string

The amount, when available.

string

The currency, when available.

string | null

On-chain transaction hash for crypto payments, when available.

`useCheckoutStatus(checkoutId?, options?)`

Options

string

default:"https://checkout-api.meru.com"

Checkout API origin to poll. Override for sandbox/self-hosted environments.

number

default:"5000"

Polling interval in milliseconds.

boolean

default:"true"

Whether polling is active. Set false to pause.

Returns

string

The latest session status, or undefined until first load.

Checkout

The full session object from GET /checkouts/{id}.

Error | null

The last polling error, if any.

boolean

true once status reaches a terminal value.

Statuses

created · pending · processing · succeeded · failed · expired succeeded, failed, and expired are terminal — polling stops once reached. See Payment status for the full lifecycle.

Helpers & exports

(opts: SessionUrlOptions) => string

Builds a hosted session URL from a checkoutId/url and optional baseUrl.

(url: string) => string

Returns the origin of a URL — useful for postMessage origin checks.

string

"https://checkout.meru.com" — the default component baseUrl.

string

"https://checkout-api.meru.com" — the default hook apiUrl.

Exported types: MeruCheckoutProps, Checkout, CheckoutStatus, CheckoutMessage, CheckoutEventType, SessionUrlOptions, UseCheckoutStatusOptions.

Sandbox / self-host

Point the SDK at a different environment by overriding baseUrl on the component and redirectToCheckout, and apiUrl on the status hook.

<MeruCheckout
  checkoutId={checkoutId}
  baseUrl="https://checkout.sandbox.meru.com"
/>

redirectToCheckout({
  checkoutId,
  baseUrl: "https://checkout.sandbox.meru.com",
});

useCheckoutStatus(checkoutId, {
  apiUrl: "https://checkout-api.sandbox.meru.com",
});

Create a session

Create the session on your backend with your secret key.

Payment status

Confirm payments server-side by polling.

Embed (iframe)

The underlying iframe + postMessage protocol.

API Documentation

Guides

Balances

Quotes

Payouts

Payins

Checkout

Cards

Webhooks

Checkout React SDK

Install

Prerequisite: create a session on your backend

Embed the checkout

Track status (optional)

`<MeruCheckout>` props

`CheckoutMessage`

`useCheckoutStatus(checkoutId?, options?)`

Options

Returns

Statuses

Helpers & exports

Sandbox / self-host

Create a session

Payment status

Embed (iframe)

​Install

​Prerequisite: create a session on your backend

​Embed the checkout

​Track status (optional)

​<MeruCheckout> props

​CheckoutMessage

​useCheckoutStatus(checkoutId?, options?)

​Options

​Returns

​Statuses

​Helpers & exports

​Sandbox / self-host

​Related

Create a session

Payment status

Embed (iframe)

Install

Prerequisite: create a session on your backend

Embed the checkout

Track status (optional)

`<MeruCheckout>` props

`CheckoutMessage`

`useCheckoutStatus(checkoutId?, options?)`

Options

Returns

Statuses

Helpers & exports

Sandbox / self-host

Related