Accept & send payments with Apple Pay

Register your domains

Any domains accepting payments must first be registered and verified with Apple. You can do this through the Moov Dashboard. Domains must be registered for each individual merchant account, which is the destination of the Moov transfer.

Within an account, navigate to the Settings tab and click the Add a domain button to add domains to Apple Pay.

To verify your domain, download the file and host it at the path shown for each domain you are registering. Ensure the file is in place before clicking Add domain. Note that serving the domain verification file via a redirect is a common cause of failure. If you encounter any issues, refer to this Apple Pay troubleshooting guide for guidance on common causes and resolutions.

You will now see a list of the domains you’ve added. You can come back to this page to remove or add domains.

Add Apple Pay button

Using the browser-native Payment Request API, no additional libraries are needed to add an Apple branded button, since everything is supported within Safari. Alternatively, you can also use the Apple Pay JS API.

Add a button element to your webpage and use the Apple Pay documentation to set the button type, and to see best practices on using CSS. For disbursements, we recommend using the continue button type from Apple.

Here’s sample code for adding a black Buy with Apple Pay button, using the default size and corner radius:

<button class="apple-pay-button"></button>
<style>
  .apple-pay-button {
    -webkit-appearance: -apple-pay-button;
    border-radius: .5rem;
    height: 2.75rem;
    cursor: pointer;
  }
</style>

You can use the canMakePayment() method to check if the device supports Apple Pay:

const supportsApplePay = new PaymentRequest(
  [{ supportedMethods: "https://apple.com/apple-pay" }],
  details
).canMakePayment();

// Supports Apple Pay?
if (await supportsApplePay) {
  // show Apple Pay logo, for instance
  return;
}

Set up the Payment Request API for Apple Pay

After adding the button, you can set up methods, details, and options in the Payment Request API.

Methods

In Methods, indicate Apple Pay as a payment method by using:

• "https://apple.com/apple-pay"
• Apple Pay certified Moov account ID
• Capabilities
• Supported networks

For more details, read the W3 documentation on Methods.

Details

In Details, you can specify transaction details. For example, the transaction’s amount, shipping options, display items, and other modifiers. For Apple Pay transactions, Moov has a platform limit of $100,000.00 per transaction. If you need a higher limit for your use-case, please contact Moov support.

For disbursements, use the modifiers array to pass an Apple Pay disbursement request, which surfaces a "Send" confirmation in the Apple Pay sheet and lets you collect recipient contact fields.

For more details, read the W3 documentation on Details.

Options

In Options, you can include any specific customer details or shipping information.

For more details, read the W3 documentation on Options.

// Sets up methods, details, and options for Payment Request API
const methods = [
  {
    supportedMethods: "https://apple.com/apple-pay",
    data: {
      version: 3,
      merchantIdentifier: "merchants-moov-account-id",
      merchantCapabilities: ["supports3DS", "supportsCredit", "supportsDebit"],
      supportedNetworks: ["amex", "discover", "masterCard", "visa"],
      countryCode: "US",
      requiredBillingContactFields: ["postalAddress"]
    },
  }
];

// Details about the purchase
const details = {
  total: {
    label: "Typically the merchant name",
    amount: { value: "1.00", currency: "USD" },
  }
};

const options = {
  requestPayerName: true,
  requestPayerEmail: true,
  requestPayerPhone: false
};

const APPLE_PAY_METHOD_URL = "https://apple.com/apple-pay";

// Fields collected for the recipient receiving the funds
const requiredRecipientContactFields = ["name", "email", "postalAddress"];

const methods = [
  {
    supportedMethods: APPLE_PAY_METHOD_URL,
    data: {
      version: 14,
      merchantIdentifier: "merchants-moov-account-id",
      merchantCapabilities: ["supports3DS", "supportsDebit", "supportsInstantFundsOut"],
      supportedNetworks: ["visa", "masterCard"],
      countryCode: "US",
      currencyCode: "USD"
    }
  }
];

// Total the recipient will receive
const details = {
  total: {
    label: "Typically the merchant name",
    amount: { value: "1.00", currency: "USD" }
  },
  modifiers: [
    {
      supportedMethods: APPLE_PAY_METHOD_URL,
      data: {
        disbursementRequest: {
          requiredRecipientContactFields
        },
        additionalLineItems: [
          { label: "Payout", amount: "1.00" },
          {
            label: "Instant Funds Out Fee",
            amount: "0.00",
            disbursementLineItemType: "instantFundsOutFee"
          },
          {
            label: "Typically the merchant name",
            amount: "1.00",
            disbursementLineItemType: "disbursement"
          }
        ]
      }
    }
  ]
};

