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();

Apple Pay frame

The Apple Pay frame renders the Apple Pay button and handles the payment flow. See Apple Pay frame reference for event details.

Apple Pay only works on Safari (macOS and iOS). Check availability before rendering.

What you’ll need

Before you initialize the Apple Pay frame, you need:

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

Initialize the frame

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

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

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

  return { iframe, channelId };
}

Handle events

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

function setupApplePayListener(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("Apple Pay button ready");
        break;

      case "complete":
        const payload = data.payload as ApplePayCompletePayload;
        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 "challenge":
        const challengePayload = data.payload as { kind: string; url: string };
        // Open the challenge URL in a new iframe — see "Challenge handling" below
        console.log("Challenge required:", challengePayload.url);
        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...");
          // updateApplePayQuote(iframe, channelId, newQuoteSignature);
        } else {
          console.error("Apple Pay error:", error.code, error.message);
        }
        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 updateApplePayQuote(
  iframe: HTMLIFrameElement,
  channelId: string,
  newQuoteSignature: string,
) {
  sendFrameMessage(iframe, channelId, "setQuote", {
    quote: { signature: newQuoteSignature },
  });
}

Google Pay frame

The Google Pay frame renders the Google Pay button and handles the payment flow. See Google Pay frame reference for event details.

The Google Pay frame requires the payment permission policy. When using a sandboxed iframe, include allow-scripts, allow-popups, allow-same-origin, and allow-forms. See Google Pay inside sandboxed iframe for details.

What you’ll need

Before you initialize the Google Pay frame, you need:

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

Initialize the frame

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

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

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

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

  return { iframe, channelId };
}

Handle events

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

function setupGooglePayListener(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("Google Pay button ready");
        break;

      case "complete":
        const payload = data.payload as GooglePayCompletePayload;
        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 "challenge":
        const challengePayload = data.payload as { kind: string; url: string };
        // Open the challenge URL in a new iframe — see "Challenge handling" below
        console.log("Challenge required:", challengePayload.url);
        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...");
          // updateGooglePayQuote(iframe, channelId, newQuoteSignature);
        } else {
          console.error("Google Pay error:", error.code, error.message);
        }
        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 updateGooglePayQuote(
  iframe: HTMLIFrameElement,
  channelId: string,
  newQuoteSignature: string,
) {
  sendFrameMessage(iframe, channelId, "setQuote", {
    quote: { signature: newQuoteSignature },
  });
}

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 frame

The buy frame processes a card or bank-transfer payment for a quote. It is headless — rendered at zero size — while the customer completes payment. For cards, if 3-D Secure is required, the frame emits a challenge event with a URL you open in a separate challenge frame. For bank transfers (SEPA, EUR), quote with paymentMethod.type set to "sepa"; the complete event returns a transaction that stays pending and carries a bankTransferDepositInfo object you render natively so the customer can send the deposit. See the buy frame reference for event details, and Pay with bank transfer for the full bank-transfer walkthrough.

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.

What you’ll need

Before you initialize the buy frame, you need:

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

Initialize the frame

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

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

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

  return { iframe, channelId };
}

Handle events

interface BuyCompletePayload {
  transaction: { id: string; status: string };
}

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

