client.setupBuyButton()

Render the Buy Button frame into your UI. The frame renders a single payment button that matches the payment method in the quote (Apple Pay, Google Pay, or a saved card) and runs the buy pipeline on tap. Use it when you want MoonPay to render the payment button. Pass headless: true to run the same purchase with no button. Use headless mode for saved-card and bank transfer (SEPA) quotes when you draw your own purchase button.

The button covers Apple Pay, Google Pay, and saved-card quotes. For bank transfers (SEPA), render your own button and call setupBuyButton() with headless: true. See Bank transfer.

The buy button can emit a challenge event mid-pipeline. Render a separate challenge frame using client.setupChallenge() at the URL from the event payload.

Setup buy button

import { createClient, type BuyButtonEvent } from "@moonpay/platform-sdk-web";

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

const buyButtonResult = await client.setupBuyButton({
  quote: quoteResult.value.data.signature,
  container: document.querySelector("#buyButtonContainer"),
  onEvent: (event: BuyButtonEvent) => {
    switch (event.kind) {
      case "ready":
        // Button is rendered — hide any loading placeholder.
        break;
      case "buttonPressed":
        // Customer tapped the button — show a loading state or fire analytics.
        break;
      case "complete":
        // Inspect FrameTransaction before polling.
        if (event.payload.transaction.status !== "failed") {
          pollTransaction(event.payload.transaction.id);
        }
        break;
      case "challenge":
        // Hand off to the challenge frame at the provided URL.
        handleChallenge(event.payload.url);
        break;
      case "cancelled":
        // Customer dismissed the Apple Pay or Google Pay sheet. The button stays on screen.
        break;
      case "error":
        console.error(event.payload.code, event.payload.message);
        break;
    }
  },
});

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

const buyButton = buyButtonResult.value;

Parameters

Property	Type	Required	Description
`quote`	`string`	✅	The quote `signature` returned from `getQuote`.
`container`	`HTMLElement`	✅	A DOM element to render the buy button into. In headless mode, it hosts the hidden frame.
`externalTransactionId`	`string`		Partner-assigned identifier for this transaction attempt. Useful for reconciliation.
`headless`	`boolean`		Pass `true` to run the purchase on load with no button. Card and SEPA bank transfer quotes only; Apple Pay and Google Pay quotes need the button. Defaults to `false`. See Headless mode.
`applePayButtonSettings`	`ApplePayButtonSettings`		Styles the Apple Pay button variant. Pass an object; the SDK serializes it for you. Has no effect on the card or Google Pay button, or in headless mode.
`googlePayButtonSettings`	`GooglePayButtonSettings`		Styles the Google Pay button variant. Pass an object; the SDK serializes it for you. Has no effect on the card or Apple Pay button, or in headless mode.
`onEvent`	`(event: BuyButtonEvent) => void`		Callback invoked for buy-button events. See `BuyButtonEvent`.

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

Button settings

Pass applePayButtonSettings and googlePayButtonSettings as plain objects. The SDK serializes each one and passes it to the frame, which applies the one that matches the button it renders. You can pass both. Every property is optional, and the frame ignores a property with an invalid value while still applying the rest. For the allowed values and validation rules, see the frame reference: Apple Pay button settings and Google Pay button settings.

Style the wallet buttons

const buyButtonResult = await client.setupBuyButton({
  quote: quoteResult.value.data.signature,
  container: document.querySelector("#buyButtonContainer"),
  applePayButtonSettings: { style: "black", height: "48", borderRadius: "28" },
  googlePayButtonSettings: { style: "black", height: "48", borderRadius: "28" },
});

The default button is 44px high. If you set a custom height, size the container to match it.