const options = {};

Detect if Apple Pay is available

The Apple Pay button should only be displayed if your user is using a supported device. You can check if the browser will support ApplePaySession with the call below:

if (window.PaymentRequest) {
  // If available, show Apple Pay button
}

Another option is to use Apple’s JS library canMakePaymentsWithActiveCard method to check if the device supports Apple Pay, and the user has an active card in their wallet. In the request below, use the merchant’s Moov accountID as the merchantIdentifier.

if (window.ApplePaySession) {
  let merchantIdentifier = 'merchants-moov-account-id';
  let promise = ApplePaySession.canMakePaymentsWithActiveCard(merchantIdentifier);
  promise.then((canMakePayments) => {
    if (canMakePayments) {
        // Display Apple Pay button here.
    }
  });
}

Now that you have verified eligibility and added the button, you are ready to create a payment request with the previously defined options when the button is clicked:

const paymentRequest = new PaymentRequest(methods, details, options);

Create & validate a merchant session

Once the payment request has been created, it’s time to create and validate an Apple Pay merchant session using the Moov API’s create Apple Pay session POST endpoint, or Moov.js method shown below:

moov.accounts.applePay.sessions.create({ 
  accountID: 'merchants-moov-account-id', 
  applePaySessionConfig: { displayName: 'string' }
});

This request accepts the account ID and display name of the merchant that will be accepting the payment. The response is a promise that includes the opaque merchantSession response from Apple to be used to resolve the onmerchantvalidation step.

• accountID - Moov account ID of the merchant, which is the destination of the transfer
• displayName - Merchant name for display in the Apple Pay payment sheet, for example, “Whole Body Fitness”

Link an Apple Pay token

Link an Apple Pay token to the payer or recipient's Moov account using the Moov API's link Apple Pay token POST endpoint, or Moov.js method shown below. The request accepts the account ID as well as the opaque paymentResponse from Apple.

On API v2026.04.00 and later, the response is an array of payment methods — one per supported Apple Pay flow that could be created for the linked token. Filter the array by paymentMethodType to pick the paymentMethodID you need for your transfer.

const paymentMethods = await moov.accounts.applePay.tokens.create({
  accountID: 'payers-moov-account-id',
  applePayToken: paymentResponse.details
});

const paymentMethodID = paymentMethods.find(
  (pm) => pm.paymentMethodType === "apple-pay"
)?.paymentMethodID;

const paymentMethods = await moov.accounts.applePay.tokens.create({
  accountID: 'recipients-moov-account-id',
  applePayToken: paymentResponse.details
});

const paymentMethodID = paymentMethods.find(
  (pm) => pm.paymentMethodType === "push-to-apple-pay"
)?.paymentMethodID;

Create a transfer & dismiss payment sheet

Use the paymentMethodID you filtered from the link-token response as the transfer source (for pay-ins) or destination (for payouts) when calling Moov's create transfer POST endpoint. No Moov.js method exists for creating a transfer.

Use the X-Wait-For header on the transfer request to receive a synchronous response so you can close out the payment sheet.

// Pseudo-code: instruct your server to make the transfer
const moovTransferResponse = await fetch(`/pay`, {
  method: 'post',
  body: JSON.stringify({ paymentMethodID })
});

let status;
if (moovTransferResponse.source.cardDetails.status === 'confirmed') {
  status = 'success';
} else {
  status = 'fail';
}

try {
  paymentResponse.complete(status);
  // Payment sheet is dismissed
} catch (error) {
  console.error(error);
}

// Pseudo-code: instruct your server to make the payout
const moovTransferResponse = await fetch(`/payout`, {
  method: 'post',
  body: JSON.stringify({ paymentMethodID })
});

let status;
if (moovTransferResponse.destination.cardDetails.status === 'completed') {
  status = 'success';
} else {
  status = 'fail';
}

try {
  paymentResponse.complete(status);
  // Payment sheet is dismissed
} catch (error) {
  console.error(error);
}