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

# 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](/platform/guides/connect-a-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.

<CodeGroup>
  ```ts Get quote (pre-select payment method) theme={null}
  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
  }
  ```

  ```ts Get quote (customer chooses) theme={null}
  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
  }
  ```
</CodeGroup>

<Callout icon="circle-info" iconType="regular">
  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](/platform/guides/pay-with-apple-pay) for native
  Apple Pay.
</Callout>

## Render the widget

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

```ts Widget theme={null}
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.

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