<MoonPayBuyButton />

Inline buy button for Apple Pay, Google Pay, and card quotes, or a headless purchase behind your own button.

<MoonPayBuyButton> renders the Buy Button frame inline in your layout. The frame renders the payment button that matches the payment method in the quote (Apple Pay, Google Pay, or a saved card) and runs the purchase on tap.

Pass headless to run the same purchase with no button. Use headless mode for saved-card and bank transfer (SEPA) quotes when you draw your own native purchase button.

Apple Pay and Google Pay inside a WebView have extra requirements. See Mobile WebViews. When the wallet isn’t available, the component emits an "error" with code applePayUnavailable or googlePayUnavailable: offer another payment method.

BuyButtonSection.tsx

import React from "react";
import {
  MoonPayBuyButton,
  MoonPayChallenge,
  type BuyButtonEvent,
} from "@moonpay/platform-sdk-react-native";

export function BuyButtonSection({
  quoteSignature,
}: {
  quoteSignature: string;
}) {
  const [challengeUrl, setChallengeUrl] = React.useState<string | null>(null);

  const handleEvent = (event: BuyButtonEvent) => {
    switch (event.kind) {
      case "buttonPressed":
        // Customer tapped the button — show a loading state or fire analytics.
        break;
      case "complete":
        console.log(event.payload.transaction);
        break;
      case "challenge":
        setChallengeUrl(event.payload.url);
        break;
      case "cancelled":
        // Customer dismissed the Apple Pay or Google Pay sheet. The button stays on screen.
        break;
      case "error":
        console.error(event.payload.code, event.payload.message);
        break;
    }
  };

  return (
    <>
      <MoonPayBuyButton quote={quoteSignature} onEvent={handleEvent} />
      {challengeUrl && (
        <MoonPayChallenge
          url={challengeUrl}
          onEvent={(e) => {
            if (e.kind === "complete" || e.kind === "cancelled") {
              setChallengeUrl(null);
            }
          }}
        />
      )}
    </>
  );
}

---

Props

Prop	Type	Required	Default	Description
quote	string	✅	—	Quote signature from getQuote(). Reactive — updating this prop pushes the new signature into the frame without a remount.
externalTransactionId	string		—	Partner-assigned identifier for this transaction attempt. Mount-time only.
headless	boolean		false	Render nothing visible and start the purchase on mount. Card and SEPA bank transfer quotes only; Apple Pay and Google Pay quotes need the button. Mount-time only. See Headless mode.
applePayButtonSettings	ApplePayButtonSettings		—	Styles the Apple Pay button variant. Has no effect on the card or Google Pay button, or in headless mode. Mount-time only.
googlePayButtonSettings	GooglePayButtonSettings		—	Styles the Google Pay button variant. Has no effect on the card or Apple Pay button, or in headless mode. Mount-time only.
onEvent	(event: BuyButtonEvent) => void		—	Callback for buy button lifecycle events. See BuyButtonEvent.
style	ViewStyle		height: 48	Container style. Ignored in headless mode.

Button settings

Pass applePayButtonSettings and googlePayButtonSettings as plain objects. The frame applies the one that matches the button it renders, so you can pass both. Every property is optional. Both settings are read at mount only. The imperative client.setupBuyButton() method accepts the same two options.

Style the wallet buttons

<MoonPayBuyButton
  quote={quoteSignature}
  applePayButtonSettings={{ style: "black", height: "48", borderRadius: "28" }}
  googlePayButtonSettings={{ style: "black", height: "48", borderRadius: "28" }}
  style={{ height: 48 }}
  onEvent={handleEvent}
/>

Set the height in the component’s style prop to match the button height you choose. Both settings take width, height, borderRadius, paddingX, paddingY, and style (black, white, or white-outline). Apple Pay also takes type and locale. On Google Pay, white and white-outline render the same white button with an outline. The settings have no effect in headless mode, since the frame renders no button.

For the allowed values, defaults, and validation rules, see Apple Pay button settings and Google Pay button settings. Both types are exported from @moonpay/platform-sdk-react-native.

BuyButtonEvent

Use event.kind to handle each event.

