ℹ️
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

Your application creates a payment session on your backend server
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.
cross_domain_name here should be the domain of the parent domain embedding the iframe, for example xyz.com (without the https://)

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

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

Enabling Google Pay on an embedded iframe

Google Pay relies on the browser's Payment Request API to invoke the native wallet drawer. When this API is unavailable inside the iframe, Google Pay silently falls back to a degraded PAN_ONLY flow instead of producing a network token (CRYPTOGRAM_3DS). This results in all Google Pay transactions being treated as manually-keyed card numbers (FPAN) rather than tokenized cards (DPAN), which reduces authorization rates and loses the liability shift that tokenized payments provide.

To enable the full Google Pay flow, two attributes are required on the iframe:

allow="payment ..." — grants the Permissions Policy for payment handling (already shown in the example above).
If you set a sandbox attribute on the iframe, you must also include allow-payment-request. The sandbox attribute blocks the Payment Request API by default, so without this value the native Google Pay drawer can never be rendered.

⚠️
If you are not setting a sandbox attribute at all, no extra configuration is needed — the Payment Request API is allowed by default. Only add allow-payment-request when a sandbox attribute is already present.

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

How to verify:

On desktop Chrome, inspect the embedded iframe element and confirm both allow="payment ..." and (if sandbox is set) allow-payment-request are present.
On an Android device with a card enrolled for contactless payment in the Google Wallet app, complete a test Google Pay transaction and confirm it is processed as CRYPTOGRAM_3DS (DPAN) rather than PAN_ONLY (FPAN).

📘
Once the iframe is correctly configured, the FPAN/DPAN split is determined entirely by the issuer — specifically whether each user's card has been enrolled in network tokenization (Visa Token Service / Mastercard MDES) by their bank. This is outside the merchant's and Breeze's control.

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
Ensure cross_domain_name is passed as a query parameter in the URL

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.

Placing it in the public folder for Vite

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