Property	Type	Apple Pay	Google Pay	Description
`width`	`string`	✅	✅	Width in pixels, as `"320"` or `"320px"`.
`height`	`string`	✅	✅	Height in pixels. Defaults to `44px`.
`borderRadius`	`string`	✅	✅	Corner radius in pixels. Defaults to `16px`.
`paddingX`	`string`	✅	✅	Horizontal padding in pixels. On Google Pay, setting only `paddingY` makes this `0px`.
`paddingY`	`string`	✅	✅	Vertical padding in pixels. On Google Pay, setting only `paddingX` makes this `0px`.
`style`	`"black"` \| `"white"` \| `"white-outline"`	✅	✅	The button’s visual style. On Google Pay, `white` and `white-outline` render the same white button with an outline.
`type`	`string`	✅		The Apple Pay button label, such as `"buy"` or `"pay"`.
`locale`	`string`	✅		The Apple Pay button language, such as `"fr-FR"`.

Both types are exported from @moonpay/platform-sdk-web. The settings have no effect when you call setupBuyButton with headless: true, since the frame renders no button.

`BuyButtonEvent`

onEvent receives events as the buy pipeline progresses.

kind	Payload	When you receive it
`"ready"`	—	The button is rendered and ready for the customer to tap. For Apple Pay and Google Pay, this fires once the device is confirmed to support the wallet. Use it to hide any loading placeholder. In headless mode, the purchase is starting: show a loading state.
`"buttonPressed"`	—	The customer tapped the pay button, before the Apple Pay or Google Pay sheet appears, or before the card pipeline runs. An intent-to-buy signal with no payload; it still fires if the customer then cancels. Not a purchase outcome; listen for `"complete"` for the result. Not sent in headless mode.
`"complete"`	`{ transaction:` `FrameTransaction; sessionUpgraded?: true }`	The pipeline finished. Inspect the `FrameTransaction` to detect the failure variant. After a guest checkout recovery that finished on this button with `resume`, it also carries `sessionUpgraded: true`: create a new session and check the connection again.
`"challenge"`	`{ kind: string; url: string }`	Verification is required before the transaction can proceed. Render the challenge frame at the provided `url`. For an Apple Pay or Google Pay quote, open the challenge with `resume: true` and keep this button mounted to have the customer pay on this button afterwards. See Finish on your buy button. For a card or bank transfer quote, including headless mode, open the challenge without `resume`: it finishes the purchase and sends its own `"complete"`.
`"cancelled"`	`{ code: "payment_sheet_dismissed"; message: string }`	The customer dismissed the Apple Pay or Google Pay sheet without paying. This is not a failure: the button stays on screen and the customer can tap it again. Not sent for card payments or in headless mode.
`"error"`	`BuyButtonEventError`	The purchase could not run. Surface to logs and tear down the frame, except after `quoteExpired`: fetch a new quote and pass it to `setQuote()`.

`FrameTransaction`

FrameTransaction is a discriminated union — the failure variant carries failureCode and failureReason, the non-failure variant always carries id. Pass id to client.getTransaction() to poll for the final status.

Field	Type	Required	Description
`status`	`string`	✅	The transaction status. On the failure variant, `"failed"`.
`id`	`string`		Required on the non-failure variant; optional when `status` is `"failed"`.
`failureReason`	`string`		Present only on the failure variant (`status === "failed"`).
`failureCode`	`FrameTransactionFailureCode`		Present only on the failure variant (`status === "failed"`). Why the payment failed. See the failure codes.

`BuyButtonEventError`

Field	Type	Required	Description
`code`	`string`	✅	The error category: `configurationError`, `invalidQuote`, `quoteExpired`, `unsupportedPaymentMethod`, `applePayUnavailable`, `googlePayUnavailable`, or `generic`. See the Buy Button frame. A failed payment arrives as `"complete"`, not `"error"`.
`message`	`string`	✅	Developer-friendly details. Not intended to be rendered in UI.

Result

client.setupBuyButton() returns a Result<BuyButtonFrame, SetupBuyButtonError>.

Result envelope

Result<BuyButtonFrame, SetupBuyButtonError>

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

`BuyButtonFrame`

Field	Type	Required	Description
`setQuote`	`(signature: string) => void`	✅	Updates the quote signature used by the frame. With the button, use this when the current quote expires before the customer taps it. In headless mode, call it only after an `"error"` with code `quoteExpired`: the frame retries the purchase with the new quote and ignores `setQuote` at any other time.
`dispose`	`() => void`	✅	Unmounts the frame. After you call this, no further events are dispatched to your `onEvent` callback.

