Web - MoonPay Developer Docs

Use iframes and postMessage to embed frames directly in web applications without installing any MoonPay packages.

Read the manual integration overview for core concepts before you continue.

Setup

Encryption

The connect and check frames require X25519 key exchange to encrypt client credentials. The examples below use @noble/curves, but you can use any library that supports X25519 and AES-GCM.

pnpm i @noble/curves @noble/hashes @noble/ciphers

bun add @noble/curves @noble/hashes @noble/ciphers

npm i @noble/curves @noble/hashes @noble/ciphers

Message utilities

Create helper functions for sending and receiving frame messages. All messages follow the frames protocol.

messageUtils.ts

const FRAME_ORIGIN = "https://platform.moonpay.com";

interface FrameMessage {
  version: number;
  meta: { channelId: string };
  kind: string;
  payload?: unknown;
}

function parseFrameMessage(
  event: MessageEvent,
  channelId: string,
): FrameMessage | null {
  if (event.origin !== FRAME_ORIGIN) return null;

  try {
    const data: FrameMessage =
      typeof event.data === "string" ? JSON.parse(event.data) : event.data;
    if (data.meta?.channelId !== channelId) return null;
    return data;
  } catch {
    return null;
  }
}

function sendFrameMessage(
  iframe: HTMLIFrameElement,
  channelId: string,
  kind: string,
  payload?: object,
) {
  const message: FrameMessage = {
    version: 2,
    meta: { channelId },
    kind,
    ...(payload && { payload }),
  };

  iframe.contentWindow?.postMessage(JSON.stringify(message), FRAME_ORIGIN);
}

Encryption utility

The connect and check frames return encrypted credentials. Generate an X25519 keypair and provide the public key to the frame.

Key generation

crypto.ts

import { x25519 } from "@noble/curves/ed25519";
import { bytesToHex } from "@noble/hashes/utils";

function generateKeyPair() {
  const { secretKey, publicKey } = x25519.keygen();

  return {
    privateKeyHex: bytesToHex(secretKey),
    publicKeyHex: bytesToHex(publicKey),
  };
}

Decryption

decrypt.ts

import { x25519 } from "@noble/curves/ed25519";
import { hkdf } from "@noble/hashes/hkdf";
import { sha256 } from "@noble/hashes/sha256";
import { gcm } from "@noble/ciphers/aes";
import { hexToBytes } from "@noble/hashes/utils";

interface ClientCredentials {
  accessToken: string;
  clientToken: string;
}

function decryptClientCredentials(
  encryptedBase64: string,
  privateKeyHex: string,
): ClientCredentials {
  const json = JSON.parse(atob(encryptedBase64)) as {
    ephemeralPublicKey: string;
    iv: string;
    ciphertext: string;
  };

  const sharedSecret = x25519.getSharedSecret(
    hexToBytes(privateKeyHex),
    hexToBytes(json.ephemeralPublicKey),
  );

  const derivedKey = hkdf(sha256, sharedSecret, undefined, undefined, 32);

  const aes = gcm(derivedKey, hexToBytes(json.iv));
  const decrypted = aes.decrypt(hexToBytes(json.ciphertext));
  const text = new TextDecoder().decode(decrypted);

  return JSON.parse(text) as ClientCredentials;
}

Check frame

The check frame verifies whether a customer already has an active connection. It’s headless — no UI is rendered. Use it to skip the connect flow for returning customers. See check frame reference for event details.

Initialize the frame

const FRAME_ORIGIN = "https://platform.moonpay.com";

function initializeCheckFrame(sessionToken: string) {
  const iframe = document.getElementById("moonpay-frame") as HTMLIFrameElement;
  const channelId = crypto.randomUUID();
  const keyPair = generateKeyPair();

  const params = new URLSearchParams({
    sessionToken,
    publicKey: keyPair.publicKeyHex,
    channelId,
  });

  iframe.src = `${FRAME_ORIGIN}/platform/v1/check-connection?${params.toString()}`;

  return { iframe, channelId, keyPair };
}

Handle events

