Skip to main content

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.

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 "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

PropertyTypeRequiredDescription
quotestring✅The quote signature returned from getQuote.
containerHTMLElement✅A DOM element to render the buy button into.
onEvent(event: BuyButtonEvent) => voidCallback 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. Unlike setupBuy(), the buy-button frame does not emit a ready event — the button renders synchronously and there is nothing to wait for before showing it.
kindPayloadWhen you receive it
"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"BuyButtonEventErrorThe 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.
FieldTypeRequiredDescription
statusstring✅The transaction status. On the failure variant, "failed".
idstringRequired on the non-failure variant; optional when status is "failed".
failureReasonstringPresent only on the failure variant (status === "failed").

​
BuyButtonEventError

FieldTypeRequiredDescription
codestring✅The error category. Includes configurationError, invalidQuote, and backend-specific error codes.
messagestring✅Developer-friendly details. Not intended to be rendered in UI.

​
Result

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

​
Result envelope

Result<BuyButtonFrame, SetupBuyButtonError>
FieldTypeRequiredDescription
okboolean✅Whether the operation succeeded.
valueBuyButtonFramePresent when ok is true.
errorSetupBuyButtonErrorPresent when ok is false.

​
BuyButtonFrame

FieldTypeRequiredDescription
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

FieldTypeRequiredDescription
kind"configurationError" | "genericError"✅The error category.
messagestring✅Developer-friendly details.
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: "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;
};