Apple Pay

URL

https://platform.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. If you set a custom height through applePayButtonSettings, size the frame container to match that height instead of 44px.

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://platform.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 from the connect flow, or from the connection check when you offer guest checkout.
`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.
`applePayButtonSettings`	`string`		A `JSON.stringify`-ed, URL-encoded object that styles the Apple Pay button. See Apple Pay button settings.

Apple Pay button settings

Use applePayButtonSettings to style the Apple Pay button without injecting custom CSS. Build a settings object, pass it through JSON.stringify, URL-encode the result, and append it to the frame URL. Every property is optional. Any property you omit keeps the button’s default.

Property	Type	Allowed values
`width`	`string`	Button width in pixels, as a bare number (`"320"`) or a `px` value (`"320px"`). Normalized to `"<n>px"`. Defaults to `100%` so the button fills the container.
`height`	`string`	Button height in pixels, in the same format as `width`. Defaults to `44px`.
`borderRadius`	`string`	Corner radius in pixels, in the same format as `width`. Defaults to `16px`.
`paddingX`	`string`	Horizontal padding in pixels, in the same format as `width`. Defaults to `16px`.
`paddingY`	`string`	Vertical padding in pixels, in the same format as `width`. Defaults to `8px`.
`style`	`string`	The button’s visual style. One of `black`, `white-outline`, or `white`. When you omit this, the button follows the frame’s `theme`: light renders the black button and dark renders the white button.
`type`	`string`	The button label. One of `plain`, `buy`, `top-up`, `reload`, `continue`, `check-out`, or `pay`. Defaults to `pay`.
`locale`	`string`	The button’s language. One of `en-US`, `ar-AB`, `ca-ES`, `zh-CN`, `zh-HK`, `zh-TW`, `hr-HR`, `cs-CZ`, `da-DK`, `de-DE`, `nl-NL`, `en-AU`, `en-GB`, `fi-FI`, `fr-CA`, `fr-FR`, `el-GR`, `he-IL`, `hi-IN`, `hu-HU`, `id-ID`, `it-IT`, `ja-JP`, `ko-KR`, `ms-MY`, `nb-NO`, `pl-PL`, `pt-BR`, `pt-PT`, `ro-RO`, `ru-RU`, `sk-SK`, `es-MX`, `es-ES`, `sv-SE`, `th-TH`, `tr-TR`, `uk-UA`, or `vi-VN`.

Dimensions accept pixels only. A bare number is treated as pixels and normalized to a px value.

Validation

Validation applies each property on its own:

A property with an invalid value is ignored, and the remaining valid properties still apply. Invalid values include a non-pixel dimension such as 50%, and a style, type, or locale outside its allowed set.
If the whole value is not valid JSON, the frame ignores applePayButtonSettings entirely and uses the defaults.

Example

This object sets a 52px-tall white button with a 26px corner radius, the buy label, and French text:

{
  "height": "52",
  "borderRadius": "26",
  "style": "white",
  "type": "buy",
  "locale": "fr-FR"
}

Run it through JSON.stringify, URL-encode the result, and append it to the frame URL:

https://platform.moonpay.com/platform/v1/apple-pay?...&applePayButtonSettings=%7B%22height%22%3A%2252%22%2C%22borderRadius%22%3A%2226%22%2C%22style%22%3A%22white%22%2C%22type%22%3A%22buy%22%2C%22locale%22%3A%22fr-FR%22%7D

If you set a custom height, size the frame container to match.

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

`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.

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

{
  "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://platform.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;
  };
}>;

`cancelled`

The customer dismissed the native Apple Pay sheet without completing the payment. This is a user cancellation, not a failure, so handle it separately from error. Re-enable your UI so the customer can try again, and log the abandonment if you track it. The payload carries code: "payment_sheet_dismissed" and a developer-facing message. The message is not intended to be rendered in UI.

{
  "version": 2,
  "meta": { "channelId": "ch_1" },
  "kind": "cancelled",
  "payload": {
    "code": "payment_sheet_dismissed",
    "message": "The customer dismissed the Apple Pay sheet before completing payment."
  }
}

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

type ApplePayCancelledEvent = Message<{
  kind: "cancelled";
  payload: {
    /** Always `payment_sheet_dismissed` for this event. */
    code: "payment_sheet_dismissed";
    /** A developer-facing message. This message is not intended to be rendered in UI. */
    message: 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;
    };
  };
}>;

Overview

Customers

Payments

Integration essentials

SDK Reference

Frames

URL

Requirements

Size

Permissions

WKWebView

Initialization parameters

Apple Pay button settings

Validation

Example

Events

Outbound events

`handshake`

`ready`

`buttonPressed`

`complete`

Failure codes

`challenge`

`cancelled`

`error`

Inbound events

`ack`

`setQuote`

​URL

​Requirements

​Size

​Permissions

​WKWebView

​Initialization parameters

​Apple Pay button settings

​Validation

​Example

​Events

​Outbound events

​handshake

​ready

​buttonPressed

​complete

Failure codes

​challenge

​cancelled

​error

​Inbound events

​ack

​setQuote

URL

Requirements

Size

Permissions

WKWebView

Initialization parameters

Apple Pay button settings

Validation

Example

Events

Outbound events

`handshake`

`ready`

`buttonPressed`

`complete`

`challenge`

`cancelled`

`error`

Inbound events

`ack`

`setQuote`