client.setupWidget()

Render the MoonPay buy widget and initiate a transaction with a quote signature. The quote must have executable: true — a non-executable quote will not render. The provider presents the widget in a full-screen native modal and handles the full purchase flow — including payment collection, verification, and transaction confirmation.

Setup widget

import {
  useMoonPay,
  type WidgetEvent,
} from "@moonpay/platform-sdk-react-native";

export function WidgetScreen({ quoteSignature }: { quoteSignature: string }) {
  const { client } = useMoonPay();

  const start = async () => {
    const widgetResult = await client.setupWidget({
      quote: quoteSignature,
      onEvent: (event: WidgetEvent) => {
        switch (event.kind) {
          case "ready":
            break;
          case "transactionCreated":
            console.log(event.payload.transaction);
            break;
          case "complete":
            console.log(event.payload.transaction);
            break;
          case "close":
            // The customer closed the widget
            break;
          case "error":
            console.error(event.payload.code, event.payload.message);
            break;
        }
      },
    });

    if (!widgetResult.ok) {
      // Handle error
      console.error(widgetResult.error.kind, widgetResult.error.message);
      return;
    }

    const widget = widgetResult.value;
  };

  // ...
}

Parameters

Property	Type	Required	Description
`quote`	`string`	✅	The quote `signature` returned from `getQuote`.
`externalTransactionId`	`string`		Partner-assigned identifier for this transaction attempt. Useful for reconciliation.
`onEvent`	`(event: WidgetEvent) => void`		Callback invoked for widget flow events. See `WidgetEvent`.

This method does not require a separate auth token. The client uses stored credentials from an active connection.

`WidgetEvent`

onEvent receives events as the widget flow progresses. Use event.kind to decide how to handle each event.

kind	Payload	When you receive it
`"ready"`	—	The widget is loaded and ready to be shown.
`"transactionCreated"`	`{ transaction: { id: string; status: string } }`	A transaction has been created. The customer may still need to complete additional steps (for example, 3-D Secure).
`"complete"`	`{ transaction:` `FrameTransaction` `}`	The widget flow finished. `FrameTransaction` is a discriminated union — handle the `"failed"` variant separately.
`"close"`	—	The customer closed the widget.
`"error"`	`WidgetEventError`	The flow encountered an error.

`FrameTransaction`

The transaction reported by the widget on "complete". The shape depends on the outcome.

Field	Type	Required	Description
`id`	`string`		Present on the success variant. Required when `status !== "failed"`; optional when `status` is `"failed"`.
`status`	`string`	✅	The transaction status. On the failure variant this is `"failed"`.
`failureReason`	`string`		Present only on the failure variant (`status === "failed"`).

To track the final status after "complete", pass transaction.id to client.getTransaction().

`WidgetEventError`

Field	Type	Required	Description
`code`	`"configurationError"` \| `"apiError"` \| `"generic"`	✅	The error category.
`message`	`string`	✅	Developer-friendly details.

Result

client.setupWidget() returns a Result<WidgetFrame, SetupWidgetError>.

Result envelope

Result<WidgetFrame, SetupWidgetError>

Field	Type	Required	Description
`ok`	`boolean`	✅	Whether the operation succeeded.
`value`	`WidgetFrame`		Present when `ok` is `true`.
`error`	`SetupWidgetError`		Present when `ok` is `false`.

`WidgetFrame`

Field	Type	Required	Description
`dispose`	`() => void`	✅	Unmounts the frame. After you call this, no further events are dispatched to your `onEvent` callback.

`SetupWidgetError`

Field	Type	Required	Description
`kind`	`"configurationError"` \| `"apiError"` \| `"genericError"`	✅	The error category.
`message`	`string`	✅	Developer-friendly details.

TS Definitions

types.ts

type WidgetFrame = {
  dispose: () => void;
};

type FrameTransaction =
  | { id: string; status: string }
  | { id?: string; status: "failed"; failureReason: string };

type WidgetEvent =
  | { kind: "ready" }
  | {
      kind: "transactionCreated";
      payload: { transaction: { id: string; status: string } };
    }
  | {
      kind: "complete";
      payload: { transaction: FrameTransaction };
    }
  | { kind: "close" }
  | { kind: "error"; payload: WidgetEventError };

type WidgetEventError = {
  code: "configurationError" | "apiError" | "generic";
  message: string;
};

type SetupWidgetError = {
  kind: "configurationError" | "apiError" | "genericError";
  message: string;
};

Overview

Customers

Payments

Integration essentials

SDK Reference

Frames

Parameters

`WidgetEvent`

`FrameTransaction`

`WidgetEventError`

Result

Result envelope

`WidgetFrame`

`SetupWidgetError`

​Parameters

​WidgetEvent

​FrameTransaction

​WidgetEventError

​Result

​Result envelope

​WidgetFrame

​SetupWidgetError

Parameters

`WidgetEvent`

`FrameTransaction`

`WidgetEventError`

Result

Result envelope

`WidgetFrame`

`SetupWidgetError`