Accepting Apple Pay with WooPayments

WooPayments provides your store with Apple Pay, which makes it easier for customers to checkout quickly using their saved Apple Wallet details.

This document describes how to set up, test, and troubleshoot the Apple Pay feature in WooPayments.

To enable Apple Pay:

1. Go to Payments > Settings in your site’s dashboard.
2. Navigate to the Express Checkouts section.
3. Check the box for Apple Pay / Google Pay.
4. Scroll to the bottom of the page.
5. Click Save Changes.

These steps will:

• Create a file on your site that Apple will use to verify your site can offer Apple Pay.
• Communicate to Apple that your site is ready to accept payments via Apple Pay.

When Apple Pay is enabled, the Apple Pay button can appear in three places on your site:

• The Checkout page.
• The Cart page.
• Individual product pages.

You can customize which of these locations show the Apple Pay button. To specify which pages you’d like to display the Apple Pay button:

1. Navigate to Payments > Settings.
2. Select the Customize link for Apple Pay / Google Pay in the Express Checkouts section.

When customizing the Apple Pay settings, you can change:

• Where the Apple Pay button shows up.
• The text of the Apple Pay button itself.
• The size and color scheme of the Apple Pay button.
• The button’s border radius, i.e. how rounded it is.

Note that some customizations may not apply if you’re also using the Express Checkout block’s “Apply uniform styles” setting, introduced in WooCommerce 9.4.0.

By checking out with Apple Pay, customers skip the regular checkout process. All of the customer’s information is handled using the Apple Pay interface, where customers can select their:

• Billing details
• Payment method
• Shipping address, if applicable

Once the transaction is authorized through the customer’s Apple device, WooPayments processes the transaction and redirects the customer to your site’s thank you page.

Apple may offer buy now, pay later options through the usual Apple Pay interface. Note that there is no way for WooPayments to control or disable these offerings, aside from disabling Apple Pay entirely.

Please check Apple’s documentation for further details on what BNPL offerings might be included in Apple Pay and how they work.

You can test Apple Pay while WooPayments is in test mode. A test purchase made using Apple Pay will use the real card details in your Apple Wallet without incurring any actual charges.

To perform a test payment via Apple Pay:

1. Enable test mode.
2. Open your site using a supported device.
3. Select the Apple Pay button.
4. Confirm the purchase using your preferred customer details.

Your test order will be visible in the dashboard after it is completed.

You can read more about the compatibility of Apple Pay here.

Before troubleshooting Apple Pay, ensure you have Log Error Messages enabled under Payments > Settings > Advanced settings. This lets you see any error messages from WooPayments under WooCommerce > Status > Logs, which could potentially be useful if you need to contact our support staff.

To ensure there isn’t a problem with your browser and device combination, try using the Apple Pay button on another website. You can try this demo, for example.

• If Apple Pay does not appear on another site, there is likely not an issue with WooPayments itself.
• If Apple Pay does appear on that demo, but not on your WooPayments store, this can happen for several reasons. To try to remedy the issue, please:
  1. Ensure the Apple Pay / Google Pay setting is enabled under Payments > Settings.
  2. Verify the site is served over HTTPS.
  3. Test with an eligible device with Apple Pay enabled.
  4. Ensure one of the following combinations of settings are configured in WooCommerce > Settings > Accounts & Privacy:
     • Enable guest checkout is enabled, or…
     • Both of the following are enabled:
       • Allow customers to create an account > During checkout
       • Send password setup link

If you’ve ruled out all of those potential issues, that may mean that WooPayments was unable to verify your domain with Apple. See the section below for some background and potential fixes.

What is domain registration? Is my domain registered?

In order for your store to accept Apple Pay transactions, your domain must be registered with and verified by Apple. WooPayments handles this for you automatically when you enable Apple Pay; it does this, in part, by hosting anapple-developer-merchantid-domain-association file under your domain root.

This domain registration file should be accessible via your web browser at the following URL:

https://example.com/.well-known/apple-developer-merchantid-domain-association

If you navigate to this URL in your browser and replace example.com with your site’s domain, it should return a very long string of numbers and letters. Here is how this file looks for WooCommerce.com.

You can check if this file is available from your own site by following these steps:

1. Copy the following URL: https://example.com/.well-known/apple-developer-merchantid-domain-association
2. Paste the URL in a new browser tab or window.
3. Edit the URL to replace example.com with your own domain.
4. Navigate to the resulting URL.

The domain registration file is not accessible

If the apple-developer-merchantid-domain-association file is not accessible from your web browser, then WooPayments may be running into an issue creating it.

To recreate the file and go through the domain verification process again, you can:

1. Navigate to Settings > Permalinks and make sure you have your permalinks set to anything other than Plain.
   • If they already are set to anything other than Plain, re-save your permalinks.
2. Trigger domain registration again by:
   1. Navigating to Payments > Settings.
   2. Unchecking the Apple Pay / Google Pay box in the Express Checkouts section.
   3. Scrolling to the bottom of the page.
   4. Selecting Save Changes.
   5. Checking the Apple Pay / Google Pay box in the Express Checkouts section to re-enable Apple Pay.
   6. Scrolling to the bottom and click Save Changes again.
   7. Clearing your browser cache.
   8. Testing if the Apple Pay button appears as expected.

If the button still does not show up:

1. Check the error logs under WooCommerce > Status > Logs.
2. Assess the logs to see if there are domain registration related errors.

If you see an error, it may be that the apple-developer-merchantid-domain-association file is not publicly available from your domain root.

Adding the domain registration file manually

If WooPayments cannot write the apple-developer-merchantid-domain-association file to your server automatically, you can add it manually.

To upload this file:

1. Download the file here.
2. Use SFTP or SSH to upload it to the .well-known directory on your server.
   • You may need to create a .well-known directory in the root directory of your site if none exists
   • The final location should be: https://example.com/.well-known/apple-developer-merchantid-domain-association
3. Follow the steps here to trigger domain registration again
4. Determine if the Apple Pay button appears as expected..

If the Apple Pay button is missing from only some locations but not others — like the product page — this can happen because:

• The product may not be compatible with express checkouts.
• Your theme may not support the necessary WooCommerce hooks, which are needed for Apple Pay to show up.

If you experience any other issues with Apple Pay, please take the following steps:

1. Enable test mode and logging under Payments > Settings > Advanced settings.
2. Attempt an Apple Pay transaction.
3. Review the logs under WooCommerce > Status > Logs.
4. Contact support and provide the logs for review.