Payment gateway in the e-shop
For integrating the payment gateway directly into your online store, we recommend using the Web Checkout SDK. The SDK enables card payments, Google Pay payments and Apple Pay payments to be accepted directly on your online store’s page — without requiring the customer to be redirected to the payment gateway. It provides secure entry of card details in an isolated iframe, full 3D Secure support and PCI-DSS compliance.
Alternative integration via iframe
If you do not want to or cannot use the Web Checkout SDK, the payment gateway can be displayed in an iframe directly on your online store’s page. This approach is simpler to implement, but offers more limited options — only card payment and QR code work in the iframe. Other payment methods require redirection to a new page for security reasons.
Displaying the payment gateway in an iframe
The payment gateway allows display optimized for iframe. This functionality is suitable in case you do not want to redirect the payer to the payment gateway, but display it within your system. To display the payment gateway in an iframe, you need to use the "embedded" = true parameter when creating the payment. The payment URL is generated in the standard way, but instead of redirecting the customer to the gateway, an iframe with the payment URL is displayed on the e-shop page.
There are two display options. Either you can display the payment gateway directly in the cart or using a pop-up window over your website. Implementing an iframe requires knowledge of web technologies. Iframe can only be used for card payment and QR code. For other payment methods, the payer will always be redirected to a new page for security reasons.
If you are using the Content-Security-Policy header on your website, it is necessary to allow all external contexts in iframes. We discuss this configuration in the Security section.
For the correct display of the payment gateway in an iframe on the web page, we recommend making the following modification to your web pages.
Setting the display of the payment gateway
HTML code
<div id="comgate-container">
<!-- The allow=payment attribute is necessary for displaying the gateway in an iframe -->
<iframe id='comgate-iframe' allow="payment" src="[payment URL]" frameborder="0px"></iframe>
</div>
To display the payment gateway inside an iframe it is necessary to specify the allow="payment" attribute. Without this attribute there is no guarantee that the payment gateway will work correctly.
CSS styles
#comgate-container {
display: none;
position:absolute;
z-index: 9999;
left: 50%;
top: 30px;
overflow: auto;
margin-left: -250px;
}
#comgate-iframe {
width: 504px;
height: 679px;
}
@media (max-height: 700px) {
#comgate-iframe {
top: 0px;
}
}
JavaScript code
// function to open iframe with gateway
function comgateOpen() {
let comgate_container = document.getElementById("comgate-container");
comgate_container.style.display = "block";
}
// function to close iframe with gateway
function comgateClose() {
let comgate_container = document.getElementById("comgate-container");
comgate_container.style.display = "none";
// will be removed from the DOM - it will no longer be possible to show it again using comgateOpen
// let comgate_iframe = document.getElementById("comgate-iframe");
// comgate_iframe.remove();
}
To display the iframe, you need to call the comgateOpen() function. For example, by binding to a user action (clicking a button, etc.). The comgateClose() function then serves to possibly hide the iframe.
Example of calling the function to display the iframe by clicking the "Pay" button:
HTML code
<button id="comgate-open" onclick="comgateOpen()">Pay</button>
ApplePay in the iframe
In certain cases, it is not possible to complete an Apple Pay payment from within an iframe because the browser blocks the redirection of the main window from a cross-origin iframe for security reasons.
In such cases, the following message may be displayed:
We are unable to redirect you due to your browser's security settings, please choose a different payment method.
This behavior depends on the settings of the specific browser.
Redirecting the customer after completing the payment
After the payment is completed by the customer, they are automatically redirected to the e-shop (only within 1 hour of the payment being created) to the URL that was set in the Client Portal (more than 97 % of payments are settled within 5 minutes of being created).
We recommend performing one of the following modifications, which will ensure that the customer is redirected directly to the return URL and does not stay inside the iframe.
1. Redirecting the external page to the URL you specified
This refreshes the entire page and the customer does not get stuck in the iframe opened on the page. Today, however, this is no longer the recommended approach.
Javascript code for the internal page
window.top.location = window.self.location
2. Sending your own message from the iframe to your external page
After we redirect the customer to the e-shop, your e-shop page is displayed a second time inside the iframe. From this page inside the iframe you can send a simple javascript message to your external page and process it there. The entire page therefore does not have to be refreshed.
The actual payment result that has not arrived via a push notification must always be verified in the standard way through our API. For security reasons, you cannot rely on the result passed by a message from the iframe or in the URL during redirection (the information can easily be forged).
Javascript code for the internal page, which sends the external page a message with the payment ID and payment status, e.g., for a paid payment:
// You get the payment ID from the URL the customer is redirected to after completing the payment
// default URL parameters: id=${id}&refId=${refId} (you can add your own parameter with a fixed value of the expected status)
// for more information see the e-shop connection in the Client Portal
window.parent.postMessage({ id: 'payment-id', status: 'PAID' /* refId, ... */ }, '*');
Javascript code for the external page, which processes the incoming message from the iframe:
// capture a message sent from the iframe using postMessage
if (window.addEventListener) {
window.addEventListener('message', function (e) {
// validate that the message contains data
if (!e || !(e !== null && e !== void 0 && e.data)) return;
const { id, status /* refId, ... */ } = e.data;
if (['PAID', 'AUTHORIZED'].includes(status)) {
// handling the PAID / AUTHORIZED state
console.log(id)
} else {
// handling other states, etc ...
}
}, false);
}
3. Listening to messages sent directly by the Comgate gateway
After the customer completes the payment (PAID, AUTHORIZED, CANCELLED), the payment gateway attempts to pass the information about the payment status to the merchant's server (push). Then, immediately before redirecting the customer back to the e-shop, it sends a javascript message about the payment status to the parent of the iframe (your e-shop).
There is no guarantee that this javascript message is sent only after the payment status has been successfully passed in the background (push). Typically, this message may be sent prematurely after 1 hour has elapsed since the payment was created.
Once your page receives the message from our gateway in the iframe, the iframe should be hidden. If you do not want your page to be loaded a second time directly in the iframe, you need to remove the iframe from the page (the DOM) - the css styles display: none, visible: hidden or others cannot be used for this. All information about payment statuses should be verified through your server. If the push notification about the payment status has not arrived yet, your server should verify this fact directly through our API.
The actual payment result that has not arrived via a push notification must always be verified in the standard way through our API. For security reasons, you cannot rely on the result passed by a message from the iframe or in the URL during redirection (the information can easily be forged).
Javascript code for your page, which processes the incoming message from the iframe sent by the Comgate gateway:
// capture a message sent from the iframe using postMessage
if (window.addEventListener) {
window.addEventListener('message', function (e) {
// validate that the message contains data
if (!e || !(e !== null && e !== void 0 && e.data)) return;
// read the data from the message
const { scope, action, value } = e.data;
// evaluate that the message is from Comgate and is intended for the e-shop
// and at the same time check that it is information about the payment status
// and that the value is valid
if (scope === 'comgate-to-eshop' && action === 'status' && value) {
// id = XXXX-XXXX-XXXX
// isTest = true/false (test payment)
// refId = order ID from the client
// status = payment status
const { id, isTest, refId, status } = value;
if (['PAID', 'AUTHORIZED'].includes(status)) {
// handling the PAID/AUTHORIZED state - paid/pre-authorized
} else if (status === 'CANCELLED') {
// handling the CANCELLED state - not paid
} else {
// handling other states, etc (a very rare case) ...
// PENDING, UNKNOWN
}
}
}, false);
}
Payment gateway in the iframe from the payer's perspective
The Comgate payment gateway allows users to repeat the payment if they failed to complete it the first time. For the next attempt, a selection of all payment methods is displayed.
If a method other than card payment is chosen at any step of the payment process, the payer is redirected to a new page and thus jumps out of the iframe. The user will not return to the iframe.
Template for displaying the gateway in the e-shop
For easy implementation of our payment gateway into your e-shop, you can use the available template implementations below.
HTML code
<!doctype html>
<html lang="cs">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Comgate :: working with iframe</title>
<style>
body,html {
background: #fff;
padding:0;
margin:0;
width: 100%;
height: 100%;
}
.page {
width: 100%;
background: #eee;
margin: 0 auto;
max-width: 800px;
}
.page .header h1 {
text-align: center;
margin: 0;
padding: 25px 15px;
font-size: 25px;
}
#comgate-iframe-box {
width: 450px; /* width is set automatically to 100% of screen width for small displays */
height: 700px; /* for the new gateway, you can dynamically adjust the height according to your needs */
margin: 0 auto;
}
#comgate-iframe-box .iframe {
width: 100%;
height: 100%;
}
@media (max-width: 450px) {
#comgate-iframe-box {
width: 100%;
}
}
</style>
</head>
<body>
<div class="page">
<div class="header">
<h1>Demonstration of working with iframe</h1>
</div>
<div id="comgate-iframe-box">
<!--
In iframe configuration:
use scrolling="off" for the new gateway
use scrolling="on" for the old gateway
Note: The URL address (src) of the established payment can change.
Always use the address returned by the API, and do not interfere with it.
-->
<iframe
class="iframe"
src="https://pay2.comgate.cz/init?id=XXXX-XXXX-XXXX"
allow="payment"
frameborder="0px"
scrolling="off">
</iframe>
</div>
</div>
</body>
</html>
