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.
externalTransactionId	string		Your own identifier for the transaction. Stored and associated with the MoonPay transaction for correlation.
theme	string		Pass dark or light to force a specific appearance. If you omit this, the frame uses the user’s system appearance.

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"
}

type Message<T> = T & {
  version: 2;
  meta: { channelId: string };
};

type HandshakeEvent = Message<{
  kind: "handshake";
}>;

ready

The widget finished loading and the UI is visible.

Example

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

type Message<T> = T & {
  version: 2;
  meta: { channelId: string };
};

type ReadyEvent = Message<{
  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"
    }
  }
}

type Message<T> = T & {
  version: 2;
  meta: { channelId: string };
};

type TransactionCreatedEvent = Message<{
  kind: "transactionCreated";
  payload: {
    transaction: {
      /** The MoonPay identifier for this transaction. **/
      id: string;
      /** The current status of the transaction. **/
      status: string;
    };
  };
}>;

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"
    }
  }
}

{
  "version": 2,
  "meta": { "channelId": "ch_1" },
  "kind": "complete",
  "payload": {
    "transaction": {
      "status": "failed",
      "failureReason": "The payment could not be completed."
    }
  }
}

type Message<T> = T & {
  version: 2;
  meta: { channelId: string };
};

enum TransactionStatus {
  complete = "complete",
  pending = "pending",
  failed = "failed",
}

type Transaction =
  | {
      /** The MoonPay identifier for this transaction. **/
      id: string;
      /** The status of the transaction. **/
      status: TransactionStatus.complete | TransactionStatus.pending;
    }
  | {
      status: TransactionStatus.failed;
      /** A developer-friendly error message detailing the reason for the transaction failure. **/
      failureReason: string;
    };

type WidgetCompleteEvent = Message<{
  kind: "complete";
  payload: {
    transaction: Transaction;
  };
}>;

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

type Message<T> = T & {
  version: 2;
  meta: { channelId: string };
};

type WidgetError = Message<{
  kind: "error";
  payload: {
    code: "configurationError" | "apiError" | "generic";
    /** A developer-facing error message. Not intended for end-user display. */
    message: string;
  };
}>;

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"
}

type Message<T> = T & {
  version: 2;
  meta: { channelId: string };
};

type AckEvent = Message<{
  kind: "ack";
}>;