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: { asset: { code: "USD" }, amount: "100.00" },
  destination: { asset: { code: "ETH" } },
  wallet: { address: "0x1234..." },
  paymentMethod: { type: "credit_debit_card" }, // Pre-selects credit/debit card
});

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

const quoteResult = await client.getQuote({
  source: { asset: { code: "USD" }, amount: "100.00" },
  destination: { asset: { code: "ETH" } },
  wallet: { address: "0x1234..." },
  // No paymentMethod — customer selects inside the widget
});

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

Supported paymentMethod.type 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-sdk-web";

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.

Compare payment methods

The widget is one of five ways to run a buy. See Choose a payment method to compare it with Apple Pay, Google Pay, card, and the buy button. Use getPaymentMethods() to determine which methods are available and choose the flow that fits your experience.