Skip to main content
Render the MoonPay buy widget into your UI and initiate a transaction with a quote signature. The quote must have executable: true. The widget handles the full purchase flow — including payment-method selection, verification, and transaction confirmation — inside an iframe.
Setup widget
import { createClient, type WidgetEvent } from "@moonpay/platform-sdk-web";

const client = createClient({ sessionToken: "c3N0XzAwMQ==" });

const widgetResult = await client.setupWidget({
  quote: quoteResult.value.data.signature,
  container: document.querySelector("#widgetContainer"),
  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

PropertyTypeRequiredDescription
quotestring✅The quote signature returned from getQuote.
containerHTMLElement✅A DOM element to render the widget frame into.
onEvent(event: WidgetEvent) => voidCallback 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.
kindPayloadWhen 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"WidgetEventErrorThe flow encountered an error.

​
FrameTransaction

The transaction reported by the widget on "complete". The shape depends on the outcome.
FieldTypeRequiredDescription
idstringPresent on the success variant. Required when status !== "failed"; optional when status is "failed".
statusstring✅The transaction status. On the failure variant this is "failed".
failureReasonstringPresent only on the failure variant (status === "failed").
To track the final status after "complete", pass transaction.id to client.getTransaction().

​
WidgetEventError

FieldTypeRequiredDescription
code"configurationError" | "apiError" | "generic"✅The error category.
messagestring✅Developer-friendly details.

​
Result

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

​
Result envelope

Result<WidgetFrame, SetupWidgetError>
FieldTypeRequiredDescription
okboolean✅Whether the operation succeeded.
valueWidgetFramePresent when ok is true.
errorSetupWidgetErrorPresent when ok is false.

​
WidgetFrame

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

​
SetupWidgetError

FieldTypeRequiredDescription
kind"configurationError" | "apiError" | "genericError"✅The error category.
messagestring✅Developer-friendly details.
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;
};