interface CheckCompletePayload {
  status:
    | "active"
    | "connectionRequired"
    | "pending"
    | "unavailable"
    | "failed";
  credentials?: string;
  expiresAt?: string;
  customer?: {
    id: string;
    country: string;
    administrativeArea?: string;
    area?: string;
  };
  capabilities?: {
    ramps: {
      requirements: {
        /** @deprecated Use customer.country, customer.administrativeArea, and customer.area instead */
        paymentDisclosures?: {
          country: string;
          administrativeArea?: string;
          area?: string;
        };
      };
    };
  };
  /** Present only when the session's email and phone number resolve to different MoonPay customers. */
  mismatch?: boolean;
  reason?: string;
}

function setupCheckListener(channelId: string, privateKeyHex: string) {
  const handler = (event: MessageEvent) => {
    const data = parseFrameMessage(event, channelId);
    if (!data) return;

    const iframe = document.getElementById(
      "moonpay-frame",
    ) as HTMLIFrameElement;

    switch (data.kind) {
      case "handshake":
        sendFrameMessage(iframe, channelId, "ack");
        break;

      case "complete":
        handleCheckComplete(
          data.payload as CheckCompletePayload,
          privateKeyHex,
        );
        break;

      case "error":
        const error = data.payload as { code: string; message: string };
        console.error("Check error:", error.code, error.message);
        break;
    }
  };

  window.addEventListener("message", handler);

  return () => window.removeEventListener("message", handler);
}

function handleCheckComplete(
  payload: CheckCompletePayload,
  privateKeyHex: string,
) {
  switch (payload.status) {
    case "active":
      const credentials = decryptClientCredentials(
        payload.credentials!,
        privateKeyHex,
      );
      // Store credentials in memory for subsequent API calls and frames
      console.log("Already connected!");
      // Read payload.customer.country, payload.customer.administrativeArea,
      // and payload.customer.area to determine geo-based disclosure requirements.
      // payload.capabilities.ramps.requirements.paymentDisclosures is deprecated.
      break;

    case "connectionRequired":
      const anonymousCredentials = decryptClientCredentials(
        payload.credentials!,
        privateKeyHex,
      );
      // Store both tokens in memory, then pass clientToken to the connect frame
      console.log("No active connection — show connect frame");
      // payload.mismatch is true when the session's email and phone resolve to different customers — route through the connect flow first.
      break;

    case "pending":
      console.log("Connection pending — customer may need to complete KYC");
      break;

    case "unavailable":
      console.log("Connection unavailable — likely geo-restricted");
      break;

    case "failed":
      console.error("Check failed:", payload.reason);
      break;
  }
}

Usage

const { channelId, keyPair } = initializeCheckFrame("your-session-token");
const cleanup = setupCheckListener(channelId, keyPair.privateKeyHex);

// When done, clean up the listener
// cleanup();

Connect frame

The connect frame establishes a customer connection to your application. See connect frame reference for event details.

Initialize the frame

const FRAME_ORIGIN = "https://platform.moonpay.com";

function initializeConnectFrame(clientToken: string) {
  const iframe = document.getElementById("moonpay-frame") as HTMLIFrameElement;
  const channelId = crypto.randomUUID();
  const keyPair = generateKeyPair();

  const params = new URLSearchParams({
    clientToken,
    publicKey: keyPair.publicKeyHex,
    channelId,
  });

  iframe.src = `${FRAME_ORIGIN}/platform/v1/connect?${params.toString()}`;

  return { iframe, channelId, keyPair };
}

Handle events

interface ConnectCompletePayload {
  status: "active" | "pending" | "unavailable" | "failed";
  credentials?: string;
  expiresAt?: string;
  customer?: {
    id: string;
    country: string;
    administrativeArea?: string;
    area?: string;
  };
  capabilities?: {
    ramps: {
      requirements: {
        /** @deprecated Use customer.country, customer.administrativeArea, and customer.area instead */
        paymentDisclosures?: {
          country: string;
          administrativeArea?: string;
          area?: string;
        };
      };
    };
  };
  reason?: string;
}

