Embed the Marlin checkout widget

Add the Marlin checkout widget to a React app or static site using data attributes, programmatic JS, or the React component — all three patterns shown.

The Marlin checkout widget lets customers pay without leaving your app. It opens the hosted checkout page in a sandboxed iframe with a full-screen modal overlay, so all payment logic stays inside a secure iframe and your page never handles any sensitive data. The widget supports three integration patterns: HTML data attributes for no-build setups, a programmatic JavaScript API, and a React component.

Installation

npm / pnpm

npm install @marlin/checkout
# or
pnpm add @marlin/checkout

---

Integration patterns

Pattern A — HTML attributes

The simplest integration. Add data-marlin-checkout to any button or link and the SDK binds the click handler automatically when the page loads. No JavaScript required beyond the script tag.

<script src="https://unpkg.com/@marlin/checkout/dist/checkout.js"></script>

<!-- One-time invoice payment -->
<button data-marlin-checkout data-invoice-id="inv_abc123">
  Pay $25.00
</button>

<!-- Subscription plan -->
<button data-marlin-checkout data-plan-slug="pro-monthly" data-theme="dark">
  Subscribe
</button>

Supported data attributes:

Attribute	Description
data-marlin-checkout	Required. Marks the element for auto-binding.
data-invoice-id	Invoice ID for a one-time payment.
data-plan-slug	Plan slug for a subscription checkout.
data-theme	light, dark, or auto (default).

Provide either data-invoice-id or data-plan-slug — not both.

Pattern B — Programmatic JS

Call MarlinCheckout.open() directly when you need full control over when the widget opens, how you respond to success or failure, or how you integrate with your own state management.

import { MarlinCheckout } from "@marlin/checkout";

const handle = MarlinCheckout.open({
  invoiceId: "inv_abc123",
  theme: "dark",
  onSuccess: ({ invoiceId, txHash }) => {
    console.log("Payment confirmed:", txHash);
    window.location.href = "/thank-you";
  },
  onError: ({ code, message }) => {
    console.error("Payment failed:", code, message);
  },
  onClose: () => {
    console.log("Widget dismissed");
  },
});

// Close programmatically if needed
// handle.close();

For a subscription, pass planSlug instead of invoiceId:

MarlinCheckout.open({
  planSlug: "pro-monthly",
  theme: "auto",
  onSuccess: ({ txHash }) => activateSubscription(txHash),
});

MarlinCheckout.open() options:

Option	Type	Description
invoiceId	string	Invoice ID for a one-time payment.
planSlug	string	Plan slug for a subscription checkout.
theme	'light' | 'dark' | 'auto'	Widget color scheme. Defaults to 'auto'.
onSuccess	({ invoiceId?, txHash? }) => void	Called when payment is confirmed on-chain.
onError	({ code, message }) => void	Called when the payment fails.
onClose	() => void	Called when the widget is dismissed without completing payment.

The return value of open() is a handle object with a single method: handle.close(), which programmatically dismisses the widget.

Pattern C — React

Import MarlinCheckoutButton for a drop-in button component, or use the useMarlinCheckout hook for fully custom UI.

Button component:

import { MarlinCheckoutButton } from "@marlin/checkout/react";

function CheckoutPage({ invoiceId }: { invoiceId: string }) {
  return (
    <MarlinCheckoutButton
      invoiceId={invoiceId}
      theme="light"
      onSuccess={({ txHash }) => {
        console.log("Paid!", txHash);
        router.push("/success");
      }}
      onError={({ message }) => alert(message)}
      className="btn btn-primary"
    >
      Pay with Crypto
    </MarlinCheckoutButton>
  );
}

Hook for custom UI:

Use useMarlinCheckout when you want to control the trigger element yourself:

import { useMarlinCheckout } from "@marlin/checkout/react";

function CustomCheckoutButton({ invoiceId }: { invoiceId: string }) {
  const { open, loading } = useMarlinCheckout();

  return (
    <button
      onClick={() =>
        open({
          invoiceId,
          theme: "dark",
          onSuccess: (data) => router.push("/success"),
        })
      }
      disabled={loading}
    >
      {loading ? "Processing..." : "Pay $49.00 USDC"}
    </button>
  );
}

The open function from the hook accepts the same options object as MarlinCheckout.open().

---

How the widget works

When you call MarlinCheckout.open() (or click a data-attribute button), the SDK:

1. Creates a full-screen semi-transparent backdrop overlay.
2. Loads an <iframe> pointing to the hosted checkout page at widget.marlin.fi.
3. Communicates with the iframe via postMessage events: ready, resize, success, error, and close.
4. Closes on Escape key, backdrop click, or handle.close().

All wallet connection and transaction signing happens inside the sandboxed iframe. Your page never has access to wallet credentials or private keys.

The iframe is sandboxed and loaded from widget.marlin.fi. If you use a Content Security Policy, add https://widget.marlin.fi to your frame-src directive.

Override the widget URL

To point the widget at a staging environment during development, set the global override before any MarlinCheckout.open() calls:

// Set before importing or calling MarlinCheckout
globalThis.MARLIN_WIDGET_URL = "https://staging-widget.marlin.fi";

Next steps

For a complete reference of all widget options and postMessage event types, see the Widget integration reference.

If you only need a shareable payment link and do not want to embed anything, every invoice already has a paymentUrl you can send directly. See Share a hosted checkout payment link.