Apple Pay — Hosted Payment Page (iframe)

How to enable Apple Pay when the Hosted Payment Page is loaded inside your own <iframe>, rather than a full-page redirect or lightbox overlay.

Why this needs extra setup: Apple requires that the domain of the website hosting the iframe matches the domain verified during Apple's Merchant validation process. A plain Hosted Payment Page redirect doesn't have this requirement — it only applies when you embed the page in an iframe on your own site.

1. Overview

To enable Apple Pay on a Hosted Payment Page embedded within an HTML <iframe>, Apple requires the domain of the website hosting the iframe to be the same domain verified during Apple's Merchant validation process. The steps below cover that setup.

2. Domain configuration

2.1 MMS configuration

For Apple to verify the domain, it must be added to the list of Merchant custom domains, and the Domain Verification File (DVF) must be placed on that domain's web server.

1. In the Merchant Management System (MMS), go to Preferences → Digital Wallets.
2. Add your store's domain (or domains) to the list of custom domain names.
3. After entering the domain and pressing Enter, a pop-up alerts you that you've changed the Apple Pay Custom Domain Names list and need to download a Domain Verification File — follow the instructions in that pop-up.

2.2 Placing the Domain Verification File

The Domain Verification File is linked in the help pop-up. Download it and place it on your web server in the .well-known directory.

• Apple must be able to download the file from your store's web server at the expected location, or domain registration fails.
• Do not click OK in the MMS pop-up until the file is actually available at that location.
• Apple only supports secure HTTPS URLs — the file cannot be served over HTTP.

2.3 Hosted Integration request

To make the Apple Pay button function correctly when the Hosted Payment Page is loaded inside an iframe, your payment request must include your store's domain via the applePayCheckoutOptions request field.

• The value must be the same domain name registered in the MMS above.
• applePayCheckoutOptions can be encoded using any of the Gateway's supported "Serialised Records" formats. Using JSON:

  { "domainName": "www.exampledomainhere.com" }
  

• Optionally, add a displayName inside the same options object to control the store name shown on the cardholder's Apple Pay confirmation screen. If omitted, the Gateway falls back to any merchantName on the request, or the Merchant Account's configured name.

3. Iframe element markup

The <iframe> tag that will show the Hosted Payment Page needs an allow attribute granting the payment permission policy to the Gateway's domain:

<iframe
   allow="payment https://gateway.examplegatewaydomain.com">
</iframe>

This allows cross-origin communication between your page and the Gateway so the Apple Pay button can function inside the iframe. See the W3C Payment Request spec on cross-origin iframes for background on why this is required.

4. Sample code

A browser form sends the payment request to the Gateway's Hosted Integration, with the resulting Hosted Payment Page shown inside the iframe (via the form's target attribute).

Example request fields:

<form action="https://gateway.examplegatewaydomain.com/paymentform/" method="post" target="my_iframe">
  <input type="hidden" name="action" value="SALE">
  <input type="hidden" name="amount" value="100">
  <input type="hidden" name="countryCode" value="826">
  <input type="hidden" name="currencyCode" value="826">
  <input type="hidden" name="merchantID" value="<MERCHANT_ID>">
  <input type="hidden" name="redirectURL" value="https://exampledomainhere.com/return">
  <input type="hidden" name="transactionUnique" value="Apple Pay Test">
  <input type="hidden" name="type" value="1">
  <input type="hidden" name="applePayCheckoutOptions" value='{"domainName":"exampledomainhere.com"}'>
  <input type="hidden" name="signature" value="f7fe96fb46d23d848e9eba3e930c3180c0d8f6857fcafab9c7f139902e8ee5facb6c05b4b416bf6680047e69779e131826ba6e635d00bda52a8e789ac926a5c9">
  <input type="submit" value="Pay Now">
</form>

<iframe
  allow="payment https://gateway.examplegatewaydomain.com"
  height="900px"
  width="500px"
  name="my_iframe">
</iframe>

The signature value above is a worked example from the source guide — always compute your own using the signing algorithm.

For further request examples, see the Example Integration Code section of the official Integration Guide.

5. Quick reference

Applies when:  the Hosted Payment Page is embedded in your own <iframe> (not a redirect/lightbox)
MMS setup:     Preferences → Digital Wallets → add domain → download Domain Verification File
DVF placement: https://yourdomain.com/.well-known/<file>   (HTTPS only)
Request field: applePayCheckoutOptions = {"domainName": "...", "displayName": "..."(optional)}
Iframe attr:   allow="payment https://gateway.examplegatewaydomain.com"

6. Source

Breathepay's "Hosted Payment Page (iframe) — Apple Pay® Set Up" user guide (V1.00).