function setupConnectListener(channelId: string, privateKeyHex: string) {
  const handler = (event: MessageEvent) => {
    const data = parseFrameMessage(event, channelId);
    if (!data) return;

    const iframe = document.getElementById(
      "moonpay-frame",
    ) as HTMLIFrameElement;

    switch (data.kind) {
      case "handshake":
        sendFrameMessage(iframe, channelId, "ack");
        break;

      case "complete":
        handleConnectComplete(
          data.payload as ConnectCompletePayload,
          privateKeyHex,
        );
        break;

      case "error":
        const error = data.payload as { code: string; message: string };
        console.error("Connect error:", error.code, error.message);
        break;
    }
  };

  window.addEventListener("message", handler);

  return () => window.removeEventListener("message", handler);
}

function handleConnectComplete(
  payload: ConnectCompletePayload,
  privateKeyHex: string,
) {
  switch (payload.status) {
    case "active":
      const credentials = decryptClientCredentials(
        payload.credentials!,
        privateKeyHex,
      );
      // Store tokens in memory for subsequent API calls and frames
      console.log("Connected!");
      // Read payload.customer.country, payload.customer.administrativeArea,
      // and payload.customer.area to determine geo-based disclosure requirements.
      // payload.capabilities.ramps.requirements.paymentDisclosures is deprecated.
      break;

    case "pending":
      console.log("Connection pending — customer may need to complete KYC");
      break;

    case "unavailable":
      console.log("Connection unavailable — likely geo-restricted");
      break;

    case "failed":
      console.error("Connection failed:", payload.reason);
      break;
  }
}

Usage

// The clientToken is obtained from the check frame's `connectionRequired` response
const { channelId, keyPair } = initializeConnectFrame("your-client-token");
const cleanup = setupConnectListener(channelId, keyPair.privateKeyHex);

// When done, clean up the listener
// cleanup();

Auth frame

The auth frame authenticates a customer with email or SMS one-time passcode and returns fully scoped credentials — without the hosted KYC UI in the connect frame. Launch it after the check frame returns connectionRequired, typically when you drive onboarding through the Customer API. See auth frame reference for event details.

Initialize the frame

const FRAME_ORIGIN = "https://platform.moonpay.com";

function initializeAuthFrame(clientToken: string) {
  const iframe = document.getElementById("moonpay-frame") as HTMLIFrameElement;
  const channelId = crypto.randomUUID();
  const keyPair = generateKeyPair();

  const params = new URLSearchParams({
    clientToken,
    publicKey: keyPair.publicKeyHex,
    channelId,
  });

  iframe.src = `${FRAME_ORIGIN}/v2/auth?${params.toString()}`;

  return { iframe, channelId, keyPair };
}

Handle events

interface AuthCompletePayload {
  status: "active" | "termsAcceptanceRequired" | "pending" | "unavailable";
  credentials?: string;
  expiresAt?: string;
  customer?: { id: string };
  capabilities?: {
    ramps: {
      requirements: {
        paymentDisclosures?: {
          country: string;
          administrativeArea?: string;
          area?: string;
        };
      };
    };
  };
}

function setupAuthListener(channelId: string, privateKeyHex: string) {
  const handler = (event: MessageEvent) => {
    const data = parseFrameMessage(event, channelId);
    if (!data) return;

    const iframe = document.getElementById(
      "moonpay-frame",
    ) as HTMLIFrameElement;

    switch (data.kind) {
      case "handshake":
        sendFrameMessage(iframe, channelId, "ack");
        break;

      case "ready":
        // OTP sent — reveal the iframe and hide your loading state
        iframe.style.display = "block";
        break;

      case "complete":
        handleAuthComplete(data.payload as AuthCompletePayload, privateKeyHex);
        break;

      case "error":
        const error = data.payload as { code: string; message: string };
        console.error("Auth error:", error.code, error.message);
        break;

      case "close":
        // Customer dismissed the frame — tear down the iframe
        iframe.remove();
        break;
    }
  };

  window.addEventListener("message", handler);

  return () => window.removeEventListener("message", handler);
}

