client.setupBuyButton()

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.

The buy button covers card, Apple Pay, and Google Pay. For bank transfers (SEPA), render your own button and open the headless Buy frame with client.setupBuy() instead.

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;
};

Overview

Customers

Payments

Integration essentials

SDK Reference

Frames

Parameters

`BuyButtonEvent`

`FrameTransaction`

`BuyButtonEventError`

Result

Result envelope

`BuyButtonFrame`

`SetupBuyButtonError`

​Parameters

​BuyButtonEvent

​FrameTransaction

​BuyButtonEventError

​Result

​Result envelope

​BuyButtonFrame

​SetupBuyButtonError

Parameters

`BuyButtonEvent`

`FrameTransaction`

`BuyButtonEventError`

Result

Result envelope

`BuyButtonFrame`

`SetupBuyButtonError`