Skip to main content

Documentation Index

Fetch the complete documentation index at: https://dev.moonpay.com/llms.txt

Use this file to discover all available pages before exploring further.

​
URL

https://blocks.moonpay.com/platform/v1/widget

​
Requirements

​
Permissions

The payment permission policy is required.
Example
<iframe src="https://blocks.moonpay.com/platform/v1/widget" allow="payment" />

​
Initialization parameters

PropertyTypeRequiredDescription
flowstring✅The transaction flow. Currently only buy is supported.
clientTokenstring✅The client token returned from the connect flow.
quoteSignaturestring✅The quote signature from the quote endpoint. Pass signature as returned.
channelIdstring✅A unique identifier for the frame generated on your client. This value is attached to each postMessage payload to help identify messages.

The format of this string is up to you.

​
Events

All events are dispatched using the message pattern described in the frames protocol. Below are the event payloads specific to the widget frame.

​
Outbound events

frame->parent These events are sent from this frame to the parent window.

​
handshake

The frame requests that you open a message channel. 
{
  "version": 2,
  "meta": { "channelId": "ch_1" },
  "kind": "handshake"
}

​
ready

The widget finished loading and the UI is visible. 
{
  "version": 2,
  "meta": { "channelId": "ch_1" },
  "kind": "ready"
}

​
transactionCreated

A transaction has been initiated. The customer may still need to complete additional steps such as 3-D Secure authorization. 
{
  "version": 2,
  "meta": { "channelId": "ch_1" },
  "kind": "transactionCreated",
  "payload": {
    "transaction": {
      "id": "txn_01",
      "status": "waitingAuthorization"
    }
  }
}

​
complete

The transaction has reached a terminal state. Use the transaction ID to track status updates via polling or webhooks. 
{
  "version": 2,
  "meta": { "channelId": "ch_1" },
  "kind": "complete",
  "payload": {
    "transaction": {
      "id": "txn_01",
      "status": "complete"
    }
  }
}

​
error

An error occurred in the widget flow. 
{
  "version": 2,
  "meta": { "channelId": "ch_1" },
  "kind": "error",
  "payload": {
    "code": "apiError",
    "message": "Failed to build widget URL."
  }
}

​
Inbound events

parent->frame These events are sent from the parent window to this frame.

​
ack

Acknowledge the handshake. 
{
  "version": 2,
  "meta": { "channelId": "ch_1" },
  "kind": "ack"
}