Platobná brána v e-shope
Pre integráciu platobnej brány priamo do e-shopu odporúčame použiť Web Checkout SDK. SDK umožňuje prijímať platby kartou, platby prostredníctvom Google Pay a Apple Pay priamo na stránke vášho e-shopu — bez nutnosti presmerovania zákazníka na platobnú bránu. Zabezpečuje bezpečné zadávanie kartových údajov v izolovanom iframe, plnú podporu 3D Secure a súlad s PCI-DSS.
Alternatívna integrácia cez iframe
Ak nechcete alebo nemôžete využiť Web Checkout SDK, je možné platobnú bránu zobraziť v iframe priamo na stránke vášho e-shopu. Tento prístup je jednoduchší na implementáciu, ale ponúka obmedzenejšie možnosti — v iframe funguje iba platba kartou a QR kód. Ostatné platobné metódy vyžadujú presmerovanie na novú stránku z dôvodu bezpečnosti.
Zobrazenie platobnej brány v iframe
Platobná brána umožňuje zobrazenie optimalizované pre iframe. Táto funkcia je vhodná v prípade, že nechcete platiteľa presmerovávať na platobnú bránu, ale zobraziť ju v rámci svojho systému. Aby sa platobná brána zobrazila v iframe, je potrebné pri založení platby použiť parameter „embedded“ = true. Platobné URL je vygenerované štandardným spôsobom, ale namiesto presmerovania zákazníka na bránu sa zobrazí na stránke e-shopu iframe s platobnou URL.
Na zobrazenie sú dve možnosti. Platobnú bránu je možné zobraziť buď priamo v košíku, alebo vo vyskakovacom okne nad vašou webovou stránkou. Implementácia iframu vyžaduje znalosť webových technológií. Iframe je možné použiť len pre platbu kartou a QR kód. Pri ostatných platobných metód dôjde vždy k presmerovanie platiteľa na novú stránku z dôvodu bezpečnosti.
V prípade, že na svojom webe používate hlavičku Content-Security-Policy, je potrebné povoliť všetky externé kontexty v iframe. O tejto konfigurácii píšeme v sekcii Zabezpečenie.
Pre správne zobrazenie platobnej brány v iframe na webovej stránke odporúčame vykonať nasledujúcu úpravu vašich webových stránok.
Nastavenie zobrazenia platobnej brány
HTML kód
<div id="comgate-container">
<!-- Atribút allow=payment je pre zobrazenie brány v iframe nevyhnutný -->
<iframe id='comgate-iframe' allow="payment" src="[platobná URL]" frameborder="0px"></iframe>
</div>
Pre zobrazenie platobnej brány v rámci iframe je nevyhnutné uviesť atribút allow="payment". Bez použitia tohto atribútu nie je garantované, že bude platobná brána fungovať správne.
CSS štýly
#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;
}
}
Javascriptový kód
// funkcia na otvorenie iframe s bránou
function comgateOpen() {
var comgate_container = document.getElementById("comgate-container");
comgate_container.style.display = "block";
}
// funkcia na zatvorenie iframe s bránou
function comgateClose() {
var comgate_container = document.getElementById("comgate-container");
comgate_container.style.display = "none";
// bude odstránené z DOM - už nepôjde zobraziť znova pomocou comgateOpen
// let comgate_iframe = document.getElementById("comgate-iframe");
// comgate_iframe.remove();
}
Na zobrazenie iframe je potrebné vyvolať funkciu comgateOpen (). Napríklad nadviazaním na akciu užívateľa (kliknutie na tlačidlo a pod.). Funkcia comgateClose () potom slúži na prípadné skrytie iframe.
Príklad vyvolania funkcie na zobrazenie iframe kliknutím na tlačidlo „Zaplatiť“:
HTML kód
<button id="comgate-open" onclick="comgateOpen()">Zaplatit</button>
ApplePay v iframe
V niektorých prípadoch nie je možné dokončiť platbu cez Apple Pay z iframe, pretože prehliadač z bezpečnostných dôvodov zablokuje presmerovanie hlavného okna z cross-origin iframe.
V takom prípade sa môže zobraziť nasledujúca hláška:
We are unable to redirect you due to your browser's security settings, please choose a different payment method.
Toto správanie závisí od nastavenia konkrétneho prehliadača.
Presmerovanie zákazníka po dokončení platby
Po dokončení platby zákazníkom dochádza (iba v čase do 1 hodiny od založenia) k jeho automatickému presmerovaniu do e-shopu na URL, ktorá bola nastavená v klientskom portáli (do 5 minút od založenia platby je vybavených viac než 97 % platieb).
Odporúčame vykonať jednu z nasledujúcich úprav, ktorá zaistí, že zákazník bude presmerovaný priamo na návratovú URL a nezostane tak vnútri iframe.
1. Presmerovanie vonkajšej stránky na vami určenú URL
Týmto dôjde k obnoveniu celej stránky a zákazník neuviazne v iframe otvorenom na stránke. Dnes už však nejde o odporúčaný spôsob.
Javascriptový kód pre vnútornú stránku
window.top.location = window.self.location
2. Zaslanie vlastnej správy z iframe na svoju vonkajšiu stránku
Potom čo zákazníka presmerujeme do e-shopu, je v iframe duplicitne zobrazená stránka vášho e-shopu. Z tejto stránky vnútri iframe si môžete poslať jednoduchú javascriptovú správu svojej vonkajšej stránke a v nej ju spracovať. Nemusí teda dôjsť k obnoveniu celej stránky.
Skutočný výsledok platby, ktorý nedorazil pomocou push notifikácie, je vždy potrebné overiť štandardným spôsobom na našom API. Z bezpečnostných dôvodov sa nemožno spoliehať na výsledok odovzdaný správou z iframe alebo v URL pri presmerovaní (informácia môže byť ľahko podvrhnutá).
Javascriptový kód pre vnútornú stránku, ktorý pošle vonkajšej stránke správu s ID platby a stavom platby, napr. pre zaplatenú platbu:
// ID platby získate z URL adresy, na ktorú je zákazník presmerovaný po dokončení platby
// východiskové parametre URL: id=${id}&refId=${refId} (možno si pridať vlastný parameter s pevnou hodnotou očakávaného stavu)
// viac informácií viď prepojenie obchodu v klientskom portáli
window.parent.postMessage({ id: 'id-platby', status: 'PAID' /* refId, ... */ }, '*');
Javascriptový kód pre vonkajšiu stránku, ktorý spracuje prichádzajúcu správu z iframe:
// odchytenie správy poslanej z iframe pomocou postMessage
if (window.addEventListener) {
window.addEventListener('message', function (e) {
// validácia, že message obsahuje dáta
if (!e || !(e !== null && e !== void 0 && e.data)) return;
const { id, status /* refId, ... */ } = e.data;
if (['PAID', 'AUTHORIZED'].includes(status)) {
// obslúženie stavu PAID / AUTHORIZED
console.log(id)
} else {
// obslúženie ďalších stavov, atď ...
}
}, false);
}
3. Počúvanie správ zasielaných priamo bránou Comgate
Po dokončení platby zákazníkom (PAID, AUTHORIZED, CANCELLED) sa platobná brána pokúsi odovzdať informáciu o stave platby na server obchodníka (push). Následne, bezprostredne pred tým, než zákazníka presmeruje späť do e-shopu, odošle rodičovi iframe (vášmu e-shopu) javascriptovú správu o stave platby.
Nie je garantované, že je táto javascriptová správa odoslaná až potom, čo dôjde k úspešnému odovzdaniu stavu platby na pozadí (push). Typicky môže k predčasnému odoslaniu tejto správy dochádzať po uplynutí 1 hodiny od založenia platby.
Potom čo vaša stránka prijme správu od našej brány v iframe, mal by byť iframe skrytý. Ak si neprajete, aby dochádzalo k duplicitnému načítaniu vašej stránky priamo v iframe, je potrebné iframe zo stránky (DOM) odobrať (na to nie je možné použiť css štýly display: none, visible: hidden alebo ďalšie). Všetky informácie o stave platieb by mali byť overované cez váš server. Ten by si mal v prípade, že ešte nedorazila push notifikácia o stave platby, túto skutočnosť overiť priamo na našom API.
Skutočný výsledok platby, ktorý nedorazil pomocou push notifikácie, je vždy potrebné overiť štandardným spôsobom na našom API. Z bezpečnostných dôvodov sa nemožno spoliehať na výsledok odovzdaný správou z iframe alebo v URL pri presmerovaní (informácia môže byť ľahko podvrhnutá).
Javascriptový kód pre vašu stránku, ktorý spracuje prichádzajúcu správu z iframe od brány Comgate:
// odchytenie správy poslanej z iframe pomocou postMessage
if (window.addEventListener) {
window.addEventListener('message', function (e) {
// validácia, že message obsahuje dáta
if (!e || !(e !== null && e !== void 0 && e.data)) return;
// načítanie dát zo správy
const { scope, action, value } = e.data;
// vyhodnotenie, že je správa od Comgate a je určená e-shopu
// súčasne kontrola, že ide o informáciu o stave platby
// a hodnota je platná
if (scope === 'comgate-to-eshop' && action === 'status' && value) {
// id = XXXX-XXXX-XXXX
// isTest = true/false (testovacia platba)
// refId = ID objednávky od klienta
// status = stav platby
const { id, isTest, refId, status } = value;
if (['PAID', 'AUTHORIZED'].includes(status)) {
// obslúženie stavu PAID/AUTHORIZED - zaplatené/predautorizované
} else if (status === 'CANCELLED') {
// obslúženie stavu CANCELLED - nezaplatené
} else {
// obslúženie ďalších stavov, atď (veľmi krajný prípad) ...
// PENDING, UNKNOWN
}
}
}, false);
}
Platobná brána v iframe z pohľadu platiteľa
Platobná brána Comgate umožňuje užívateľom opakovať platbu, ak sa im ju nepodarilo dokončiť naprvýkrát. Pre ďalší pokus je zobrazený výber všetkých platobných metód.
Pokiaľ dôjde v akomkoľvek kroku platobného procesu k vybratiu inej metódy než platby kartou, dôjde k presmerovaniu platiteľa na novú stránku a tzv. vyskočeniu z iframe. Užívateľ sa už späť do iframe nevráti.
Vzor pre zobrazenie brány v e-shope
Pre jednoduchú implementáciu našej platobnej brány do vášho e-shopu môžete využiť nižšie dostupné vzorové implementácie.
HTML kód
<!doctype html>
<html lang="sk">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Comgate :: práca s 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; /* šírka je pomocou media automaticky nastavená na 100 % šírky obrazovky v prípade malého displeja */
height: 700px; /* výšku je pre novú bránu možné dynamicky prispôsobiť vašim potrebám */
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>Ukážka práce s iframe</h1>
</div>
<div id="comgate-iframe-box">
<!--
V konfigurácii iframe:
pre novú bránu použiť scrolling="off"
pre starú bránu použiť scrolling="on"
Pozor: URL adresa (src) založenej platby sa môže meniť.
Vždy použite adresu, ktorú vám vráti API, a nijako do nej nezasahujte.
Atribút allow=payment je pre zobrazenie brány v iframe nevyhnutný
-->
<iframe
class="iframe"
src="https://pay2.comgate.cz/init?id=XXXX-XXXX-XXXX"
allow="payment"
frameborder="0px"
scrolling="off">
</iframe>
</div>
</div>
</body>
</html>
