Skip to main content

​
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"
/>

​
Initialization parameters

PropertyTypeRequiredDescription
clientTokenstring✅The client token returned from the connect flow.
channelIdstring✅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.
signaturestring✅The quote signature from the quote endpoint. Pass signature as returned.
externalTransactionIdstringYour own identifier for the transaction. Stored and associated with the MoonPay transaction for correlation.
themestringPass 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"
}

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

​
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"
    }
  }
}
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.
failureCodeDefault failureReasonWhen it firesRecommended 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=..."
  }
}

​
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."
  }
}
CodeDescription
configurationErrorThe frame configuration is invalid. Check initialization parameters.
quoteExpiredThe quote has expired. Fetch a new quote and send it via setQuote.
invalidQuoteThe quote signature is invalid or malformed.
applePayUnavailableApple Pay is not available in the current environment or browser.
genericAn 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"
}

​
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..."
    }
  }
}