React Native

Use react-native-webview to embed frames in React Native applications. The WebView communicates with your app through the ReactNativeWebView JavaScript interface.

Read the manual integration overview for core concepts before you continue.

Setup

The react-native-webview library automatically injects the ReactNativeWebView JavaScript interface into the WebView. The frame detects this interface and uses it for communication between the frame and your app. You don’t need to inject a custom JavaScript bridge.

Dependencies

Install react-native-webview 13.15.0 or later to render frames in your app. Earlier versions don’t support paymentRequestEnabled, which Google Pay needs in an Android WebView.

React Native CLI
Expo

pnpm i react-native-webview@^13.15.0

bun add react-native-webview@^13.15.0

npm i react-native-webview@^13.15.0

If targeting iOS, you may also need to run:

cd ios && pod install

npx expo install react-native-webview

See the Expo WebView docs for additional platform configuration.

The connect and check frames require X25519 key exchange to encrypt client credentials. The examples below use noble-curves, but you can use any library that supports X25519 and AES-GCM. You also need a polyfill for getRandomValues (MDN) which is only available in browsers.

pnpm i react-native-get-random-values @noble/curves @noble/hashes @noble/ciphers

bun add react-native-get-random-values @noble/curves @noble/hashes @noble/ciphers

npm i react-native-get-random-values @noble/curves @noble/hashes @noble/ciphers

Base WebView component

Create a reusable base component for frame communication:

MoonPayWebView.tsx

import React, {
  useRef,
  useCallback,
  useImperativeHandle,
  forwardRef,
} from "react";
import { View, ViewStyle, StyleSheet } from "react-native";
import { WebView, WebViewMessageEvent } from "react-native-webview";

const FRAME_ORIGIN = "https://platform.moonpay.com";

// iOS reports the sending frame's URL. Android reports its origin, or the
// page URL on older WebViews. Accept both forms, only for the frame origin.
function isFromFrameOrigin(sourceUrl: string): boolean {
  return sourceUrl === FRAME_ORIGIN || sourceUrl.startsWith(`${FRAME_ORIGIN}/`);
}

type MoonPayWebViewProps = {
  url: string;
  channelId: string;
  onMessage: (data: FrameMessage) => void;
  onHandshake: () => void;
  style?: ViewStyle;
};

export type MoonPayWebViewRef = {
  sendMessage: (kind: string, payload?: object) => void;
};

export type FrameMessage = {
  version: number;
  meta: { channelId: string };
  kind: string;
  payload?: unknown;
};

export const MoonPayWebView = forwardRef<
  MoonPayWebViewRef,
  MoonPayWebViewProps
>(({ url, channelId, onMessage, onHandshake, style }, ref) => {
  const webViewRef = useRef<WebView>(null);

  const sendMessage = useCallback(
    (kind: string, payload?: object) => {
      const message = {
        version: 2,
        meta: { channelId },
        kind,
        ...(payload && { payload }),
      };

      webViewRef.current?.postMessage(JSON.stringify(message));
    },
    [channelId],
  );

  useImperativeHandle(ref, () => ({ sendMessage }), [sendMessage]);

  const handleMessage = useCallback(
    (event: WebViewMessageEvent) => {
      // Other frames on the page, such as a 3-D Secure page, can reach the
      // bridge too, so ignore messages that don't come from MoonPay
      if (!isFromFrameOrigin(event.nativeEvent.url)) return;

      try {
        const data: FrameMessage = JSON.parse(event.nativeEvent.data);
        if (data.meta?.channelId !== channelId) return;

        if (data.kind === "handshake") {
          sendMessage("ack");
          onHandshake();
        }

        onMessage(data);
      } catch {
        // Ignore malformed messages
      }
    },
    [channelId, sendMessage, onMessage, onHandshake],
  );

  return (
    <View style={[styles.container, style]}>
      <WebView
        ref={webViewRef}
        source={{ uri: url }}
        onMessage={handleMessage}
        javaScriptEnabled
        domStorageEnabled
        allowsInlineMediaPlayback
        // Android: enables the Payment Request API for Google Pay in the
        // buy button and challenge frames
        paymentRequestEnabled
        originWhitelist={["*"]}
        style={styles.webview}
      />
    </View>
  );
});

const styles = StyleSheet.create({
  container: { flex: 1 },
  webview: { flex: 1 },
});

Encryption utility

When using the connect or check frame, you generate an X25519 keypair and provide the public key to the frame. The frame encrypts the returned client credentials with this key.

Key generation

