> ## 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.

# Widget

> Details on working with the [widget](/platform/guides/pay-with-widget) frame.

## URL

```html theme={null}
https://blocks.moonpay.com/platform/v1/widget
```

## Requirements

### Permissions

The `payment` [permission policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy#iframes) is required.

```tsx Example theme={null}
<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](/platform/guides/api-and-sdk-credentials#client-token) returned from the [connect flow](/platform/guides/connect-a-customer).                                               |
| `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.<br /><br />The format of this string is up to you. |
| `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](/platform/frames/overview#frames-protocol#messages). Below are the event payloads specific to the widget frame.

### Outbound events

<Badge size="md" className="px-2" color="purple">
  frame->parent
</Badge>

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

#### `handshake`

The frame requests that you open a message channel.

<CodeGroup>
  ```json Example theme={null}
  {
    "version": 2,
    "meta": { "channelId": "ch_1" },
    "kind": "handshake"
  }
  ```

  ```ts twoslash TypeScript definition theme={null}
  type Message<T> = T & {
    version: 2;
    meta: { channelId: string };
  };

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

#### `ready`

The widget finished loading and the UI is visible.

<CodeGroup>
  ```json Example theme={null}
  {
    "version": 2,
    "meta": { "channelId": "ch_1" },
    "kind": "ready"
  }
  ```

  ```ts twoslash TypeScript definition theme={null}
  type Message<T> = T & {
    version: 2;
    meta: { channelId: string };
  };

  type ReadyEvent = Message<{
    kind: "ready";
  }>;
  ```
</CodeGroup>

#### `transactionCreated`

A transaction has been initiated. The customer may still need to complete additional steps such as 3-D Secure authorization.

<CodeGroup>
  ```json Example theme={null}
  {
    "version": 2,
    "meta": { "channelId": "ch_1" },
    "kind": "transactionCreated",
    "payload": {
      "transaction": {
        "id": "txn_01",
        "status": "waitingAuthorization"
      }
    }
  }
  ```

  ```ts twoslash TypeScript definition theme={null}
  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;
      };
    };
  }>;
  ```
</CodeGroup>

#### `complete`

The transaction has reached a terminal state. Use the transaction ID to track status updates via polling or webhooks.

<CodeGroup>
  ```json Example (success) theme={null}
  {
    "version": 2,
    "meta": { "channelId": "ch_1" },
    "kind": "complete",
    "payload": {
      "transaction": {
        "id": "txn_01",
        "status": "complete"
      }
    }
  }
  ```

  ```json Example (fail) theme={null}
  {
    "version": 2,
    "meta": { "channelId": "ch_1" },
    "kind": "complete",
    "payload": {
      "transaction": {
        "status": "failed",
        "failureReason": "The payment could not be completed."
      }
    }
  }
  ```

  ```ts twoslash TypeScript definition theme={null}
  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;
    };
  }>;
  ```
</CodeGroup>

#### `error`

An error occurred in the widget flow.

<CodeGroup>
  ```json Example theme={null}
  {
    "version": 2,
    "meta": { "channelId": "ch_1" },
    "kind": "error",
    "payload": {
      "code": "apiError",
      "message": "Failed to build widget URL."
    }
  }
  ```

  ```ts twoslash TypeScript definition theme={null}
  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;
    };
  }>;
  ```
</CodeGroup>

### Inbound events

<Badge size="md" className="px-2">
  parent->frame
</Badge>

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

#### `ack`

Acknowledge the [handshake](#handshake).

<CodeGroup>
  ```json Example theme={null}
  {
    "version": 2,
    "meta": { "channelId": "ch_1" },
    "kind": "ack"
  }
  ```

  ```ts twoslash TypeScript definition theme={null}
  type Message<T> = T & {
    version: 2;
    meta: { channelId: string };
  };

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