Pay with Apple Pay

Use this guide to execute a transaction with Apple Pay after you have a connected customer. To let new customers buy with Apple Pay before they have a MoonPay account, see Guest checkout. See the Going Live section for details on the requirements you must meet before you can take this integration to production.

Prerequisites

A connected customer (via client.getConnection() or client.connect()).
A UI surface where you can render the Apple Pay frame.

You can test the full Apple Pay flow without a real Apple Pay account by using test mode. The frame renders a mock Apple Pay button that simulates successful and failed transactions.

Device and browser support

Apple Pay is available in Safari on macOS and in every iOS browser. The customer also needs a card set up in Apple Pay. In other browsers, the frame reports Apple Pay as unavailable and renders nothing. It does not offer Apple’s cross-device flow, where the page shows a QR code that the customer scans with their iPhone to approve the payment. The widget does support the cross-device flow. In a native iOS app, you can embed the Apple Pay frame in a WKWebView. By default, WKWebView silently dismisses the JavaScript dialogs the frame relies on, so you must handle them through WKUIDelegate. See the frame requirements and the iOS manual integration guide. When Apple Pay isn’t available in the customer’s environment, the frame emits an unsupported event. Use it to build the experience that fits your product — for example, hide the Apple Pay option up front, or route customers who select Apple Pay to the widget with your apple_pay quote. The code sample in Execute the transaction handles this event.

Display payment methods

Use the SDK or API to fetch and display the payment methods that are available for the customer right now.

// After connecting, list available payment methods
const paymentMethodsResult = await client.getPaymentMethods();

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

console.log(paymentMethodsResult.value);

[
  {
    type: "apple_pay",
    capabilities: {
      supportedCurrencies: ["USD", "EUR", "GBP"],
      supportedTransactionTypes: ["buy"],
    },
    availability: {
      active: true,
    },
  },
];

Get quotes

Quotes provide real-time prices and fees for transactions. Show the contextual quote summary above the Apple Pay button. The Apple Pay sheet presents fees, so you do not need to render a fee breakdown. See Going Live for the required presentation and fee behavior for how fees relate to the source amount. Only quotes with executable: true can be used to execute a transaction. See the quotes API reference for the fields required to receive executable: true.

const quoteResult = await client.getQuote({
  source: { asset: { code: "USD" }, amount: "100.00" }, // The fiat currency and amount to pay
  destination: { asset: { code: "ETH" } }, // The crypto the customer will receive
  wallet: { address: "0x1234..." }, // The destination wallet address
  paymentMethod: { type: "apple_pay" }, // The payment method type
});

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

console.log(quoteResult.value);

{
  source: {
    amount: "100.00",
    asset: {
      code: "USD",
      name: "US Dollar",
      precision: 2
    }
  },
  destination: {
    amount: "0.025",
    asset: {
      code: "ETH",
      name: "Ethereum",
      precision: 18
    }
  },
  fees: {
    network: {
      amount: "2.50",
      currencyCode: "USD"
    },
    moonpay: {
      amount: "3.99",
      currencyCode: "USD"
    }
  },
  wallet: {
    address: "0x1234..."
  },
  paymentMethod: {
    type: "apple_pay"
  },
  expiresAt: "2026-01-12T14:45:00Z",
  executable: true,
  signature: "eyJhbGciOiJFUzI1NiIs..."
}

Execute the transaction

To execute a transaction, set up the payment flow based on the quote. Different payment methods have different requirements—you can configure each as needed to control your experience. For the frame URL, size, permissions, and events, see the Apple Pay frame reference.

Some transactions require a challenge — the Apple Pay frame emits a challenge event when extra verification is needed. See Handle challenges for the full flow.

Apple Pay

import type { ApplePayEvent } from "@moonpay/platform-sdk-web";

// Render the Apple Pay frame into your UI and handle callbacks
const applePayResult = await client.setupApplePay({
  quote: quoteResult.value.signature, // The quote signature from getQuote

  container: document.querySelector("#applePayContainer"), // DOM element to render the button

  onEvent: (event: ApplePayEvent) => {
    switch (event.kind) {
      case "ready":
        // The frame is ready. Use this event to reveal the button if needed.
        break;

      case "complete": {
        const txn = event.payload.transaction;

        if (txn.status === "failed") {
          // The transaction failed. Branch on failureCode for programmatic handling.
          switch (txn.failureCode) {
            case "authorizationDeclined":
              // Prompt the customer to try a different card.
              break;

            case "serviceUnavailable":
            case "applePayMerchantUnavailable":
              // Retry after a short delay.
              break;

            default:
              // Show txn.failureReason to the customer.
              break;
          }
          break;
        }

        // The transaction is executing. Track the final status via polling and/or webhooks.
        console.log(txn);
        // { id: "txn_01", status: "pending" }
        break;
      }

      case "challenge":
        // Verification required. Render the challenge frame at the provided URL.
        // See: /platform/guides/handling-challenges
        console.log(event.payload.url);
        break;

      case "quoteExpired":
        // Fetch a new quote, then pass its signature into the frame
        // const newQuote = await client.getQuote({...});
        // event.payload.setQuote(newQuote.value.signature);
        break;

      case "error":
        // Depending on the error, you can have the customer pick a different payment method or retry.
        console.error(event.payload.message);
        break;

      case "unsupported":
        // Apple Pay isn't supported in the current environment.
        break;
    }
  },
});

if (!applePayResult.ok) {
  // Handle error setting up Apple Pay
}

// You can update the quote or dispose the frame later
// applePayResult.value.setQuote(newQuoteSignature);
// applePayResult.value.dispose();

Transaction statuses

Transactions have the following statuses:

Pending: The transaction has been initiated and the payment accepted. The assets are being transferred.
Complete: The transaction is finalized. The payment is complete and the assets have been delivered to their destination.
Failed: The transaction has failed. The payment was not executed and funds were not transferred.

Overview

Customers

Payments

Integration essentials

SDK Reference

Frames

Prerequisites

Device and browser support

Display payment methods

Get quotes

Execute the transaction

Transaction statuses

​Prerequisites

​Device and browser support

​Display payment methods

​Get quotes

​Execute the transaction

​Transaction statuses

Prerequisites

Device and browser support

Display payment methods

Get quotes

Execute the transaction

Transaction statuses