Generate an X25519 keypair for secure communication:

crypto.ts

import { x25519 } from "@noble/curves/ed25519";
import { bytesToHex } from "@noble/hashes/utils";
import "react-native-get-random-values"; // Polyfill for crypto.getRandomValues

export function generateKeyPair() {
  const { secretKey, publicKey } = x25519.keygen();

  return {
    privateKeyHex: bytesToHex(secretKey),
    publicKeyHex: bytesToHex(publicKey),
  };
}

export function generateChannelId() {
  return `ch_${Date.now()}_${Math.random().toString(36).slice(2)}`;
}

Decryption utility

Decrypt the encrypted credentials returned from connect/check frames:

decrypt.ts

import { x25519 } from "@noble/curves/ed25519";
import { hkdf } from "@noble/hashes/hkdf";
import { sha256 } from "@noble/hashes/sha256";
import { gcm } from "@noble/ciphers/aes";
import { hexToBytes } from "@noble/hashes/utils";

interface ClientCredentials {
  accessToken: string;
  clientToken: string;
}

export function decryptClientCredentials(
  encryptedValue: string,
  privateKeyHex: string,
): ClientCredentials {
  const encrypted = JSON.parse(encryptedValue) as {
    ephemeralPublicKey: string;
    iv: string;
    ciphertext: string;
  };

  const sharedSecret = x25519.getSharedSecret(
    hexToBytes(privateKeyHex),
    hexToBytes(encrypted.ephemeralPublicKey),
  );

  const derivedKey = hkdf(sha256, sharedSecret, undefined, undefined, 32);

  const aes = gcm(derivedKey, hexToBytes(encrypted.iv));
  const decrypted = aes.decrypt(hexToBytes(encrypted.ciphertext));
  const text = new TextDecoder().decode(decrypted);

  return JSON.parse(text) as ClientCredentials;
}

Check frame

The check frame verifies whether a customer already has an active connection. It’s headless — no UI is rendered. See check frame reference for event details.

Check component

import React, { useState, useCallback } from "react";
import { MoonPayWebView, FrameMessage } from "./MoonPayWebView";
import {
  generateKeyPair,
  generateChannelId,
  decryptClientCredentials,
} from "./crypto";

const FRAME_ORIGIN = "https://platform.moonpay.com";

interface CheckFrameProps {
  sessionToken: string;
  onActive: (credentials: { accessToken: string; clientToken: string }) => void;
  onConnectionRequired: (credentials: {
    accessToken: string;
    clientToken: string;
  }) => void;
  onError: (error: { code: string; message: string }) => void;
  onPending?: () => void;
  onUnavailable?: () => void;
}

export function MoonPayCheckFrame({
  sessionToken,
  onActive,
  onConnectionRequired,
  onError,
  onPending,
  onUnavailable,
}: CheckFrameProps) {
  const [channelId] = useState(generateChannelId);
  const [keyPair] = useState(generateKeyPair);

  const frameUrl = `${FRAME_ORIGIN}/platform/v1/check-connection?${new URLSearchParams(
    {
      sessionToken,
      publicKey: keyPair.publicKeyHex,
      channelId,
    },
  ).toString()}`;

  const handleMessage = useCallback(
    (data: FrameMessage) => {
      switch (data.kind) {
        case "complete":
          const payload = data.payload as {
            status: string;
            credentials?: string;
            expiresAt?: string;
            customer?: {
              id: string;
              country: string;
              administrativeArea?: string;
              area?: string;
            };
            /** Present only when the session's email and phone number resolve to different MoonPay customers. */
            mismatch?: boolean;
            reason?: string;
          };

          switch (payload.status) {
            case "active":
              const credentials = decryptClientCredentials(
                payload.credentials!,
                keyPair.privateKeyHex,
              );
              // Read payload.customer.country, payload.customer.administrativeArea,
              // and payload.customer.area to determine geo-based disclosure requirements.
              // payload.capabilities.ramps.requirements.paymentDisclosures is deprecated.
              onActive(credentials);
              break;
            case "connectionRequired":
              const anonymousCredentials = decryptClientCredentials(
                payload.credentials!,
                keyPair.privateKeyHex,
              );
              // payload.mismatch is true when the session's email and phone resolve to different customers — route through the connect flow first.
              onConnectionRequired(anonymousCredentials);
              break;
            case "pending":
              onPending?.();
              break;
            case "unavailable":
              onUnavailable?.();
              break;
            case "failed":
              onError({
                code: "failed",
                message: payload.reason || "Check failed",
              });
              break;
          }
          break;

        case "error":
          onError(data.payload as { code: string; message: string });
          break;
      }
    },
    [
      keyPair,
      onActive,
      onConnectionRequired,
      onError,
      onPending,
      onUnavailable,
    ],
  );

  return (
    <MoonPayWebView
      url={frameUrl}
      channelId={channelId}
      onMessage={handleMessage}
      onHandshake={() => {}}
    />
  );
}