function handleAuthComplete(
  payload: AuthCompletePayload,
  privateKeyHex: string,
) {
  switch (payload.status) {
    case "active":
      const credentials = decryptClientCredentials(
        payload.credentials!,
        privateKeyHex,
      );
      // Store tokens in memory. Use payload.customer.id for Customer API calls.
      console.log("Authenticated!", payload.customer?.id);
      break;

    case "termsAcceptanceRequired":
      // Show Terms of Use in your UI, then create a new session with
      // termsAcceptedAt and relaunch — see Terms acceptance guide.
      console.log("Terms acceptance required");
      break;

    case "pending":
      console.log("Auth pending — KYC decision in progress");
      break;

    case "unavailable":
      console.log("Auth unavailable — likely geo-restricted");
      break;
  }
}

Usage

// The clientToken is the anonymous token from the check frame's
// `connectionRequired` response (after calling getConnection with skipKyc).
const { channelId, keyPair } = initializeAuthFrame("your-client-token");
const cleanup = setupAuthListener(channelId, keyPair.privateKeyHex);

// When done, clean up the listener
// cleanup();

Add Card frame

The add card frame lets a customer save a new card to their account. See add card frame reference for event details.

What you’ll need

Before you initialize the add card frame, you need:

A clientToken from a successful connect flow

Initialize the frame

function initializeAddCardFrame(clientToken: string) {
  const iframe = document.getElementById("moonpay-frame") as HTMLIFrameElement;
  const channelId = crypto.randomUUID();

  const params = new URLSearchParams({
    clientToken,
    channelId,
  });

  iframe.src = `${FRAME_ORIGIN}/platform/v1/add-card?${params.toString()}`;

  return { iframe, channelId };
}

Handle events

interface AddCardCompletePayload {
  card: {
    id: string;
    brand: string;
    last4: string;
    cardType: string;
    expirationMonth: number;
    expirationYear: number;
    availability: { active: boolean };
  };
}

function setupAddCardListener(channelId: string) {
  const iframe = document.getElementById("moonpay-frame") as HTMLIFrameElement;

  const handler = (event: MessageEvent) => {
    const data = parseFrameMessage(event, channelId);
    if (!data) return;

    switch (data.kind) {
      case "handshake":
        sendFrameMessage(iframe, channelId, "ack");
        break;

      case "ready":
        console.log("Add card frame ready");
        break;

      case "complete":
        const payload = data.payload as AddCardCompletePayload;
        console.log("Card saved:", payload.card.id);
        // Poll for card status or proceed to payment
        break;

      case "error":
        const error = data.payload as { code: string; message: string };
        console.error("Add card error:", error.code, error.message);
        break;
    }
  };

  window.addEventListener("message", handler);

  return () => window.removeEventListener("message", handler);
}

Usage

const { channelId } = initializeAddCardFrame("your-client-token");
const cleanup = setupAddCardListener(channelId);

// When done, clean up the listener
// cleanup();

Buy Button frame

The Buy Button frame takes a quote to payment. It renders the Apple Pay, Google Pay, or card button that matches the payment method in your quote, and supports guest checkout when your quote allows it. For card and bank transfer quotes, you can also run it in headless mode behind your own purchase button. See the Buy Button frame reference for event details, and Pay with the buy button for the full walkthrough.

Apple Pay and Google Pay need the payment permission policy, so set allow="payment" on the iframe. If you sandbox the iframe, include allow-scripts, allow-popups, allow-same-origin, and allow-forms, plus allow-modals for the test-mode payment dialog. See Permissions.

Apple Pay is available in Safari on macOS and in every iOS browser. Check availability before you request an Apple Pay quote.

What you’ll need

Before you initialize the Buy Button frame, you need:

A clientToken from a successful connect flow
A valid quote signature for the transaction

Initialize the frame

The function creates the iframe inside a container element with the ID moonpay-buy-button and sizes it 44px tall. The button fills the container width. See Size.

