@marlin/checkout embeddable widget

Drop the Marlin checkout widget into any website to accept stablecoin payments via a sandboxed iframe — no backend required for the embed itself.

@marlin/checkout is a drop-in checkout widget that lets you accept stablecoin payments on any website without building a custom payment UI. You add a script tag or import the package, and the widget loads the Marlin-hosted checkout page inside a sandboxed iframe. All payment logic — wallet connection, transaction signing, confirmation — runs inside the iframe on Marlin’s infrastructure. Your page only manages when to open and close the overlay.

How it works

When you call MarlinCheckout.open() or click a data-marlin-checkout element, the SDK:

1. Creates a full-screen dark backdrop overlay.
2. Loads the hosted checkout page from widget.marlin.fi in a sandboxed iframe.
3. Listens for postMessage events (ready, resize, success, error, close) from the iframe.
4. Tears down the overlay when the payment completes, the user closes the widget, or you call handle.close().

No sensitive payment data passes through your page. The SDK only manages the overlay DOM and forwards lifecycle events to your callbacks.

Integration patterns

You have three ways to embed the widget. Pick the one that fits your stack.

Pattern	Best for
Data attributes	Static HTML pages, CMS templates, no-build environments
Programmatic JS	Full control over when and how the widget opens; vanilla JS or any framework
React component	React applications that want typed props and hook-based control

See Integrate the Marlin checkout widget for complete code for all three patterns.

Package details

npm package: @marlin/checkout

React bindings subpath: @marlin/checkout/react

CDN URL:

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

Security model

The widget uses a defense-in-depth approach:

• The iframe loads from widget.marlin.fi, a domain fully controlled by Marlin. The SDK validates that all incoming postMessage events originate from that origin before acting on them.
• The iframe attribute allow="payment; clipboard-write" grants only the permissions the widget needs.
• No API keys, wallet private keys, or payment credentials ever leave the iframe. The SDK on your page only receives opaque success/error events.
• If you need to point at a staging widget URL during development, set globalThis.MARLIN_WIDGET_URL before any MarlinCheckout calls (see Integrate the Marlin checkout widget).