Apple Pay

Details on working with the Apple Pay frame.

URL

https://blocks.moonpay.com/platform/v1/apple-pay

Requirements

Size

The frame container height must be 44px. Width is flexible; the Apple Pay button inside the frame uses 100% of the container width.

Permissions

The payment permission policy is required.

In test mode, the frame uses window.confirm to simulate the Apple Pay payment. If your iframe uses the sandbox attribute, you will need to include allow-modals.

Example

<iframe
  src="https://blocks.moonpay.com/platform/v1/apple-pay"
  allow="payment"
/>

WKWebView

To embed the Apple Pay frame in a native iOS app, you render it inside a WKWebView. The frame communicates with the host app through the postMessage-based frames protocol. See Events below.

You must handle JavaScript dialogs. The frame uses window.confirm, for example to present the simulated Apple Pay sheet in test mode. By default a WKWebView silently dismisses window.confirm, alert, and prompt: the call returns false with no UI shown, and the frame reads that as the customer cancelling, so the transaction comes back with status: "failed".

To fix this, conform your view controller to WKUIDelegate, set webView.uiDelegate, and present the confirm panel, for example as a UIAlertController:

extension MoonPayFrameViewController: WKUIDelegate {
    func webView(_ webView: WKWebView,
                 runJavaScriptConfirmPanelWithMessage message: String,
                 initiatedByFrame frame: WKFrameInfo,
                 completionHandler: @escaping (Bool) -> Void) {
        // Present the dialog and return the customer's choice.
    }
}

Wire this even if you only ship live mode, since the default behaviour applies to any dialog the frame surfaces.

For a complete native walkthrough that covers rendering the frame, wiring the bridge and events, and the full dialog handler, see iOS manual integration.

Initialization parameters

Property	Type	Required	Description
clientToken	string	✅	The client token returned from the connect flow.
channelId	string	✅	A unique identifier for the frame generated on your client. This value is attached to each postMessage payload to help identify messages. The format of this string is up to you.
signature	string	✅	The quote signature from the quote endpoint. Pass signature as returned.
externalTransactionId	string		Your own identifier for the transaction. Stored and associated with the MoonPay transaction for correlation.
theme	string		Pass dark or light to force a specific appearance. If you omit this, the frame uses the user’s system appearance.

Events

All events are dispatched using the message pattern described in the frames protocol. Below are the event payloads specific to the Apple Pay frame.

Outbound events

frame->parent

These events are sent from this frame to the parent window.

handshake

The frame requests that you open a message channel.

Example

{
  "version": 2,
  "meta": { "channelId": "ch_1" },
  "kind": "handshake"
}

type Message<T> = T & {
  version: 2;
  meta: { channelId: string };
};

type HandshakeEvent = Message<{
  kind: "handshake";
}>;

ready

The frame finished loading and the UI is fully rendered. You can use this to coordinate UI transitions if needed.

Example

{
  "version": 2,
  "meta": { "channelId": "ch_1" },
  "kind": "ready"
}

type Message<T> = T & {
  version: 2;
  meta: { channelId: string };
};

type ReadyEvent = Message<{
  kind: "ready";
}>;

buttonPressed

The customer tapped the Apple Pay button. The frame emits this the instant the button is tapped, before iOS presents the PassKit payment sheet. Treat it as an intent-to-buy signal: use it to react to the tap, for example to show a loading state or fire analytics.

This event carries no payload. Route it by channelId.

buttonPressed is not a purchase outcome. It still fires if the customer opens the payment sheet and then cancels, and it fires before any authorization happens. For the transaction result, listen for complete, which reports the outcome once the payment resolves.

Example

{
  "version": 2,
  "meta": { "channelId": "ch_1" },
  "kind": "buttonPressed"
}

type Message<T> = T & {
  version: 2;
  meta: { channelId: string };
};

type ButtonPressedEvent = Message<{
  kind: "buttonPressed";
}>;

complete

The transaction is complete. Use the transaction ID to track status updates (for example, by polling or via webhooks).

Example (success)

{
  "version": 2,
  "meta": { "channelId": "ch_1" },
  "kind": "complete",
  "payload": {
    "transaction": {
      "id": "txn_01",
      "status": "pending"
    }
  }
}

{
  "version": 2,
  "meta": { "channelId": "ch_1" },
  "kind": "complete",
  "payload": {
    "transaction": {
      "status": "failed",
      "failureReason": "Your payment was declined by your bank.",
      "failureCode": "authorizationDeclined"
    }
  }
}

type Message<T> = T & {
  version: 2;
  meta: { channelId: string };
};

enum TransactionStatus {
  /** The transaction has successfully completed. The payment has been made and the crypto has been transferred. **/
  completed = "completed",
  /** The payment has been completed and the crypto transfer is underway. **/
  pending = "pending",
  /** The transaction has failed. No payment was applied and the crypto was not transferred. **/
  failed = "failed",
}