function initializeBuyButtonFrame(
  clientToken: string,
  quoteSignature: string,
  externalTransactionId?: string,
  applePayButtonSettings?: Record<string, string>,
  googlePayButtonSettings?: Record<string, string>,
) {
  const container = document.getElementById(
    "moonpay-buy-button",
  ) as HTMLElement;
  const channelId = crypto.randomUUID();

  // Create the iframe here, since challenge handling removes it when the purchase ends
  const iframe = document.createElement("iframe");
  iframe.style.cssText = "width: 100%; height: 44px; border: none;";

  // Required for Apple Pay and Google Pay: enables the Payment Request API inside the iframe
  iframe.allow = "payment";

  const params = new URLSearchParams({
    clientToken,
    channelId,
    signature: quoteSignature,
    ...(externalTransactionId && { externalTransactionId }),
    ...(applePayButtonSettings && {
      applePayButtonSettings: JSON.stringify(applePayButtonSettings),
    }),
    ...(googlePayButtonSettings && {
      googlePayButtonSettings: JSON.stringify(googlePayButtonSettings),
    }),
  });

  iframe.src = `${FRAME_ORIGIN}/platform/v1/buy-button?${params.toString()}`;
  container.appendChild(iframe);

  return { iframe, channelId };
}

applePayButtonSettings and googlePayButtonSettings are optional. The frame applies the one that matches the button it renders. URLSearchParams URL-encodes each value. For the keys and validation rules, see Apple Pay button settings and Google Pay button settings.

Handle events

interface BuyButtonTransaction {
  // Missing when a failed transaction was never created
  id?: string;
  status: "pending" | "completed" | "failed";
  failureCode?: string;
  failureReason?: string;
}

interface BuyButtonChallengePayload {
  kind: string;
  url: string;
}

function setupBuyButtonListener(
  channelId: string,
  iframe: HTMLIFrameElement,
  onComplete: (transaction: BuyButtonTransaction) => void,
  onChallenge: (url: string) => void,
  onError?: (error: { code: string; message: string }) => void,
) {
  const handler = (event: MessageEvent) => {
    const data = parseFrameMessage(event, channelId);
    if (!data) return;

    switch (data.kind) {
      case "handshake":
        sendFrameMessage(iframe, channelId, "ack");
        break;

      case "ready":
        console.log("Buy Button frame ready");
        break;

      case "complete":
        const payload = data.payload as { transaction: BuyButtonTransaction };
        if (payload.transaction.status === "failed") {
          // Branch on failureCode; failureReason is developer-facing only
          console.error(
            "Transaction failed:",
            payload.transaction.failureCode,
            payload.transaction.failureReason,
          );
        }
        onComplete(payload.transaction);
        break;

      case "challenge":
        const challenge = data.payload as BuyButtonChallengePayload;
        onChallenge(challenge.url);
        break;

      case "cancelled":
        // The customer dismissed the Apple Pay or Google Pay sheet.
        // The button stays on screen, so the customer can tap it again.
        console.log("Payment sheet dismissed");
        break;

      case "error":
        const error = data.payload as { code: string; message: string };
        if (error.code === "quoteExpired") {
          // Fetch a new quote and send it to the frame
          console.log("Quote expired, fetching new quote...");
          // updateBuyButtonQuote(iframe, channelId, newQuoteSignature);
        } else {
          console.error("Buy Button error:", error.code, error.message);
        }
        onError?.(error);
        break;
    }
  };

  window.addEventListener("message", handler);

  return () => window.removeEventListener("message", handler);
}

Update the quote

When the quote expires or changes, send a new quote to the frame:

function updateBuyButtonQuote(
  iframe: HTMLIFrameElement,
  channelId: string,
  newQuoteSignature: string,
) {
  sendFrameMessage(iframe, channelId, "setQuote", {
    quote: { signature: newQuoteSignature },
  });
}

Challenge handling

When the Buy Button frame emits a challenge event, for example for 3-D Secure, open the challenge URL in a new iframe inside a modal. The challenge frame is self-driving after the handshake. Opened without resume, as below, it finishes the purchase for every payment method and sends complete. To have the customer finish an Apple Pay or Google Pay purchase on your buy button instead, see Finish on your buy button.

interface ChallengeCompletePayload {
  flow: "buy";
  transaction: BuyButtonTransaction;
}

