client.setupBuyButton()

Render the MoonPay-hosted buy button and run the buy pipeline on tap.

Render the Buy button frame into your UI. The frame renders a payment button — card, Apple Pay, or Google Pay, depending on what’s available — and runs the buy pipeline on tap. Use it when you want a single payment button instead of orchestrating individual payment-method frames yourself.

Like the headless Buy frame, 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 "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.
externalTransactionId	string		Partner-assigned identifier for this transaction attempt. Useful for reconciliation.
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.

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.
"buttonPressed"	—	The customer tapped the pay button, before the payment sheet appears. 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.
"complete"	{ transaction: FrameTransaction }	The pipeline finished. Inspect the FrameTransaction to detect the failure variant.
"challenge"	{ kind: string; url: string }	Verification is required before the transaction can proceed. Render the challenge frame at the provided url.
"error"	BuyButtonEventError	The flow encountered an error. Surface to logs and tear down the frame.

FrameTransaction

FrameTransaction is a discriminated union — the failure variant carries 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").

BuyButtonEventError

Field	Type	Required	Description
code	string	✅	The error category. Includes configurationError, invalidQuote, and backend-specific error codes.
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. Use this when the current quote expires before the customer taps the button — fetch a new quote and pass its signature.
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.

TS Definitions

types.ts

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

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

type BuyButtonEvent =
  | { kind: "ready" }
  | { kind: "buttonPressed" }
  | {
      kind: "complete";
      payload: { transaction: FrameTransaction };
    }
  | {
      kind: "challenge";
      payload: { kind: string; url: string };
    }
  | { kind: "error"; payload: BuyButtonEventError };

type BuyButtonEventError = {
  code: string;
  message: string;
};

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