client.setupBuy()

client.setupBuy() is deprecated. Use client.setupBuyButton() with headless: true instead. It runs the same purchase with no visible UI and sends the same events. Existing setupBuy() calls keep working. Build new integrations with setupBuyButton().

Mount a hidden frame into your UI and execute a transaction from a quote signature. The frame renders no visible UI. It drives the buy pipeline in the background and emits events you handle from your own purchase screen. MoonPay serves it as the Buy Button frame in headless mode.

The frame is headless. When it emits a challenge event, render a separate challenge frame with client.setupChallenge() at the URL from the event payload. See the Handle challenges guide for the full flow.

Setup buy

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

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

const buyResult = await client.setupBuy({
  quote: quoteResult.value.data.signature,
  container: document.querySelector("#buyContainer"),
  externalTransactionId: "order_12345",
  onEvent: (event: BuyEvent) => {
    switch (event.kind) {
      case "ready":
        // Pipeline starting — show a loading indicator
        break;
      case "complete":
        // Transaction created. Track final status via polling.
        console.log(event.payload.transaction);
        break;
      case "challenge":
        // Verification required — render the challenge frame at the URL.
        // See: /platform/guides/handling-challenges
        openChallengeFrame(event.payload.url);
        break;
      case "error":
        console.error(event.payload.code, event.payload.message);
        break;
    }
  },
});

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

const buy = buyResult.value;

Parameters

Property	Type	Required	Description
`quote`	`string`	✅	The quote `signature` returned from `getQuote`.
`container`	`HTMLElement`	✅	A DOM element to mount the hidden frame into. The frame has zero dimensions and renders no visible UI.
`externalTransactionId`	`string`		Your own identifier for the transaction. Stored on the MoonPay transaction for correlation.
`onEvent`	`(event: BuyEvent) => void`		Callback invoked for buy flow events. See `BuyEvent`.

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

`BuyEvent`

onEvent receives events as the buy pipeline progresses. Use event.kind to decide how to handle each event.

kind	Payload	When you receive it
`"ready"`	—	The buy pipeline has started. Show a loading state in your own UI.
`"complete"`	`{ transaction:` `FrameTransaction` `}`	The pipeline finished. If `status` is `"failed"`, the payment didn’t go through: read `failureCode`. Otherwise use the transaction `id` to poll for final status.
`"challenge"`	`BuyChallengePayload`	Verification is required before the transaction can proceed. Render the challenge frame at the provided `url` using `setupChallenge()`.
`"error"`	`BuyEventError`	The flow encountered an error. Surface the message to developers and tear down the frame.

`FrameTransaction`

This is the transaction object returned when the buy pipeline completes. 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"` (a transaction may not exist yet on early failure).
`failureReason`	`string`		Present only on the failure variant (`status === "failed"`). A developer-friendly reason.
`failureCode`	`FrameTransactionFailureCode`		Present only on the failure variant (`status === "failed"`). Why the payment failed. See the failure codes.

`BuyChallengePayload`

Field	Type	Required	Description
`kind`	`string`	✅	The challenge type (currently always `"frame"`, but typed as `string` for forward compatibility).
`url`	`string`	✅	A fully-formed URL to pass directly to `setupChallenge()`. Do not modify it.

`BuyEventError`

Field	Type	Required	Description
`code`	`string`	✅	The error category: `configurationError`, `invalidQuote`, `quoteExpired`, `unsupportedPaymentMethod`, 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.setupBuy() returns a Result<BuyFrame, SetupBuyError>.

Result envelope

Result<BuyFrame, SetupBuyError>

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

`BuyFrame`

Field	Type	Required	Description
`setQuote`	`(signature: string) => void`	✅	Sends a new quote to the frame after an `"error"` with code `quoteExpired`. The frame retries the purchase with it. At any other time the frame ignores it.
`dispose`	`() => void`	✅	Unmounts the frame. After you call this, no further events are dispatched to your `onEvent` callback. Always call `dispose()` once the flow finishes or errors out.