kind	Payload	When you receive it
"ready"	—	The button is rendered and ready for the customer to tap. In headless mode, the purchase is starting: show a loading state.
"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. Not sent in headless mode.
"complete"	{ transaction: FrameTransaction; sessionUpgraded?: true }	The payment finished. Inspect FrameTransaction for the outcome. After a guest checkout recovery that finished on this button with resume, it also carries sessionUpgraded: true: create a new session and check the connection again.
"challenge"	{ kind: "frame"; url: string }	Verification required. Render <MoonPayChallenge> with the provided URL. For an Apple Pay or Google Pay quote, open the challenge with resume: true and keep this button mounted to have the customer pay on this button afterwards. See Finish on your buy button. For a card or bank transfer quote, including headless mode, open the challenge without resume: it finishes the purchase and sends its own "complete".
"cancelled"	{ code: "payment_sheet_dismissed"; message: string }	The customer dismissed the Apple Pay or Google Pay sheet without paying. This is not a failure: the button stays on screen and the customer can tap it again. Not sent for card payments or in headless mode.
"error"	{ code: string; message: string }	The purchase could not run. code is one of configurationError, invalidQuote, quoteExpired, unsupportedPaymentMethod, applePayUnavailable, googlePayUnavailable, or generic. See the Buy Button frame. A failed payment arrives as "complete", not "error".

When the quote expires, the frame emits an "error" event with code: "quoteExpired". Fetch a new quote and update the quote prop to retry.

FrameTransaction

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".
failureReason	string		Present only on the failure variant (status === "failed").
failureCode	FrameTransactionFailureCode		Present only on the failure variant (status === "failed"). Why the payment failed. See the failure codes.

Headless mode

Pass headless when you draw your own native purchase button. The component renders nothing visible and starts the purchase as soon as it mounts. Mount it when the customer confirms the purchase in your UI, not before, because mounting it is what starts the purchase. headless is mount-time only.

Headless mode sends the same BuyButtonEvent events, with these differences:

• It accepts saved-card and bank transfer (sepa) quotes for a connected customer only. An Apple Pay or Google Pay quote gets an "error" with code unsupportedPaymentMethod, and a guest checkout quote gets invalidQuote.
• It never sends "buttonPressed" or "cancelled".
• After "ready", it sends exactly one of "complete", "challenge", or "error".
• It reads a new quote only after an "error" with code quoteExpired. At any other time the frame ignores the update, so it never starts a second purchase.
• On "challenge", render <MoonPayChallenge> without resume. The challenge frame finishes the purchase and sends its own "complete".

For the frame-level behavior, see Headless mode on the Buy Button frame.

HeadlessBuy.tsx

import React from "react";
import { Button } from "react-native";
import {
  MoonPayBuyButton,
  MoonPayChallenge,
  type BuyButtonEvent,
  type ChallengeEvent,
} from "@moonpay/platform-sdk-react-native";

export function HeadlessBuy({ cardQuote }: { cardQuote: string }) {
  const [quote, setQuote] = React.useState(cardQuote);
  const [buying, setBuying] = React.useState(false);
  const [challengeUrl, setChallengeUrl] = React.useState<string | null>(null);

  const finish = () => {
    setBuying(false);
    setChallengeUrl(null);
  };

  const handleBuyEvent = async (event: BuyButtonEvent) => {
    switch (event.kind) {
      case "ready":
        showLoadingIndicator();
        break;
      case "complete":
        finish();
        if (event.payload.transaction.status !== "failed") {
          pollTransaction(event.payload.transaction.id);
        }
        break;
      case "challenge":
        // Render the challenge without `resume`. It finishes the purchase.
        setChallengeUrl(event.payload.url);
        break;
      case "error":
        if (event.payload.code === "quoteExpired") {
          // Keep the component mounted and retry with a fresh quote.
          setQuote(await refreshQuoteSignature());
          break;
        }
        finish();
        console.error(event.payload.code, event.payload.message);
        break;
    }
  };

  const handleChallengeEvent = (event: ChallengeEvent) => {
    switch (event.kind) {
      case "complete":
        // The challenge frame finished the purchase.
        finish();
        if (event.payload.flow === "buy") {
          pollTransaction(event.payload.transaction.id);
        }
        break;
      case "cancelled":
      case "error":
        finish();
        break;
    }
  };

  return (
    <>
      {/* Mounting the headless button starts the purchase. */}
      <Button title="Buy" onPress={() => setBuying(true)} disabled={buying} />
      {buying && (
        <MoonPayBuyButton headless quote={quote} onEvent={handleBuyEvent} />
      )}
      {challengeUrl && (
        <MoonPayChallenge url={challengeUrl} onEvent={handleChallengeEvent} />
      )}
    </>
  );
}

For the end-to-end card payment walkthrough, 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 with paymentMethod: { type: "sepa" }, mount <MoonPayBuyButton headless> 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 client.getTransaction() 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.

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.