Usage

import { MoonPayCheckFrame } from "./MoonPayCheckFrame";

function SplashScreen({ navigation }) {
  return (
    <MoonPayCheckFrame
      sessionToken="your-session-token"
      onActive={({ accessToken, clientToken }) => {
        // Customer is already connected — skip to payment
        console.log("Already connected!", { accessToken, clientToken });
        navigation.navigate("Payment");
      }}
      onConnectionRequired={({ accessToken, clientToken }) => {
        // Store both tokens in memory, then pass clientToken to the connect frame
        CredentialsStore.set({ accessToken, clientToken });
        navigation.navigate("Connect", { clientToken });
      }}
      onError={(error) => {
        console.error("Check failed:", error);
      }}
    />
  );
}

Connect frame

The connect frame establishes a customer connection to your application. See connect frame reference for event details.

Connect component

import React, { useState, useCallback } from "react";
import { MoonPayWebView, FrameMessage } from "./MoonPayWebView";
import {
  generateKeyPair,
  generateChannelId,
  decryptClientCredentials,
} from "./crypto";

const FRAME_ORIGIN = "https://platform.moonpay.com";

interface ConnectFrameProps {
  clientToken: string;
  onComplete: (credentials: {
    accessToken: string;
    clientToken: string;
  }) => void;
  onError: (error: { code: string; message: string }) => void;
  onPending?: () => void;
  onUnavailable?: () => void;
}

export function MoonPayConnectFrame({
  clientToken,
  onComplete,
  onError,
  onPending,
  onUnavailable,
}: ConnectFrameProps) {
  const [channelId] = useState(generateChannelId);
  const [keyPair] = useState(generateKeyPair);

  const frameUrl = `${FRAME_ORIGIN}/platform/v1/connect?${new URLSearchParams({
    clientToken,
    publicKey: keyPair.publicKeyHex,
    channelId,
  }).toString()}`;

  const handleMessage = useCallback(
    (data: FrameMessage) => {
      switch (data.kind) {
        case "complete":
          const payload = data.payload as {
            status: string;
            credentials?: string;
            expiresAt?: string;
            customer?: {
              id: string;
              country: string;
              administrativeArea?: string;
              area?: string;
            };
            reason?: string;
          };

          switch (payload.status) {
            case "active":
              const credentials = decryptClientCredentials(
                payload.credentials!,
                keyPair.privateKeyHex,
              );
              // Read payload.customer.country, payload.customer.administrativeArea,
              // and payload.customer.area to determine geo-based disclosure requirements.
              // payload.capabilities.ramps.requirements.paymentDisclosures is deprecated.
              onComplete(credentials);
              break;
            case "pending":
              onPending?.();
              break;
            case "unavailable":
              onUnavailable?.();
              break;
            case "failed":
              onError({
                code: "failed",
                message: payload.reason || "Connection failed",
              });
              break;
          }
          break;

        case "error":
          onError(data.payload as { code: string; message: string });
          break;
      }
    },
    [keyPair, onComplete, onError, onPending, onUnavailable],
  );

  return (
    <MoonPayWebView
      url={frameUrl}
      channelId={channelId}
      onMessage={handleMessage}
      onHandshake={() => {}}
    />
  );
}

Usage

import { MoonPayConnectFrame } from "./MoonPayConnectFrame";

function ConnectScreen({ route, navigation }) {
  // The clientToken is the anonymous token passed from the check frame's
  // `connectionRequired` response.
  const { clientToken } = route.params;

  const handleComplete = ({ accessToken, clientToken }) => {
    // Replace the anonymous credentials with the authenticated ones and store
    // them in memory (e.g., React Context or state management).
    console.log("Connected!", { accessToken, clientToken });
    navigation.navigate("Home");
  };

  const handleError = (error) => {
    console.error("Connection failed:", error);
    // Show error UI
  };

  return (
    <MoonPayConnectFrame
      clientToken={clientToken}
      onComplete={handleComplete}
      onError={handleError}
      onPending={() => console.log("Connection pending")}
      onUnavailable={() => console.log("Connection unavailable")}
    />
  );
}