type FailureCode =
  | "applePayMerchantUnavailable"
  | "transactionNotAllowed"
  | "validationError"
  | "serviceUnavailable"
  | "authorizationDeclined"
  | "unknown";

type Transaction =
  | {
      /** The MoonPay identifier for this transaction. **/
      id: string;
      /** The status of the transaction. **/
      status: TransactionStatus.completed | TransactionStatus.pending;
    }
  | {
      status: TransactionStatus.failed;
      /** A stable, machine-readable code identifying the failure category. Branch on this value for programmatic handling. May be omitted when the frame cannot classify the failure. **/
      failureCode?: FailureCode;
      /** A developer-friendly error message detailing the reason for the transaction failure. **/
      failureReason: string;
    };

type ApplePayCompleteEvent = Message<{
  kind: "complete";
  payload: {
    transaction: Transaction;
  };
}>;

Failure codes

When a complete event has status: "failed", the failureCode field indicates the failure category. Use this value — not failureReason — for programmatic branching. failureReason is a human-readable fallback suitable for display when you do not have custom copy for a given code.

failureCode is optional. When the frame cannot classify a failure, it sends failureReason alone — fall back to showing that message to the customer.

failureCode	Default failureReason	When it fires	Recommended handling
applePayMerchantUnavailable	”Apple Pay is temporarily unavailable. Please try again later.”	Apple Pay merchant validation failed.	Retry after a short delay or offer an alternative payment method.
transactionNotAllowed	”This transaction is not allowed for your account.”	Payment method or account is not eligible (for example, region restriction or KYC limit).	Show the failureReason and guide the customer to resolve the issue or choose a different payment method.
validationError	”The transaction request was invalid.”	Request failed validation (unsupported currency, missing parameters).	Check the quote parameters and retry with corrected values.
serviceUnavailable	”Service temporarily unavailable. Please try again.”	Upstream payment service is degraded or returned a 5xx response.	Retry with exponential back-off.
authorizationDeclined	”Your payment was declined by your bank.”	The issuer or gateway rejected the authorization.	Prompt the customer to try a different card.
unknown	”An unexpected error occurred.”	Any unexpected or unclassified error, including thrown authorization exceptions and fraud blocks.	Show the failureReason to the customer and retry.

Quote expiry is reported through the error event with code: "quoteExpired", not through complete. Listen for both events to cover all failure paths.

challenge

Verification is required before the transaction can proceed. Render the challenge frame at the provided URL. Do not construct the URL yourself — use it as-is.

Example

{
  "version": 2,
  "meta": { "channelId": "ch_1" },
  "kind": "challenge",
  "payload": {
    "kind": "frame",
    "url": "https://blocks.moonpay.com/platform/v1/challenge?challengeToken=..."
  }
}

type Message<T> = T & {
  version: 2;
  meta: { channelId: string };
};

type ApplePayChallengeEvent = Message<{
  kind: "challenge";
  payload: {
    kind: string;
    /** Fully-formed URL to pass directly as the challenge frame src. */
    url: string;
  };
}>;

error

This event dispatches errors that occur in the flow and, if available, provides steps for recovery.

Example

{
  "version": 2,
  "meta": { "channelId": "ch_1" },
  "kind": "error",
  "payload": {
    "code": "applePayUnavailable",
    "message": "Apple Pay is not supported."
  }
}

type Message<T> = T & {
  version: 2;
  meta: { channelId: string };
};

type ApplePayError = Message<{
  kind: "error";
  payload: {
    code:
      | "configurationError"
      | "quoteExpired"
      | "invalidQuote"
      | "applePayUnavailable"
      | "generic";
    /** A developer-facing error message with details on recovery or documentation. This message is not intended to be rendered in UI. */
    message: string;
  };
}>;

Code	Description
configurationError	The frame configuration is invalid. Check initialization parameters.
quoteExpired	The quote has expired. Fetch a new quote and send it via setQuote.
invalidQuote	The quote signature is invalid or malformed.
applePayUnavailable	Apple Pay is not available in the current environment or browser.
generic	An unexpected error occurred.

Inbound events

parent->frame

These events are sent from the parent window to this frame.

ack

Acknowledge the handshake.

Example

{
  "version": 2,
  "meta": { "channelId": "ch_1" },
  "kind": "ack"
}

type Message<T> = T & {
  version: 2;
  meta: { channelId: string };
};

type AckEvent = Message<{
  kind: "ack";
}>;

setQuote

Provide a new quote to the frame. Pass signature as returned by the quote endpoint. Upon receiving this event, the frame disables the Apple Pay button until the quote is revalidated.

Example

{
  "version": 2,
  "meta": { "channelId": "ch_1" },
  "kind": "setQuote",
  "payload": {
    "quote": {
      "signature": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9..."
    }
  }
}

type Message<T> = T & {
  version: 2;
  meta: { channelId: string };
};

type SetQuoteEvent = Message<{
  kind: "setQuote";
  payload: {
    quote: {
      /** The signature from a valid quote. **/
      signature: string;
    };
  };
}>;