`SetupBuyError`

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

Full example

The following example walks through the full card-payment flow: get a quote for a stored card, start the purchase in a hidden frame, hand off to a challenge frame when verification is required, and dispose of the frame when the transaction completes.

Buy with a stored card

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

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

// 1. Get a quote for the selected stored card.
const quoteResult = await client.getQuote({
  source: { asset: { code: "USD" }, amount: "100.00" },
  destination: { asset: { code: "ETH" } },
  wallet: { address: "0x1234567890abcdef1234567890abcdef12345678" },
  paymentMethod: { type: "card", id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890" },
});
if (!quoteResult.ok) throw new Error(quoteResult.error.message);

// 2. Start the purchase in a hidden frame.
const buyResult = await client.setupBuy({
  quote: quoteResult.value.data.signature,
  container: document.querySelector("#buyContainer"),
  externalTransactionId: "order_12345",
  onEvent: (event: BuyEvent) => {
    switch (event.kind) {
      case "ready":
        showLoadingIndicator();
        break;

      case "challenge":
        // 3. Hand off to the challenge frame for verification.
        handleChallenge(event.payload.url);
        break;

      case "complete":
        // The transaction was created (or failed). Inspect FrameTransaction
        // before polling — `id` is only required on the non-failure variant.
        buyResult.value.dispose();
        if (event.payload.transaction.status !== "failed") {
          pollTransaction(event.payload.transaction.id);
        }
        break;

      case "error":
        buyResult.value.dispose();
        console.error(event.payload.code, event.payload.message);
        showError(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":
          // Verification resolved. For buy challenges, the transaction is in payload.
          if (event.payload.flow === "buy") {
            pollTransaction(event.payload.transaction.id);
          }
          buyResult.value.dispose();
          break;

        case "cancelled":
          buyResult.value.dispose();
          showRetryOption();
          break;

        case "error":
          buyResult.value.dispose();
          console.error(event.payload.message);
          break;
      }
    },
  });
}

For the end-to-end card payment walkthrough — listing payment methods, adding a card, and tracking the transaction to a terminal status — 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 setupBuy() with its signature, 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 BuyEvent } 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.setupBuy({
  quote: quoteResult.value.data.signature,
  container: document.querySelector("#buyContainer"),
  onEvent: (event: BuyEvent) => {
    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);

  // Render bankTransferDepositInfo in your own UI, then keep polling for status.
  renderBankTransferScreen(result.value.data.bankTransferDepositInfo);
}

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 BuyFrame = {
  setQuote: (signature: string) => void;
  dispose: () => void;
};

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

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

type BuyEvent =
  | {
      kind: "ready";
    }
  | {
      kind: "complete";
      payload: {
        transaction: FrameTransaction;
      };
    }
  | {
      kind: "challenge";
      payload: {
        /** Currently "frame", but typed as `string` for forward compatibility. */
        kind: string;
        /** Fully-formed URL to pass directly to setupChallenge(). */
        url: string;
      };
    }
  | {
      kind: "error";
      payload: BuyEventError;
    };

type BuyEventError = {
  /**
   * Includes "configurationError", "invalidQuote", and backend-specific
   * error codes returned during the buy pipeline.
   */
  code: string;
  message: string;
};

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

Overview

Customers

Payments

Integration essentials

SDK Reference

Frames

Parameters

`BuyEvent`

`FrameTransaction`

`BuyChallengePayload`

`BuyEventError`

Result

Result envelope

`BuyFrame`

`SetupBuyError`

Full example

Bank transfer

​Parameters

​BuyEvent

​FrameTransaction

​BuyChallengePayload

​BuyEventError

​Result

​Result envelope

​BuyFrame

​SetupBuyError

​Full example

​Bank transfer

Parameters

`BuyEvent`

`FrameTransaction`

`BuyChallengePayload`

`BuyEventError`

Result

Result envelope

`BuyFrame`

`SetupBuyError`

Full example

Bank transfer