function setupBuyListener(
  channelId: string,
  iframe: HTMLIFrameElement,
  onComplete: (transaction: { id: string; status: string }) => void,
  onChallenge: (url: 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 frame ready");
        break;

      case "complete":
        const payload = data.payload as BuyCompletePayload;
        console.log("Transaction complete:", payload.transaction.id);
        onComplete(payload.transaction);
        break;

      case "challenge":
        const challenge = data.payload as BuyChallengePayload;
        onChallenge(challenge.url);
        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...");
          // updateBuyQuote(iframe, channelId, newQuoteSignature);
        } else {
          console.error("Buy error:", error.code, error.message);
        }
        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 updateBuyQuote(
  iframe: HTMLIFrameElement,
  channelId: string,
  newQuoteSignature: string,
) {
  sendFrameMessage(iframe, channelId, "setQuote", {
    quote: { signature: newQuoteSignature },
  });
}

Challenge handling

When the buy frame emits a challenge event, open the challenge URL in a new iframe inside a modal. The challenge frame is self-driving after the handshake:

interface ChallengeCompletePayload {
  flow: "buy";
  transaction: { id: string; status: string };
}

function setupChallengeListener(
  challengeChannelId: string,
  challengeIframe: HTMLIFrameElement,
  buyIframe: HTMLIFrameElement,
  buyCleanup: () => void,
  onResult: (transaction: { id: string; status: string } | 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);
    buyCleanup();
    challengeIframe.remove();
    buyIframe.remove();
  }

  window.addEventListener("message", handler);

  return cleanup;
}

function openChallengeFrame(
  challengeUrl: string,
  clientToken: string,
  buyIframe: HTMLIFrameElement,
  buyCleanup: () => void,
  onResult: (transaction: { id: string; status: string } | 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");
  challengeIframe.src = urlWithParams.toString();
  modal.appendChild(challengeIframe);

  return setupChallengeListener(
    challengeChannelId,
    challengeIframe,
    buyIframe,
    buyCleanup,
    onResult,
  );
}

Usage

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

const buyCleanup = setupBuyListener(
  channelId,
  buyIframe,
  (transaction) => {
    console.log("Transaction initiated:", transaction.id);
    // Navigate to transaction status screen or poll for updates
  },
  (challengeUrl) => {
    openChallengeFrame(
      challengeUrl,
      "your-client-token",
      buyIframe,
      buyCleanup,
      (transaction) => {
        if (transaction) {
          console.log("Challenge complete:", transaction.id);
        } else {
          console.log("Challenge cancelled or failed");
        }
      },
    );
  },
);

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

Buy Button frame

The Buy Button frame consolidates Apple Pay, Google Pay, and card into a single MoonPay-hosted button that matches the payment method in your quote. It runs the same buy pipeline as the buy frame and supports guest checkout when your quote allows it. See buy button frame reference and Pay with the buy button.

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

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

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

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

  return { iframe, channelId };
}

Handle events

The Buy Button frame uses the same events as the buy frame. Reuse setupBuyListener, updateBuyQuote, and challenge handling — point them at the Buy Button iframe instead of the headless buy iframe.

const { iframe, channelId } = initializeBuyButtonFrame(
  "your-client-token",
  "your-quote-signature",
);
const cleanup = setupBuyListener(
  channelId,
  iframe,
  (transaction) => console.log("Complete:", transaction.id),
  (url) => openChallengeModal(url),
);

For payment methods beyond Apple Pay — including credit/debit cards, Google Pay, bank transfers, and more — 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

​Apple Pay frame

​What you’ll need

​Initialize the frame

​Handle events

​Update the quote

​Google Pay frame

​What you’ll need

​Initialize the frame

​Handle events

​Update the quote

​Add Card frame

​What you’ll need

​Initialize the frame

​Handle events

​Usage

​Buy frame

​What you’ll need

​Initialize the frame

​Handle events

​Update the quote

​Challenge handling

​Usage

​Buy Button frame

​What you’ll need

​Initialize the frame

​Handle events

​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

Apple Pay frame

What you’ll need

Initialize the frame

Handle events

Update the quote

Google Pay frame

What you’ll need

Initialize the frame

Handle events

Update the quote

Add Card frame

What you’ll need

Initialize the frame

Handle events

Usage

Buy frame

What you’ll need

Initialize the frame

Handle events

Update the quote

Challenge handling

Usage

Buy Button frame

What you’ll need

Initialize the frame

Handle events

Widget frame

What you’ll need

Initialize the frame

Handle events

Usage

Reset frame

Initialize the frame

Handle events

Usage