Widget

Details on working with the widget frame.

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

Property	Type	Required	Description
flow	string	✅	The transaction flow. Currently only buy is supported.
clientToken	string	✅	The client token returned from the connect flow.
quoteSignature	string	✅	The quote signature from the quote endpoint. Pass signature as returned.
channelId	string	✅	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.

Example

{
  "version": 2,
  "meta": { "channelId": "ch_1" },
  "kind": "handshake"
}

ready

The widget finished loading and the UI is visible.

Example

{
  "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.

Example

{
  "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.

Example (success)

{
  "version": 2,
  "meta": { "channelId": "ch_1" },
  "kind": "complete",
  "payload": {
    "transaction": {
      "id": "txn_01",
      "status": "complete"
    }
  }
}

error

An error occurred in the widget flow.

Example

{
  "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.

Example

{
  "version": 2,
  "meta": { "channelId": "ch_1" },
  "kind": "ack"
}