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 in your app. The provider mounts the frame as a react-native-webview showing 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 {
  useMoonPay,
  type BuyButtonEvent,
} from "@moonpay/platform-sdk-react-native";

export function BuyButtonScreen({
  quoteSignature,
}: {
  quoteSignature: string;
}) {
  const { client } = useMoonPay();

  const start = async () => {
    const buyButtonResult = await client.setupBuyButton({
      quote: quoteSignature,
      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.
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;
};