Skip to main content
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.

Message utilities

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

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

Decryption

decrypt.ts

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

Handle events

Usage


Connect frame

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

Initialize the frame

Handle events

Usage


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:
  1. A clientToken from a successful connect flow
  2. A valid quote signature for the transaction

Initialize the frame

Handle events

Update the quote

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

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:
  1. A clientToken from a successful connect flow
  2. A valid quote signature for the transaction

Initialize the frame

Handle events

Update the quote

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

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:
  1. A clientToken from a successful connect flow

Initialize the frame

Handle events

Usage


Buy frame

The buy frame processes a card payment for a quote. It is headless — rendered at zero size — while the customer completes payment. If 3-D Secure is required, the frame emits a challenge event with a URL you open in a separate challenge frame. See buy frame reference for event details.

What you’ll need

Before you initialize the buy frame, you need:
  1. A clientToken from a successful connect flow
  2. A valid quote signature for the transaction

Initialize the frame

Handle events

Update the quote

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

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:

Usage


Widget frame

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-method selection and transaction confirmation. See pay with widget for a full walkthrough.

What you’ll need

Before you initialize the widget frame, you need:
  1. A clientToken from a successful connect flow
  2. A valid quote signature for the transaction

Initialize the frame

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

Handle events

Usage