function setupChallengeListener(
  challengeChannelId: string,
  challengeIframe: HTMLIFrameElement,
  buyButtonIframe: HTMLIFrameElement,
  buyButtonCleanup: () => void,
  onResult: (transaction: BuyButtonTransaction | null) => void,
) {
  const handler = (event: MessageEvent) => {
    const data = parseFrameMessage(event, challengeChannelId);
    if (!data) return;

    switch (data.kind) {
      case "handshake":
        sendFrameMessage(challengeIframe, challengeChannelId, "ack");
        break;

      case "ready":
        console.log("Challenge frame ready");
        break;

      case "complete":
        const payload = data.payload as ChallengeCompletePayload;
        cleanup();
        onResult(payload.transaction);
        break;

      case "cancelled":
        cleanup();
        onResult(null);
        break;

      case "error":
        const error = data.payload as { code: string; message: string };
        console.error("Challenge error:", error.code, error.message);
        cleanup();
        onResult(null);
        break;
    }
  };

  function cleanup() {
    window.removeEventListener("message", handler);
    buyButtonCleanup();
    challengeIframe.remove();
    buyButtonIframe.remove();
  }

  window.addEventListener("message", handler);

  return cleanup;
}

function openChallengeFrame(
  challengeUrl: string,
  clientToken: string,
  buyButtonIframe: HTMLIFrameElement,
  buyButtonCleanup: () => void,
  onResult: (transaction: BuyButtonTransaction | null) => void,
) {
  const modal = document.getElementById("challengeModal") as HTMLElement;
  const challengeChannelId = crypto.randomUUID();

  const urlWithParams = new URL(challengeUrl);
  urlWithParams.searchParams.set("clientToken", clientToken);
  urlWithParams.searchParams.set("channelId", challengeChannelId);

  const challengeIframe = document.createElement("iframe");
  // Wallet quotes show the Apple Pay or Google Pay sheet in the challenge frame
  challengeIframe.allow = "payment";
  challengeIframe.src = urlWithParams.toString();
  modal.appendChild(challengeIframe);

  return setupChallengeListener(
    challengeChannelId,
    challengeIframe,
    buyButtonIframe,
    buyButtonCleanup,
    onResult,
  );
}

Usage

const { iframe: buyButtonIframe, channelId } = initializeBuyButtonFrame(
  "your-client-token",
  "your-quote-signature",
);

const buyButtonCleanup = setupBuyButtonListener(
  channelId,
  buyButtonIframe,
  (transaction) => {
    console.log("Transaction initiated:", transaction.id);
    // Navigate to transaction status screen or poll for updates
  },
  (challengeUrl) => {
    openChallengeFrame(
      challengeUrl,
      "your-client-token",
      buyButtonIframe,
      buyButtonCleanup,
      (transaction) => {
        if (!transaction) {
          console.log("Challenge cancelled or errored");
        } else if (transaction.status === "failed") {
          // Branch on failureCode; failureReason is developer-facing only
          console.error("Challenge failed:", transaction.failureCode);
        } else {
          console.log("Challenge complete:", transaction.id);
        }
      },
    );
  },
);

// When done, clean up the listener
// buyButtonCleanup();

Headless mode

For card and bank transfer quotes, you can draw your own purchase button and run the Buy Button frame with headless=true. The frame renders nothing and starts the purchase as soon as it loads, so mount it at zero size when the customer confirms the purchase in your UI, not before. See Headless mode.

function initializeHeadlessBuyButtonFrame(
  clientToken: string,
  quoteSignature: string,
  externalTransactionId?: string,
) {
  const channelId = crypto.randomUUID();

  const params = new URLSearchParams({
    clientToken,
    channelId,
    signature: quoteSignature,
    headless: "true",
    ...(externalTransactionId && { externalTransactionId }),
  });

  // Headless mode renders nothing, so keep the frame out of your layout
  // and out of the accessibility tree and tab order
  const iframe = document.createElement("iframe");
  iframe.style.cssText =
    "position: absolute; width: 0; height: 0; border: none; overflow: hidden;";
  iframe.setAttribute("aria-hidden", "true");
  iframe.tabIndex = -1;
  iframe.src = `${FRAME_ORIGIN}/platform/v1/buy-button?${params.toString()}`;
  document.body.appendChild(iframe);

  return { iframe, channelId };
}

