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:- A
clientTokenfrom a successful connect flow - 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:- A
clientTokenfrom a successful connect flow - 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:- A
clientTokenfrom 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 achallenge 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:- A
clientTokenfrom a successful connect flow - 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 achallenge 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:- A
clientTokenfrom 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.