Auth frame

The auth frame authenticates a customer with email or SMS one-time passcode and returns fully scoped credentials — without the hosted KYC UI in the connect frame. Launch it after the check frame returns connectionRequired, typically when you drive onboarding through the Customer API. See auth frame reference for event details.

Auth component

import React, { useState, useCallback } from "react";
import { MoonPayWebView, FrameMessage } from "./MoonPayWebView";
import {
  generateKeyPair,
  generateChannelId,
  decryptClientCredentials,
} from "./crypto";

const FRAME_ORIGIN = "https://platform.moonpay.com";

interface AuthFrameProps {
  clientToken: string;
  onReady?: () => void;
  onComplete: (result: {
    status: string;
    credentials?: { accessToken: string; clientToken: string };
    customerId?: string;
  }) => void;
  onError: (error: { code: string; message: string }) => void;
  onClose?: () => void;
}

export function MoonPayAuthFrame({
  clientToken,
  onReady,
  onComplete,
  onError,
  onClose,
}: AuthFrameProps) {
  const [channelId] = useState(generateChannelId);
  const [keyPair] = useState(generateKeyPair);

  const frameUrl = `${FRAME_ORIGIN}/v2/auth?${new URLSearchParams({
    clientToken,
    publicKey: keyPair.publicKeyHex,
    channelId,
  }).toString()}`;

  const handleMessage = useCallback(
    (data: FrameMessage) => {
      switch (data.kind) {
        case "ready":
          onReady?.();
          break;

        case "complete":
          const payload = data.payload as {
            status: string;
            credentials?: string;
            customer?: { id: string };
          };

          if (payload.status === "active" && payload.credentials) {
            const credentials = decryptClientCredentials(
              payload.credentials,
              keyPair.privateKeyHex,
            );
            onComplete({
              status: payload.status,
              credentials,
              customerId: payload.customer?.id,
            });
          } else {
            onComplete({ status: payload.status });
          }
          break;

        case "error":
          onError(data.payload as { code: string; message: string });
          break;

        case "close":
          onClose?.();
          break;
      }
    },
    [keyPair, onReady, onComplete, onError, onClose],
  );

  return (
    <MoonPayWebView
      url={frameUrl}
      channelId={channelId}
      onMessage={handleMessage}
      onHandshake={() => {}}
    />
  );
}

Usage

import { MoonPayAuthFrame } from "./MoonPayAuthFrame";

function AuthScreen({ route, navigation }) {
  const { clientToken } = route.params;

  return (
    <MoonPayAuthFrame
      clientToken={clientToken}
      onComplete={({ status, credentials, customerId }) => {
        if (status === "active" && credentials) {
          console.log("Authenticated", customerId);
          navigation.navigate("Home");
        } else if (status === "termsAcceptanceRequired") {
          navigation.navigate("Terms");
        }
      }}
      onError={(error) => console.error("Auth failed:", error.message)}
      onClose={() => navigation.goBack()}
    />
  );
}

Add Card frame

The add card frame lets a customer save a new card to their account. See add card frame reference for event details.

What you’ll need

Before you initialize the add card frame, you need:

A clientToken from a successful connect flow

Add Card component

import React, { useState, useCallback } from "react";
import { MoonPayWebView, FrameMessage } from "./MoonPayWebView";
import { generateChannelId } from "./crypto";

const FRAME_ORIGIN = "https://platform.moonpay.com";

interface CardResult {
  id: string;
  brand: string;
  last4: string;
  cardType: string;
  expirationMonth: number;
  expirationYear: number;
  availability: { active: boolean };
}

interface AddCardFrameProps {
  clientToken: string;
  onComplete: (card: CardResult) => void;
  onError: (error: { code: string; message: string }) => void;
  onReady?: () => void;
}

export function MoonPayAddCardFrame({
  clientToken,
  onComplete,
  onError,
  onReady,
}: AddCardFrameProps) {
  const [channelId] = useState(generateChannelId);

  const frameUrl = `${FRAME_ORIGIN}/platform/v1/add-card?${new URLSearchParams({
    clientToken,
    channelId,
  }).toString()}`;

  const handleMessage = useCallback(
    (data: FrameMessage) => {
      switch (data.kind) {
        case "ready":
          onReady?.();
          break;

        case "complete":
          const payload = data.payload as { card: CardResult };
          onComplete(payload.card);
          break;

        case "error":
          onError(data.payload as { code: string; message: string });
          break;
      }
    },
    [onComplete, onError, onReady],
  );

  return (
    <MoonPayWebView
      url={frameUrl}
      channelId={channelId}
      onMessage={handleMessage}
      onHandshake={() => {}}
      style={{ flex: 1 }}
    />
  );
}

