client.setupApplePay()

Render the Apple Pay frame and start a transaction.

Render the Apple Pay frame into your UI and initiate a transaction with a quote signature. The quote must have executable: true.

Setup Apple Pay

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

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

const applePayResult = await client.setupApplePay({
  quote: quoteResult.value.data.signature,
  container: document.querySelector("#applePayContainer"),
  onEvent: (event: ApplePayEvent) => {
    switch (event.kind) {
      case "ready":
        break;
      case "buttonPressed":
        // Customer tapped the button — show a loading state or fire analytics.
        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

Property	Type	Required	Description
quote	string	✅	The quote signature returned from getQuote.
container	HTMLElement	✅	A DOM element to render the Apple Pay frame into.
externalTransactionId	string		Partner-assigned identifier for this transaction attempt. Useful for reconciliation.
onEvent	(event: ApplePayEvent) => void		Callback 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.

kind	Payload	When you receive it
"ready"	—	The Apple Pay UI is rendered and ready to be shown.
"buttonPressed"	—	The customer tapped the Apple Pay button, before iOS presents the payment sheet. An intent-to-buy signal with no payload — it still fires if the customer then cancels the sheet. Not a purchase outcome; listen for "complete" for the result.
"complete"	{ transaction: FrameTransaction }	The Apple Pay flow finished. Inspect the FrameTransaction for the outcome.
"challenge"	{ kind: "frame"; url: string }	Verification required. Render the challenge frame at the provided URL using setupChallenge().
"quoteExpired"	{ setQuote: (signature: string) => void }	The quote signature expired. Fetch a new quote and call payload.setQuote(...).
"error"	ApplePayEventError	The 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.

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").

ApplePayEventError

Field	Type	Required	Description
kind	"configurationError" | "invalidQuote" | "quoteExpired" | "oneTapApplePaySecondFactorRequired" | "genericError"	✅	The error category.
message	string	✅	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 (for example, the browser doesn’t support it) is signalled separately through the "unsupported" event, not as an error.

Result

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

Result envelope

Result<ApplePayFrame, SetupApplePayError>

Field	Type	Required	Description
ok	boolean	✅	Whether the operation succeeded.
value	ApplePayFrame		Present when ok is true.
error	SetupApplePayError		Present when ok is false.

ApplePayFrame

Field	Type	Required	Description
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

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

Setup errors cover frame initialization only (for example, a handshake timeout). Quote problems, second-factor requirements, and Apple Pay availability are reported through onEvent after setup succeeds — as the "error", "quoteExpired", and "unsupported" events respectively.

TS Definitions

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: "buttonPressed" }
  | {
      kind: "complete";
      payload: { transaction: FrameTransaction };
    }
  | {
      kind: "challenge";
      payload: {
        kind: "frame";
        url: string;
      };
    }
  | {
      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: "configurationError" | "genericError";
  message: string;
};