Reuse setupBuyButtonListener, updateBuyButtonQuote, and challenge handling with the headless iframe. In headless mode, the frame:

Sends ready, then exactly one of complete, challenge, or error.
Never sends buttonPressed or cancelled.
Accepts card and bank transfer (SEPA) quotes only. An Apple Pay or Google Pay quote returns error with unsupportedPaymentMethod.
Needs a connected customer. A guest checkout quote returns error with invalidQuote.
Reads setQuote only after an error with quoteExpired.

On challenge, open the challenge frame without resume, as in challenge handling. It finishes the purchase and sends its own complete. After complete, or an error other than quoteExpired, stop the listener and remove the iframe. Mount a new frame if the customer tries again.

// Call this when the customer confirms the purchase in your UI
function startHeadlessPurchase(clientToken: string, quoteSignature: string) {
  const { iframe, channelId } = initializeHeadlessBuyButtonFrame(
    clientToken,
    quoteSignature,
  );

  const stopListening = setupBuyButtonListener(
    channelId,
    iframe,
    (transaction) => {
      stopListening();
      iframe.remove();
      if (transaction.status === "failed") {
        // Show the failure in your UI, and let the customer try again
        return;
      }
      console.log("Transaction initiated:", transaction.id);
    },
    (challengeUrl) => {
      // Challenge handling removes the headless iframe when it finishes
      openChallengeFrame(
        challengeUrl,
        clientToken,
        iframe,
        stopListening,
        (transaction) => {
          console.log("Challenge result:", transaction?.status);
        },
      );
    },
    (error) => {
      if (error.code === "quoteExpired") {
        // Fetch a new quote and send it with updateBuyButtonQuote
        return;
      }
      stopListening();
      iframe.remove();
    },
  );
}

For a bank transfer (SEPA) quote, the complete event returns the transaction id. Fetch the transaction by id, and show the customer the bank details from bankTransferDepositInfo and the amount to send from source.amount in your own UI so they can send the transfer. See Pay with bank transfer.

For bank transfers, the customer must include the payment reference from bankTransferDepositInfo with their transfer, or it is rejected. Render the deposit details, including the reference, in your own UI. See the transaction object.

To hand the whole purchase to MoonPay, including amount entry and payment method selection, use the widget frame. It renders the full MoonPay buy experience inside an iframe, including payment collection and transaction confirmation. See pay with widget for a full walkthrough.

What you’ll need

Before you initialize the widget frame, you need:

A clientToken from a successful connect flow
A valid quote signature for the transaction

Initialize the frame

The widget iframe requires the payment permission policy to process payments.

function initializeWidgetFrame(
  clientToken: string,
  quoteSignature: string,
  externalTransactionId?: string,
) {
  const iframe = document.getElementById("moonpay-frame") as HTMLIFrameElement;
  const channelId = crypto.randomUUID();

  // The widget requires the "payment" permission policy
  iframe.allow = "payment";

  const params = new URLSearchParams({
    flow: "buy",
    clientToken,
    quoteSignature,
    channelId,
    ...(externalTransactionId && { externalTransactionId }),
  });

  iframe.src = `${FRAME_ORIGIN}/platform/v1/widget?${params.toString()}`;

  return { iframe, channelId };
}

Handle events

interface WidgetCompletePayload {
  transaction:
    | { id: string; status: "complete" | "pending" }
    | { status: "failed"; failureReason: string };
}