Usage

import { MoonPayAddCardFrame } from "./MoonPayAddCardFrame";

function SaveCardScreen({ clientToken, navigation }) {
  return (
    <MoonPayAddCardFrame
      clientToken={clientToken}
      onComplete={(card) => {
        console.log("Card saved:", card.id, card.brand, card.last4);
        navigation.navigate("Payment");
      }}
      onError={(error) => {
        console.error("Add card error:", error);
      }}
      onReady={() => console.log("Add card frame ready")}
    />
  );
}

Buy Button frame

The Buy Button frame takes a quote to payment. It renders the Apple Pay, Google Pay, or card button that matches the payment method in your quote, and supports guest checkout when your quote allows it. For card and bank transfer quotes, you can also run it in headless mode behind your own purchase button. See the Buy Button frame reference for event details, and Pay with the buy button for the full walkthrough.

Apple Pay and Google Pay inside a WebView have extra requirements, and Google Pay isn’t available in an iOS WebView. See Mobile WebViews.

What you’ll need

Before you initialize the Buy Button frame, you need:

A clientToken from a successful connect flow
A valid quote signature for the transaction

Buy Button component

The component renders the button at 44px tall. See Size. Pass headless to run the purchase without a button, as described in Headless mode.

import React, {
  useState,
  useCallback,
  useRef,
  useImperativeHandle,
  forwardRef,
} from "react";
import { StyleSheet } from "react-native";
import {
  MoonPayWebView,
  MoonPayWebViewRef,
  FrameMessage,
} from "./MoonPayWebView";
import { generateChannelId } from "./crypto";

const FRAME_ORIGIN = "https://platform.moonpay.com";

export type BuyButtonTransaction = {
  // Missing when a failed transaction was never created
  id?: string;
  status: "pending" | "completed" | "failed";
  failureCode?: string;
  failureReason?: string;
};

interface BuyButtonFrameProps {
  clientToken: string;
  quoteSignature: string;
  externalTransactionId?: string;
  headless?: boolean;
  onReady?: () => void;
  onComplete: (transaction: BuyButtonTransaction) => void;
  onChallenge: (url: string) => void;
  onCancelled?: () => void;
  onError: (error: { code: string; message: string }) => void;
  onQuoteExpired?: () => void;
}

export type BuyButtonFrameRef = {
  updateQuote: (signature: string) => void;
};

export const MoonPayBuyButtonFrame = forwardRef<
  BuyButtonFrameRef,
  BuyButtonFrameProps
>(
  (
    {
      clientToken,
      quoteSignature,
      externalTransactionId,
      headless,
      onReady,
      onComplete,
      onChallenge,
      onCancelled,
      onError,
      onQuoteExpired,
    },
    ref,
  ) => {
    const frameRef = useRef<MoonPayWebViewRef>(null);
    const [channelId] = useState(generateChannelId);

    // Build the URL once. A new URL reloads the frame, which in headless
    // mode starts a new purchase. Send quote changes with updateQuote.
    const [frameUrl] = useState(
      () =>
        `${FRAME_ORIGIN}/platform/v1/buy-button?${new URLSearchParams({
          clientToken,
          channelId,
          signature: quoteSignature,
          ...(headless && { headless: "true" }),
          ...(externalTransactionId && { externalTransactionId }),
        }).toString()}`,
    );

    useImperativeHandle(
      ref,
      () => ({
        updateQuote: (signature: string) => {
          frameRef.current?.sendMessage("setQuote", {
            quote: { signature },
          });
        },
      }),
      [],
    );

    const handleMessage = useCallback(
      (data: FrameMessage) => {
        switch (data.kind) {
          case "ready":
            onReady?.();
            break;

          case "complete":
            // Check status: a failed payment also arrives as `complete`
            onComplete(
              (data.payload as { transaction: BuyButtonTransaction })
                .transaction,
            );
            break;

          case "challenge":
            onChallenge((data.payload as { url: string }).url);
            break;

          case "cancelled":
            // The customer dismissed the Apple Pay or Google Pay sheet.
            // The button stays on screen, so the customer can tap it again.
            onCancelled?.();
            break;

          case "error":
            const error = data.payload as { code: string; message: string };
            if (error.code === "quoteExpired") {
              onQuoteExpired?.();
            } else {
              onError(error);
            }
            break;
        }
      },
      [onReady, onComplete, onChallenge, onCancelled, onError, onQuoteExpired],
    );

    return (
      <MoonPayWebView
        ref={frameRef}
        url={frameUrl}
        channelId={channelId}
        onMessage={handleMessage}
        onHandshake={() => {}}
        style={headless ? styles.headless : styles.button}
      />
    );
  },
);

