ℹ️

If you are using React as the framework of choice for the frontend, we highly recommend using our SDK as we will handle the cross-domain issues for you under the SDK

Embedding iframe allows you to seamlessly embed a hosted Breeze payment page directly within your web application. This approach is recommended when we want to avoid redirecting users to the hosted page on Breeze to keep the user experience on your web application seamless.

How It Works

1. Your application creates a payment session on your backend server
2. The iframe loads the hosted payment URL

📘

To comply with HTML guidelines for cross-domain payments, please ensure allow="payment pay.breeze.cash" is enabled on the iframe.

<iframe
  style={{ width: '100%', height: '100vh', border: 0 }}
  src="https://pay.breeze.cash/page_xxx/pcs_xxx"
  allow="payment pay.breeze.cash"
/>

3. Users complete payment within the embedded iframe
4. Your application validates the payment page status to your backend server
5. Your application handles the success or failure states appropriately on your frontend

Enabling Apple Pay on an embedded iframe

To enable Apple Pay for iframe usage, please email [email protected] for the merchant domain certification to allow Apple Pay to be enabled when the iframe is hosted on your domain

Steps to be completed:

• Adding the domain certification
• Send a post message to the iframe to allow cross-domain payments

Adding the domain certification

When you receive the domain certification from our support, you have to host it on your domain at the path {YOUR_DOMAIN}/.well-known/apple-developer-merchantid-domain-association.txt

If you are using Vite, you can simply add the textfile under /public folder.

You can validate this by simply visiting {YOUR_DOMAIN}/.well-known/apple-developer-merchantid-domain-association.txt on the URL.

Send a post message to the iframe to allow cross-domain payments

Due to restrictions on Apple Pay, we have to explicitly specify the parent-level domain (in this case your domain) before we can proceed with an Apple Pay payment.

You can do this by sending a cross-domain message to the iframe as shown below by specifying the host.

const iframe = document.querySelector("iframe");
if (iframe && iframe.contentWindow) {
    iframe.contentWindow.postMessage({
            type: "request-global-config",
            config: {
                applePayEnabled: true,
                crossDomainName: location.host,
            },
        },
        "*"
    );
}