function setupWidgetListener(channelId: string) {
  const iframe = document.getElementById("moonpay-frame") as HTMLIFrameElement;

  const handler = (event: MessageEvent) => {
    const data = parseFrameMessage(event, channelId);
    if (!data) return;

    switch (data.kind) {
      case "handshake":
        sendFrameMessage(iframe, channelId, "ack");
        break;

      case "ready":
        console.log("Widget loaded and visible");
        break;

      case "transactionCreated":
        const created = data.payload as {
          transaction: { id: string; status: string };
        };
        console.log("Transaction created:", created.transaction.id);
        // Customer may still need to complete 3-D Secure
        break;

      case "complete":
        const payload = data.payload as WidgetCompletePayload;
        if (payload.transaction.status === "failed") {
          console.error(
            "Transaction failed:",
            payload.transaction.failureReason,
          );
        } else {
          console.log("Transaction initiated:", payload.transaction.id);
          // Poll for transaction status or wait for webhook
        }
        break;

      case "error":
        const error = data.payload as { code: string; message: string };
        console.error("Widget error:", error.code, error.message);
        break;
    }
  };

  window.addEventListener("message", handler);

  return () => window.removeEventListener("message", handler);
}

Usage

const { channelId } = initializeWidgetFrame(
  "your-client-token",
  "your-quote-signature",
);
const cleanup = setupWidgetListener(channelId);

// When done, clean up the listener
// cleanup();

Reset frame

The reset frame is headless. Use it when the customer signs out of your app to clear MoonPay session state on MoonPay’s domain. See reset frame reference. Pass the same clientToken you received from connect or auth so your domain is authorized to embed the frame. Do not block sign-out if reset fails or times out.

Initialize the frame

function initializeResetFrame(clientToken: string) {
  const channelId = crypto.randomUUID();

  const params = new URLSearchParams({
    channelId,
    clientToken,
  });

  const iframe = document.createElement("iframe");
  iframe.style.cssText =
    "position: absolute; width: 0; height: 0; border: none; overflow: hidden;";
  iframe.src = `${FRAME_ORIGIN}/platform/v1/reset?${params.toString()}`;
  document.body.appendChild(iframe);

  return { iframe, channelId };
}

Handle events

function setupResetListener(
  channelId: string,
  iframe: HTMLIFrameElement,
  onComplete: () => void,
  onError?: (code: string, message: string) => void,
) {
  const handler = (event: MessageEvent) => {
    const data = parseFrameMessage(event, channelId);
    if (!data) return;

    switch (data.kind) {
      case "handshake":
        sendFrameMessage(iframe, channelId, "ack");
        break;

      case "complete":
        cleanup();
        onComplete();
        break;

      case "error":
        const error = data.payload as { code: string; message: string };
        cleanup();
        onError?.(error.code, error.message);
        break;
    }
  };

  const cleanup = () => {
    window.removeEventListener("message", handler);
    iframe.remove();
  };

  window.addEventListener("message", handler);

  return cleanup;
}

Usage

// After clearing your own local credentials:
const { iframe, channelId } = initializeResetFrame("your-client-token");
setupResetListener(channelId, iframe, () => {
  console.log("MoonPay session cleared");
});

​Setup

​Encryption

​Message utilities

​Encryption utility

​Key generation

​Decryption

​Check frame

​Initialize the frame

​Handle events

​Usage

​Connect frame

​Initialize the frame

​Handle events

​Usage

​Auth frame

​Initialize the frame

​Handle events

​Usage

​Add Card frame

​What you’ll need

​Initialize the frame

​Handle events

​Usage

​Buy Button frame

​What you’ll need

​Initialize the frame

​Handle events

​Update the quote

​Challenge handling

​Usage

​Headless mode

​Widget frame

​What you’ll need

​Initialize the frame

​Handle events

​Usage

​Reset frame

​Initialize the frame

​Handle events

​Usage

Setup

Encryption

Message utilities

Encryption utility

Key generation

Decryption

Check frame

Initialize the frame

Handle events

Usage

Connect frame

Initialize the frame

Handle events

Usage

Auth frame

Initialize the frame

Handle events

Usage

Add Card frame

What you’ll need

Initialize the frame

Handle events

Usage

Buy Button frame

What you’ll need

Initialize the frame

Handle events

Update the quote

Challenge handling

Usage

Headless mode

Widget frame

What you’ll need

Initialize the frame

Handle events

Usage

Reset frame

Initialize the frame

Handle events

Usage