const styles = StyleSheet.create({
  button: { flex: 0, height: 44 },
  // Headless mode renders nothing, so keep the frame out of your layout
  headless: { position: "absolute", width: 0, height: 0 },
});

Challenge component

When the Buy Button frame emits a challenge event, for example for 3-D Secure, render the challenge frame at the URL. Opened without resume, as below, it finishes the purchase for every payment method and sends complete. To have the customer finish an Apple Pay or Google Pay purchase on your buy button instead, see Finish on your buy button.

import React, { useState, useCallback, useMemo } from "react";
import { MoonPayWebView, FrameMessage } from "./MoonPayWebView";
import { BuyButtonTransaction } from "./MoonPayBuyButtonFrame";
import { generateChannelId } from "./crypto";

const FRAME_ORIGIN = "https://platform.moonpay.com";

interface ChallengeFrameProps {
  challengeUrl: string;
  clientToken: string;
  onComplete: (transaction: BuyButtonTransaction) => void;
  onCancelled: () => void;
  onError: (error: { code: string; message: string }) => void;
}

export function MoonPayChallengeFrame({
  challengeUrl,
  clientToken,
  onComplete,
  onCancelled,
  onError,
}: ChallengeFrameProps) {
  const [channelId] = useState(generateChannelId);

  // Append the params to the string. React Native doesn't implement
  // URLSearchParams.set, so url.searchParams.set() throws.
  const frameUrl = useMemo(() => {
    const separator = challengeUrl.includes("?") ? "&" : "?";
    const params = new URLSearchParams({ clientToken, channelId });
    return `${challengeUrl}${separator}${params.toString()}`;
  }, [challengeUrl, clientToken, channelId]);

  const handleMessage = useCallback(
    (data: FrameMessage) => {
      switch (data.kind) {
        case "complete":
          // Check status: a failed payment also arrives as `complete`
          const payload = data.payload as {
            flow: "buy";
            transaction: BuyButtonTransaction;
          };
          onComplete(payload.transaction);
          break;

        case "cancelled":
          onCancelled();
          break;

        case "error":
          onError(data.payload as { code: string; message: string });
          break;
      }
    },
    [onComplete, onCancelled, onError],
  );

  return (
    <MoonPayWebView
      url={frameUrl}
      channelId={channelId}
      onMessage={handleMessage}
      onHandshake={() => {}}
    />
  );
}

Usage

import { useRef, useState } from "react";
import {
  MoonPayBuyButtonFrame,
  BuyButtonFrameRef,
  BuyButtonTransaction,
} from "./MoonPayBuyButtonFrame";
import { MoonPayChallengeFrame } from "./MoonPayChallengeFrame";

function BuyButtonScreen({ clientToken, quoteSignature }) {
  const buyButtonRef = useRef<BuyButtonFrameRef>(null);
  const [challengeUrl, setChallengeUrl] = useState<string | null>(null);
  const [done, setDone] = useState(false);

  const handleQuoteExpired = async () => {
    // Fetch a new quote and send it to the frame
    const newQuote = await fetchNewQuote();
    buyButtonRef.current?.updateQuote(newQuote.signature);
  };

  // The purchase finished: unmount both frames and show the result
  const handleResult = (transaction: BuyButtonTransaction | null) => {
    setChallengeUrl(null);
    setDone(true);
    if (!transaction) {
      console.log("Challenge cancelled or errored");
    } else if (transaction.status === "failed") {
      // Branch on failureCode; failureReason is developer-facing only
      console.error("Transaction failed:", transaction.failureCode);
    } else {
      console.log("Complete:", transaction.status, transaction.id);
    }
  };

  if (done) {
    // Render your result screen or a retry path here
    return null;
  }

  if (challengeUrl) {
    return (
      <MoonPayChallengeFrame
        challengeUrl={challengeUrl}
        clientToken={clientToken}
        onComplete={handleResult}
        onCancelled={() => handleResult(null)}
        onError={() => handleResult(null)}
      />
    );
  }

  return (
    <MoonPayBuyButtonFrame
      ref={buyButtonRef}
      clientToken={clientToken}
      quoteSignature={quoteSignature}
      onComplete={handleResult}
      onChallenge={(url) => setChallengeUrl(url)}
      onError={(error) => console.error(error.message)}
      onQuoteExpired={handleQuoteExpired}
    />
  );
}

