ℹ️

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 *; camera *; accelerometer *; gyroscope *; microphone *" is enabled on the iframe. Also ensure you add the query parameter ?cross_domain_name=[merchant-domain-here] to the src url as seen below.

<iframe
  id="breeze-payment-page"
  src="https://pay.breeze.cash/page_xxx/pcs_xxx?cross_domain_name=[merchant-domain-here]"
  style={{ width: '100%', height: '100vh', border: 0 }}
  allow="payment *; camera *; accelerometer *; gyroscope *; microphone *"
/>

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.

Sending the configuration via postMessage

When the Breeze iframe loads, it posts a request-global-config message to the parent window. Your page must respond with the Apple Pay flag and your certified domain name.

Add the following listener to your page before the iframe loads:

window.addEventListener('message', function (event) {
  if (event.data.type === 'request-global-config') {
    event.source.postMessage(
      {
        type: 'request-global-config',
        config: {
          applePayEnabled: true,
          crossDomainName: 'yourdomain.com', // without https://
        },
      },
      '*'
    );
  }
});

Note: crossDomainName must exactly match the domain you submitted to Breeze support for certification — without the https:// prefix (e.g. yourdomain.com, not https://yourdomain.com).

You can also pass a theme object to apply brand colors dynamically:

config: {
  applePayEnabled: true,
  crossDomainName: 'yourdomain.com',
  theme: {
    primaryColor: '#1a56db',
  },
}

Tip: The cross_domain_name query parameter already present on the iframe src URL (shown in the How It Works section) is also sufficient to enable Apple Pay — the iframe reads it on load and sets applePayEnabled: true automatically. The postMessage approach is only needed when you also want to pass theme configuration dynamically.