Integrating Apple Pay into an HTML inline frame (iframe) on your website

iOS 16 and earlier

On iOS 16 and earlier, Apple Pay on the Web required Safari—and all interactions with the Apple Pay API to come from the parent/top level page. In order to facilitate the Apple Pay button in an HTML inline frame (iframe), there will need to be cross frame communication between the child and parent pages. Cross frame communication should be secure and robust, therefore the use of postMessage for this purpose is recommended.

The expectation is for all communication with Apple Pay to occur from the parent page, so the iframe must relay all Apple Pay related events to the parent to handle. Some examples:

• Apple Pay availability: The parent calls applePayCapabilities, then sends the message of the response to the iframe, which then uses the value to toggle the visibility of the Apple Pay button.
• Apple Pay session: The iframe receives an onclick() event when the Apple Pay button is clicked and sends the message to the parent (providing details about the transaction). The parent create the payment request to obtain the session validation URL, and eventually receive session credentials and invokes completeMerchantValidation() to prevent the payment sheet. After the payment is authorized by the Payment Service Provider (PSP), the parent either:
  • Redirects the parent page to a payment success page; or
  • Sends a message to the iframe to complete the transaction flow itself.

iOS 17 and later

On IOS 17 and later, the iframe HTML element should include the allow="payment" attribute, which should facilitate the cross frame communications instead of needing a dedicated JavaScript library. This means all of the Apple Pay code/calls can reside in the iframe page—which is typically a hosted page from a Payment Service Provider (PSP), all the parent page—typically a merchant—has to do is add the attribute mentioned above to the iframe element.

Important: Regardless of the iOS version, the PSP/merchant always needs to make sure the parent page domain is the one registered in the Developer portal, and used in the request to generate a merchant session via ApplePaySession.

Cheers,

Paris X Pinkney |  WWDR | DTS Engineer