Pay with widget

Render the MoonPay buy widget to support all payment methods and regions.

Use this guide to render the MoonPay buy widget after you have a connected customer. The widget renders the full MoonPay buy experience — including payment-method selection and transaction confirmation — inside an iframe in your application. It supports all payment methods and regions available in the standard MoonPay integration.

Prerequisites

• A connected customer (via client.getConnection() or client.connect()).
• A UI surface where you can render the widget frame (for example, a modal or full-screen container).

Get a quote

Request a quote for the transaction. The widget requires an executable quote with a wallet address.

If you include a paymentMethod in the quote, the widget pre-selects that method. If you omit it, the customer picks one inside the widget.

Get quote (pre-select payment method)

const quoteResult = await client.getQuote({
  source: "USD",
  destination: "ETH",
  sourceAmount: "100.00",
  walletAddress: "0x1234...",
  paymentMethod: "credit_debit_card", // Pre-selects credit/debit card
});

if (!quoteResult.ok) {
  // Handle error
}

Supported paymentMethod values include credit_debit_card, google_pay, sepa_bank_transfer, gbp_bank_transfer, gbp_open_banking_payment, pix_instant_payment, interac, paypal, revolut_pay, venmo, and moonpay_balance. If the pre-selected method is unavailable for the customer, the widget falls back to the payment selection screen. Passing apple_pay pre-selects the card form instead — use the headless Apple Pay flow for native Apple Pay.

Render the widget

Pass the quote signature to setupWidget. The widget handles the entire purchase flow inside the iframe.

Widget

import type { WidgetEvent } from "@moonpay/platform";

const widgetResult = await client.setupWidget({
  quote: quoteResult.value.signature,

  container: document.querySelector("#widgetContainer"),

  onEvent: (event: WidgetEvent) => {
    switch (event.kind) {
      case "ready":
        // The widget is loaded and visible.
        break;

      case "transactionCreated":
        // A transaction has been initiated. The customer may still
        // need to complete additional steps (for example, 3-D Secure).
        console.log(event.payload.transaction);
        // { id: "txn_01", status: "waitingAuthorization" }
        break;

      case "complete":
        // The transaction has reached a terminal state.
        console.log(event.payload.transaction);
        // { id: "txn_01", status: "pending" }
        break;

      case "error":
        console.error(event.payload.message);
        break;
    }
  },
});

if (!widgetResult.ok) {
  // Handle error setting up the widget
}

// Clean up when done
// widgetResult.value.dispose();

Transaction statuses

• waitingAuthorization: The transaction has been created but the customer needs to complete an authorization step (for example, 3-D Secure).
• Pending: The payment has been accepted and the assets are being transferred.
• Complete: The transaction is finalized and the assets have been delivered.
• Failed: The transaction has failed. No payment was applied.

Choosing between Apple Pay and the widget

Criteria	Apple Pay	Widget
Payment methods	Apple Pay only	All supported methods
UI control	Headless — you own the UI	MoonPay-hosted UI
Regions	Where Apple Pay is available	All supported regions
Best for	Streamlined single-tap checkout	Broad payment coverage

Both flows start from a connected customer and a quote. Use getPaymentMethods() to determine which methods are available and choose the flow that fits your experience.