Headless mode

For card and bank transfer quotes, you can draw your own purchase button and pass headless to MoonPayBuyButtonFrame. The frame loads with headless=true, renders nothing, and starts the purchase as soon as it loads. Mount it at zero size when the customer confirms the purchase in your UI, not before. See Headless mode. In headless mode, the frame:

Sends ready, then exactly one of complete, challenge, or error.
Never sends buttonPressed or cancelled.
Accepts card and bank transfer (SEPA) quotes only. An Apple Pay or Google Pay quote returns error with unsupportedPaymentMethod.
Needs a connected customer. A guest checkout quote returns error with invalidQuote.
Reads setQuote only after an error with quoteExpired.

On challenge, render the challenge component without resume. It finishes the purchase and sends its own complete. After complete, or an error other than quoteExpired, unmount the frame. The example below leaves the screen, which unmounts it. Mount a new frame if the customer tries again. For a bank transfer (SEPA) quote, onComplete receives the transaction id. Fetch the transaction by id, and show the customer the bank details from bankTransferDepositInfo and the amount to send from source.amount natively so they can send the transfer. See Pay with bank transfer.

For bank transfers, the customer must include the payment reference from bankTransferDepositInfo with their transfer, or it is rejected. Render the deposit details, including the reference, in your own UI. See the transaction object.

import { useRef, useState } from "react";
import { View, StyleSheet } from "react-native";
import {
  MoonPayBuyButtonFrame,
  BuyButtonFrameRef,
  BuyButtonTransaction,
} from "./MoonPayBuyButtonFrame";
import { MoonPayChallengeFrame } from "./MoonPayChallengeFrame";

// Render this screen only after the customer confirms the purchase:
// mounting the headless frame starts the purchase. Leaving the screen
// unmounts the frames.
function HeadlessBuyScreen({ clientToken, quoteSignature, navigation }) {
  const buyButtonRef = useRef<BuyButtonFrameRef>(null);
  const [challengeUrl, setChallengeUrl] = useState<string | null>(null);

  const handleComplete = (transaction: BuyButtonTransaction) => {
    if (transaction.status === "failed") {
      // Branch on failureCode; failureReason is developer-facing only
      console.error("Transaction failed:", transaction.failureCode);
      navigation.goBack();
      return;
    }
    console.log("Transaction initiated:", transaction.id);
    navigation.replace("TransactionStatus", { transactionId: transaction.id });
  };

  const handleQuoteExpired = async () => {
    const newQuote = await fetchNewQuote();
    buyButtonRef.current?.updateQuote(newQuote.signature);
  };

  return (
    <View style={StyleSheet.absoluteFill}>
      {/* Show your own loading state here */}
      <MoonPayBuyButtonFrame
        ref={buyButtonRef}
        headless
        clientToken={clientToken}
        quoteSignature={quoteSignature}
        onComplete={handleComplete}
        onChallenge={(url) => setChallengeUrl(url)}
        onError={(error) => {
          console.error("Buy Button error:", error);
          navigation.goBack();
        }}
        onQuoteExpired={handleQuoteExpired}
      />
      {challengeUrl && (
        <View style={StyleSheet.absoluteFill}>
          <MoonPayChallengeFrame
            challengeUrl={challengeUrl}
            clientToken={clientToken}
            onComplete={handleComplete}
            onCancelled={() => navigation.goBack()}
            onError={(error) => {
              console.error("Challenge error:", error);
              navigation.goBack();
            }}
          />
        </View>
      )}
    </View>
  );
}

To hand the whole purchase to MoonPay, including amount entry and payment method selection, use the widget frame. It renders the full MoonPay buy experience inside a WebView, including payment collection and transaction confirmation. See pay with widget for a full walkthrough.

import React, { useState, useCallback } from "react";
import { MoonPayWebView, FrameMessage } from "./MoonPayWebView";
import { generateChannelId } from "./crypto";

const FRAME_ORIGIN = "https://platform.moonpay.com";

interface WidgetFrameProps {
  clientToken: string;
  quoteSignature: string;
  externalTransactionId?: string;
  onTransactionCreated?: (transaction: { id: string; status: string }) => void;
  onComplete: (transaction: { id: string; status: string }) => void;
  onError: (error: { code: string; message: string }) => void;
  onReady?: () => void;
}