`SetupBuyButtonError`

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

Headless mode

Pass headless: true when you draw your own purchase button. The frame renders nothing inside container and starts the purchase as soon as it loads. Call setupBuyButton() when the customer confirms the purchase in your UI, not before, because setting up the frame is what starts the purchase. Headless mode sends the same BuyButtonEvent events, with these differences:

It accepts saved-card and bank transfer (sepa) quotes for a connected customer only. An Apple Pay or Google Pay quote gets an "error" with code unsupportedPaymentMethod, and a guest checkout quote gets invalidQuote.
It never sends "buttonPressed" or "cancelled".
After "ready", it sends exactly one of "complete", "challenge", or "error".
It reads setQuote() only after an "error" with code quoteExpired. At any other time the frame ignores it, so it never starts a second purchase.
On "challenge", open the challenge frame without resume. The challenge frame finishes the purchase and sends its own "complete".

For the frame-level behavior, see Headless mode on the Buy Button frame.

Headless mode with a saved card

import {
  createClient,
  type BuyButtonEvent,
  type ChallengeEvent,
} from "@moonpay/platform-sdk-web";

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

// Setting up the frame starts the purchase, so wait for your own button.
document.querySelector("#payButton").addEventListener("click", async () => {
  const buyResult = await client.setupBuyButton({
    quote: quoteResult.value.data.signature, // A quote for a saved card
    container: document.querySelector("#buyContainer"),
    headless: true,
    onEvent: async (event: BuyButtonEvent) => {
      switch (event.kind) {
        case "ready":
          showLoadingIndicator();
          break;

        case "complete":
          buyResult.value.dispose();
          if (event.payload.transaction.status !== "failed") {
            pollTransaction(event.payload.transaction.id);
          }
          break;

        case "challenge":
          // Open the challenge without `resume`. It finishes the purchase.
          handleChallenge(event.payload.url);
          break;

        case "error":
          if (event.payload.code === "quoteExpired") {
            // Keep the frame and retry with a fresh quote.
            buyResult.value.setQuote(await refreshQuoteSignature());
            break;
          }
          buyResult.value.dispose();
          console.error(event.payload.code, event.payload.message);
          break;
      }
    },
  });

  if (!buyResult.ok) {
    console.error(buyResult.error.kind, buyResult.error.message);
    return;
  }

  async function handleChallenge(challengeUrl: string) {
    await client.setupChallenge({
      url: challengeUrl,
      container: document.querySelector("#challengeModal"),
      onEvent: (event: ChallengeEvent) => {
        switch (event.kind) {
          case "complete":
            // The challenge frame finished the purchase.
            buyResult.value.dispose();
            if (event.payload.flow === "buy") {
              pollTransaction(event.payload.transaction.id);
            }
            break;
          case "cancelled":
          case "error":
            buyResult.value.dispose();
            break;
        }
      },
    });
  }
});

For the end-to-end card payment walkthrough, see the Pay with card guide. For details on the challenge flow, see Handle challenges.

Bank transfer

Bank transfer payments (SEPA for EUR) use the same headless flow as cards. You fetch a bank transfer quote, call setupBuyButton() with headless: true, and read the transaction id from the "complete" event. The difference is what happens after the transaction is created: the customer sends the funds from their bank. Fetch the transaction with the id and show the customer the bank details from bankTransferDepositInfo, including the payment reference, and the amount to send from source.amount. Bank transfers are a floating payment method, so the amounts are estimates until the transfer settles. The quote returns exchangeRateType: "floating". Render the estimated crypto amount with a tilde (for example, ~0.2345 BTC) and tell the customer the final amount is set when their funds settle. See Exchange rate type. For the full walkthrough, including confirming availability, rendering the deposit details, handling requotes and cancellations, and tracking the transaction to a terminal status, see the Pay with bank transfer guide.

Buy with a bank transfer

import { createClient, type BuyButtonEvent } from "@moonpay/platform-sdk-web";

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

