Apple Pay - MoonPay Developer Docs

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.

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

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

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

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

`complete`

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

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

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

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

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

{
  "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;
    };
  };
}>;

​URL

​Requirements

​Size

​Permissions

​WKWebView

​Initialization parameters

​Events

​Outbound events

​handshake

​ready

​complete

Failure codes

​challenge

​error

​Inbound events

​ack

​setQuote

URL

Requirements

Size

Permissions

WKWebView

Initialization parameters

Events

Outbound events

`handshake`

`ready`

`complete`

`challenge`

`error`

Inbound events

`ack`

`setQuote`