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 into your UI and initiate a transaction with an executable quote signature.
Setup Apple Pay
import { createClient, type ApplePayEvent } from "@moonpay/platform";
const clientResult = createClient({ sessionToken: "c3N0XzAwMQ==" });

if (!clientResult.ok) {
  // Handle error
}

const client = clientResult.value;

const applePayResult = await client.setupApplePay({
  quote: quoteResult.value.signature,
  container: document.querySelector("#applePayContainer"),
  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 "challenge":
        // Render the challenge frame at the provided URL
        // See: /platform/guides/handling-challenges
        console.log(event.payload.url);
        break;
      case "error":
        console.error(event.payload.message);
        break;
      case "unsupported":
        break;
    }
  },
});

if (!applePayResult.ok) {
  // Handle error
  console.error(applePayResult.error);
}

const applePay = applePayResult.value;

​
Parameters

PropertyTypeRequiredDescription
quotestring✅The quote signature returned from getQuote.
containerHTMLElement✅A DOM element to render the Apple Pay frame into.
onEvent(event: ApplePayEvent) => void✅Callback invoked for Apple Pay flow events. See ApplePayEvent.
This method does not require a clientToken parameter. 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: [Transaction](#transaction) }The Apple Pay flow finished and a transaction was created.
"challenge"{ url: string }Verification required. Render the challenge frame at the provided URL.
"quoteExpired"{ setQuote: (quoteSignature: 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 supported or available in the user’s current environment.

​
Transaction

This is the transaction object returned when the Apple Pay flow completes. See the API reference for details.
FieldTypeRequiredDescription
status"complete" | "pending" | "failed"✅The current transaction status.
idstringPresent when status is "complete" or "pending".
failureReasonstringPresent when status is "failed". A developer-friendly reason.

​
ApplePayEventError

FieldTypeRequiredDescription
kind"configurationError" | "invalidQuote" | "quoteExpired" | "applePayUnavailable" | "genericError"✅The error category.
messagestring✅Developer-friendly details.

​
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(quoteSignature: 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"configurationError" | "invalidQuote" | "quoteExpired" | "applePayUnavailable" | "genericError"✅The error category.
messagestring✅Developer-friendly details.
types.ts
type ApplePayFrame = {
  setQuote: (quoteSignature: string) => void;
  dispose: () => void;
};

type Transaction =
  | {
      id: string;
      status: "complete" | "pending";
    }
  | {
      status: "failed";
      failureReason: string;
    };

type ApplePayEvent =
  | {
      kind: "ready";
    }
  | {
      kind: "complete";
      payload: {
        transaction: Transaction;
      };
    }
  | {
      kind: "challenge";
      payload: {
        /** Fully-formed URL to pass directly as the challenge frame src. */
        url: string;
      };
    }
  | {
      kind: "quoteExpired";
      payload: {
        setQuote: (quoteSignature: string) => void;
      };
    }
  | {
      kind: "error";
      payload: ApplePayEventError;
    }
  | {
      kind: "unsupported";
    };

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

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