// 1. Get a bank transfer quote (SEPA for EUR).
const quoteResult = await client.getQuote({
  source: { asset: { code: "EUR" }, amount: "100.00" },
  destination: { asset: { code: "ETH" } },
  wallet: { address: "0x1234567890abcdef1234567890abcdef12345678" },
  paymentMethod: { type: "sepa" },
});
if (!quoteResult.ok) throw new Error(quoteResult.error.message);

// 2. Start the purchase from your own pay button.
const buyResult = await client.setupBuyButton({
  quote: quoteResult.value.data.signature,
  container: document.querySelector("#buyContainer"),
  headless: true,
  onEvent: (event: BuyButtonEvent) => {
    if (
      event.kind === "complete" &&
      event.payload.transaction.status !== "failed"
    ) {
      // 3. Read the deposit details and render them natively.
      showDepositDetails(event.payload.transaction.id);
    }
  },
});
if (!buyResult.ok) throw new Error(buyResult.error.message);

async function showDepositDetails(transactionId: string) {
  const result = await client.getTransaction(transactionId);
  if (!result.ok) throw new Error(result.error.message);

  const transaction = result.value.data;

  // Render the bank details in your own UI, then keep polling for status.
  renderBankTransferScreen({
    depositInfo: transaction.bankTransferDepositInfo,
    // source.amount is the exact fiat amount, including fees, the customer transfers.
    amount: transaction.source.amount,
    currency: transaction.source.asset.code,
  });
}

The customer must include the payment reference with their bank transfer. Transfers sent without it are rejected. Surface this prominently in your own UI, for example, “Always include your payment reference or your transfer will be rejected.” See Bank-transfer deposit details.

TS Definitions

types.ts

type BuyButtonFrame = {
  setQuote: (signature: string) => void;
  dispose: () => void;
};

type GooglePayButtonSettings = {
  width?: string;
  height?: string;
  borderRadius?: string;
  paddingX?: string;
  paddingY?: string;
  style?: "black" | "white-outline" | "white";
};

type ApplePayButtonSettings = {
  width?: string;
  height?: string;
  borderRadius?: string;
  paddingX?: string;
  paddingY?: string;
  style?: "black" | "white-outline" | "white";
  type?:
    | "plain"
    | "buy"
    | "top-up"
    | "reload"
    | "continue"
    | "check-out"
    | "pay";
  locale?: string;
};

type FrameTransactionFailureCode =
  | "applePayMerchantUnavailable"
  | "authorizationDeclined"
  | "serviceUnavailable"
  | "transactionDeclined"
  | "transactionNotAllowed"
  | "unknown"
  | "validationError";

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

type BuyButtonEvent =
  | { kind: "ready" }
  | { kind: "buttonPressed" }
  | {
      kind: "complete";
      payload: { transaction: FrameTransaction; sessionUpgraded?: true };
    }
  | {
      kind: "challenge";
      payload: { kind: string; url: string };
    }
  | {
      kind: "cancelled";
      payload: { code: "payment_sheet_dismissed"; message: string };
    }
  | { kind: "error"; payload: BuyButtonEventError };

type BuyButtonEventError = {
  code:
    | "configurationError"
    | "invalidQuote"
    | "quoteExpired"
    | "unsupportedPaymentMethod"
    | "applePayUnavailable"
    | "googlePayUnavailable"
    | "generic";
  message: string;
};

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

Overview

Customers

Payments

Integration essentials

SDK Reference

Frames

Parameters

Button settings

`BuyButtonEvent`

`FrameTransaction`

`BuyButtonEventError`

Result

Result envelope

`BuyButtonFrame`

`SetupBuyButtonError`

Headless mode

Bank transfer

​Parameters

​Button settings

​BuyButtonEvent

​FrameTransaction

​BuyButtonEventError

​Result

​Result envelope

​BuyButtonFrame

​SetupBuyButtonError

​Headless mode

​Bank transfer

Parameters

Button settings

`BuyButtonEvent`

`FrameTransaction`

`BuyButtonEventError`

Result

Result envelope

`BuyButtonFrame`

`SetupBuyButtonError`

Headless mode

Bank transfer