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 Apple Pay frame in your app and initiate a transaction with a quote signature. The quote must have executable: true. The provider mounts the frame as a react-native-webview.
Apple Pay availability inside a WebView depends on iOS WebKit support. The frame emits "unsupported" when Apple Pay isn’t available in the current environment — surface a fallback payment method.
Setup Apple Pay
import {
  useMoonPay,
  type ApplePayEvent,
} from "@moonpay/platform-sdk-react-native";

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

  const start = async () => {
    const applePayResult = await client.setupApplePay({
      quote: quoteSignature,
      onEvent: (event: ApplePayEvent) => {
        switch (event.kind) {
          case "ready":
            break;
          case "complete":
            console.log(event.payload.transaction);
            break;
          case "quoteExpired":
            // Fetch a new quote, then update the frame:
            // event.payload.setQuote(newQuote.signature);
            break;
          case "error":
            console.error(event.payload.kind, event.payload.message);
            break;
          case "unsupported":
            // Apple Pay isn't available in this environment — fall back to another method.
            break;
        }
      },
    });

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

    const applePay = applePayResult.value;
  };

  // ...
}

​
Parameters

PropertyTypeRequiredDescription
quotestring✅The quote signature returned from getQuote.
onEvent(event: ApplePayEvent) => voidCallback invoked for Apple Pay flow events. See ApplePayEvent.
This method does not require a separate auth token. The client uses stored credentials from an active connection.

​
ApplePayEvent

onEvent receives events as the Apple Pay flow progresses. Use event.kind to decide how to handle each event.
kindPayloadWhen you receive it
"ready"—The Apple Pay UI is rendered and ready to be shown.
"complete"{ transaction: FrameTransaction }The Apple Pay flow finished. Inspect the FrameTransaction for the outcome.
"quoteExpired"{ setQuote: (signature: string) => void }The quote signature expired. Fetch a new quote and call payload.setQuote(...).
"error"ApplePayEventErrorThe flow encountered an error.
"unsupported"—Apple Pay isn’t available in the user’s current environment.

​
FrameTransaction

The transaction object returned on "complete". FrameTransaction is a discriminated union — the failure variant carries failureReason, the non-failure variant always carries id.
FieldTypeRequiredDescription
statusstring✅The transaction status. On the failure variant, "failed".
idstringRequired on the non-failure variant; optional when status is "failed" (a transaction may not exist yet on early failure).
failureReasonstringPresent only on the failure variant (status === "failed").

​
ApplePayEventError

FieldTypeRequiredDescription
kind"configurationError" | "invalidQuote" | "quoteExpired" | "oneTapApplePaySecondFactorRequired" | "genericError"✅The error category.
messagestring✅Developer-friendly details.
"oneTapApplePaySecondFactorRequired" is emitted on the 1TAP Apple Pay flow when MoonPay needs a second authentication factor — typically because the device is new or the customer hasn’t completed a recent challenge. Hand off to the full connect flow with client.connect(), then retry. Apple Pay being unavailable in the environment is signalled separately through the "unsupported" event, not as an error.

​
Result

client.setupApplePay() returns a Result<ApplePayFrame, SetupApplePayError>.

​
Result envelope

Result<ApplePayFrame, SetupApplePayError>
FieldTypeRequiredDescription
okboolean✅Whether the operation succeeded.
valueApplePayFramePresent when ok is true.
errorSetupApplePayErrorPresent when ok is false.

​
ApplePayFrame

FieldTypeRequiredDescription
setQuote(signature: string) => void✅Updates the quote signature used by the frame. Use this in response to quoteExpired.
dispose() => void✅Unmounts the frame. After you call this, no further events are dispatched to your onEvent callback.

​
SetupApplePayError

FieldTypeRequiredDescription
kind"invalidQuote" | "quoteExpired" | "applePayUnavailable" | "oneTapApplePaySecondFactorRequired" | "genericError"✅The error category.
messagestring✅Developer-friendly details.
types.ts
type ApplePayFrame = {
  setQuote: (signature: string) => void;
  dispose: () => void;
};

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

type ApplePayEvent =
  | { kind: "ready" }
  | {
      kind: "complete";
      payload: { transaction: FrameTransaction };
    }
  | {
      kind: "quoteExpired";
      payload: { setQuote: (signature: string) => void };
    }
  | { kind: "error"; payload: ApplePayEventError }
  | { kind: "unsupported" };

type ApplePayEventError = {
  kind:
    | "configurationError"
    | "invalidQuote"
    | "quoteExpired"
    | "oneTapApplePaySecondFactorRequired"
    | "genericError";
  message: string;
};

type SetupApplePayError = {
  kind:
    | "invalidQuote"
    | "quoteExpired"
    | "applePayUnavailable"
    | "oneTapApplePaySecondFactorRequired"
    | "genericError";
  message: string;
};