export function MoonPayWidgetFrame({
  clientToken,
  quoteSignature,
  externalTransactionId,
  onTransactionCreated,
  onComplete,
  onError,
  onReady,
}: WidgetFrameProps) {
  const [channelId] = useState(generateChannelId);

  const frameUrl = `${FRAME_ORIGIN}/platform/v1/widget?${new URLSearchParams({
    flow: "buy",
    clientToken,
    quoteSignature,
    channelId,
    ...(externalTransactionId && { externalTransactionId }),
  }).toString()}`;

  const handleMessage = useCallback(
    (data: FrameMessage) => {
      switch (data.kind) {
        case "ready":
          onReady?.();
          break;

        case "transactionCreated":
          const created = data.payload as {
            transaction: { id: string; status: string };
          };
          onTransactionCreated?.(created.transaction);
          break;

        case "complete":
          const payload = data.payload as {
            transaction:
              | { id: string; status: string }
              | { status: "failed"; failureReason: string };
          };

          if (payload.transaction.status === "failed") {
            onError({
              code: "transactionFailed",
              message: (payload.transaction as { failureReason: string })
                .failureReason,
            });
          } else {
            onComplete(payload.transaction as { id: string; status: string });
          }
          break;

        case "error":
          onError(data.payload as { code: string; message: string });
          break;
      }
    },
    [onComplete, onError, onTransactionCreated, onReady],
  );

  return (
    <MoonPayWebView
      url={frameUrl}
      channelId={channelId}
      onMessage={handleMessage}
      onHandshake={() => {}}
    />
  );
}

Usage

import { MoonPayWidgetFrame } from "./MoonPayWidgetFrame";

function WidgetPaymentScreen({ clientToken, quoteSignature }) {
  return (
    <MoonPayWidgetFrame
      clientToken={clientToken}
      quoteSignature={quoteSignature}
      onReady={() => console.log("Widget loaded")}
      onTransactionCreated={(tx) =>
        console.log("Transaction created:", tx.id, tx.status)
      }
      onComplete={(tx) => console.log("Transaction complete:", tx.id)}
      onError={(error) => console.error("Widget error:", error)}
    />
  );
}

Reset frame

The reset frame is headless. Use it when the customer signs out to clear MoonPay session state on MoonPay’s domain. See reset frame reference. Pass your clientToken so your app is authorized to embed the frame. Do not block sign-out if reset fails.

Reset component

import React, { useState, useCallback, useEffect } from "react";
import { MoonPayWebView, FrameMessage } from "./MoonPayWebView";
import { generateChannelId } from "./crypto";

const FRAME_ORIGIN = "https://platform.moonpay.com";

interface ResetFrameProps {
  clientToken: string;
  onComplete: () => void;
  onError?: (error: { code: string; message: string }) => void;
}

export function MoonPayResetFrame({
  clientToken,
  onComplete,
  onError,
}: ResetFrameProps) {
  const [channelId] = useState(generateChannelId);

  const frameUrl = `${FRAME_ORIGIN}/platform/v1/reset?${new URLSearchParams({
    channelId,
    clientToken,
  }).toString()}`;

  const handleMessage = useCallback(
    (data: FrameMessage) => {
      switch (data.kind) {
        case "complete":
          onComplete();
          break;
        case "error":
          onError?.(data.payload as { code: string; message: string });
          break;
      }
    },
    [onComplete, onError],
  );

  return (
    <MoonPayWebView
      url={frameUrl}
      channelId={channelId}
      onMessage={handleMessage}
      onHandshake={() => {}}
      style={{ width: 0, height: 0, opacity: 0 }}
    />
  );
}

Usage

function signOut(clientToken: string) {
  clearLocalCredentials();

  return new Promise<void>((resolve) => {
    const timeout = setTimeout(resolve, 5000);

    // Mount MoonPayResetFrame briefly, or render it in a hidden portal:
    // onComplete / onError both call resolve() and clearTimeout(timeout).
  });
}

Overview

Customers

Payments

Integration essentials

SDK Reference

Frames

Setup

Dependencies

Base WebView component

Encryption utility

Key generation

Decryption utility

Check frame

Check component

Usage

Connect frame

Connect component

Usage

Auth frame

Auth component

Usage

Add Card frame

What you’ll need

Add Card component

Usage

Buy Button frame

What you’ll need

Buy Button component

Challenge component

Usage

Headless mode

Widget frame

Widget component

Usage

Reset frame

Reset component

Usage