Skip to main content

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 a v iframe sú dostupné všetky platobné metódy. Pri Apple Pay a väčšine ostatných metód (napr. platobných tlačidiel) však z bezpečnostných dôvodov dôjde k presmerovaniu platiteľa mimo iframe na novú stránku.

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. 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. Brána sama rozpozná, že je zobrazená v iframe, pri založení platby preto nie je potrebný žiadny ďalší parameter.

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í.

Upozornenie

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>
Nebezpečenstvo

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

Platbu cez Apple Pay nie je možné dokončiť priamo v iframe. Po kliknutí na Apple Pay brána presmeruje celú stránku (hlavné okno prehliadača) na platobnú bránu, kde platiteľ platbu dokončí.

Ak prehliadač presmerovanie hlavného okna z iframe zablokuje (napr. pri iframe s atribútom sandbox bez hodnoty allow-top-navigation), zobrazí sa hláška:

We are unable to redirect you due to your browser's security settings, please choose a different payment method

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 alebo odovzdaná pri založení platby (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.

Upozornenie

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 (alebo mu namiesto toho zobrazí stránku so stavom platby), odošle rodičovi iframe (vášmu e-shopu) javascriptovú správu o stave platby.

Upozornenie

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). Bez čakania na odovzdanie stavu sa správa odošle napríklad vtedy, keď zákazník klikne na tlačidlo pre návrat do e-shopu alebo keď sa odovzdanie stavu nepodarí.

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.

Upozornenie

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
            // refId = ID objednávky od klienta
            // status = stav platby
            const { id, 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 platobných metód dostupných pre danú platbu.

Pokiaľ platiteľ v akomkoľvek kroku platobného procesu zvolí metódu, ktorú nie je možné dokončiť v iframe (napr. platobné tlačidlo alebo Apple Pay), 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. Ak bola taká metóda určená už pri založení platby, zobrazí brána pred presmerovaním tlačidlo „Pokračovať“, aby k vyskočeniu z iframe došlo až po kliknutí platiteľa.

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 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&nbsp;iframe</h1>
    </div>
    <div id="comgate-iframe-box">
        <!--
            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">
        </iframe>
    </div>
</div>
</body>
</html>
Sekvenční diagram