Obsah x
Protokol API
Obsah

Protokol API

Špecifikácie HTTP POST

Prepojenie medzi e-shopom a platobnou bránou Comgate je realizované pomocou presmerovania platiteľa z e-shopu na platobnú bránu. Po vykonaní platby je platca presmerovaný späť do e-shopu. Zároveň na pozadí prebieha komunikácia medzi serverom e-shopu a serverom platobnej brány (server - server). Detailný opis komunikačného protokolu nájdete nižšie na tejto stránke. Ďalšie súvisiace informácie nájdete na stránkach, ktoré opisujú proces platby z pohľadu užívateľa a e-shopu, počiatočné nastavenie v klientskom portáli, odporúčaný spôsob testovania integrácie platobnej brány alebo detailný opis napojenia na EET.

Ukážková implementácia v jazyku PHP na stiahnutie tu.

Priebeh platby

Založenie platby – voliteľné

Krok založenia platby je voliteľný, je však vhodné ho implementovať v prípade, keď požadujete istotu zabezpečeného založenia platby. Vynechanie implementácie tohto kroku je možné v prípade, kedy jednotlivé platby nepotrebujete v systéme identifikovať, ale stačí vám informácia, že vám niekto zaplatil určitú čiastku. 

Je to vhodné napríklad pri implementácii darcovských príspevkov alebo dobíjaní prostriedkov na virtuálny účet zákazníka, kedy vás zaujíma len to, kto dobíja a akú sumu, ale nepotrebujete rozlišovať jednotlivé dobitie zákazníka alebo obmedziť dobitie na minimálnu čiastku atď. Pre klasický e-shop, kde platíte za konkrétny tovar, je však vynechanie tohto kroku nevhodné.

Platbu e-shopu zakladá HTTP požiadavkou na server platobnej brány. Parametre platby, vrátane unikátneho referenčného čísla platby, sú odovzdané ako POST parametre HTTP protokolu. Táto komunikácia prebieha medzi serverom Klienta a serverom platobnej brány. Platiteľ ju nevidí a nemôže meniť parametre platby. Server platobnej brány vráti Klientovi unikátny identifikátor transaction ID (identifikátor v Comgate platobnom systéme) a URL adresu, na ktorú má presmerovať Platiteľ.

Príklad založenia platby na pozadí - HTTP request:

curl -X POST -i --data "merchant=123456&price=10000&curr=CZK&label=Beatles%20-0%Help&refId=2010102600&method=ALL&prepareOnly=true&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y" https://payments.comgate.cz/v1.0/create

Príklad založenia platby na pozadí - HTTP response:

HTTP/2 200 OK
content-type: application/x-www-form-urlencoded; charset=UTF-8
code=0&message=OK&transId=AB12-CD34-EF56&redirect=https%3A%2F%2Fpayments.comgate.cz%2Fclient%2Finstructions%2Findex%3Fid%3DAB12-CD34-EF56 

Komunikácia medzi systémom Klienta a platobnou bránou je zabezpečená pomocou hesla a IP whitelistu (prístup je povolený len z IP adries systému Klienta). Nevyhnutné je použitie protokolu HTTPS, ktorý znemožňuje prezradenie hesla pri prípadnom odpočúvaní komunikácie. Heslo je odovzdávané ako POST parameter (nie GET parameter) preto, aby sa neukladalo v logu komunikácie webového servera.

Presmerovanie na platobnú bránu

Po založení platby na pozadí dostane e-shop platobné URL na zobrazenie platobnej brány. Platobná brána môže byť zobrazená dvoma spôsobmi. Prvým spôsobom je presmerovanie platiteľa na adresu, ktorú dostal e-shop v HTTP odpovedi. Presmerovanie sa zvyčajne vykonáva odoslaním HTTP odpovede 302:

HTTP odpoveď 302

HTTP/2 302 Found
Location: https://payments.comgate.cz/client/instructions/index?id=AB12-CD34-EF56 

Druhou možnosťou je zobrazenie platobnej brány priamo na stránke e-shopu pomocou iframe. Pre tento variant je potrebné vygenerovať platobné URL štandardným spôsobom, ale namiesto presmerovania zákazníka na bránu sa zobrazí na stránke e-shopu iframe s platobnou URL.

V prípade vynechania prvého kroku založenia platby na pozadí je platba založená až pri presmerovaní Platiteľa z webu Klienta na server platobnej brány alebo odoslaní webového formulára z webu Klienta na server platobnej brány. Parametre platby, vrátane unikátneho referenčného čísla platby, sú odovzdané ako GET alebo POST parametre HTTP protokolu.

Príklad založenia platby presmerovaním (odoslaním webového formulára) - HTTP request

curl -X POST -i --data "merchant=123456&price=10000&curr=CZK&label=Beatles%20-20Help&refId=2010102600&method=ALL" https://payments.comgate.cz/v1.0/create

Odovzdanie výsledku platby na pozadí

Implementácia tejto časti vám zaistí automatické odovzdanie informácie o stave každej platobnej transakcie priamo na váš server v okamihu, keď je stav platby známy. Odovzdávanie výsledku platby na pozadí je povinné.

Výsledok platby je Klientovi odovzdaný HTTP požiadavkou zo servera platobnej brány na server Klienta. Identifikátory a výsledok platby sú odovzdané ako POST parametre HTTP protokolu. Táto komunikácia sa uskutočňuje na pozadí.

Platiteľ je presmerovaný na webové stránky Klienta a identifikátory platby sú odovzdané ako GET parametre HTTP protokolu. Odoslanie tovaru alebo služby Platiteľa musí byť viazané na odovzdanie výsledku platby na pozadí, nie na výsledné presmerovanie Platiteľa na webové stránky Klienta, pretože informácie zaslané presmerovaním môže Platiteľ ľahko podstrčiť.

Príklad odovzdania výsledku platby na pozadí - HTTP request

curl -X POST -i --data "merchant=merchant_com&test=false&price=10000&curr=CZK&label=Beatles%20-%20Help&refId=2010102600&method=CARD&email=info%40customer.com&phone=%2B420123456789&transId=AB12-EF34-IJ56&secret=ZXhhbXBsZS5jb206QUJDeHl6&status=PAID" https://example.com/handler.php

Príklad odovzdania výsledku platby na pozadí - HTTP response

HTTP/2 200 OK 
content-type: application/x-www-form-urlencoded; charset=UTF-8

Komunikácia medzi systémom Klienta a serverom platobnej brány je zabezpečená pomocou hesla a IP whitelistu. Prístup musí byť povolený iba z IP adresy servera platobnej brány. Rozsahy IP adries sú definované v sekcii Zabezpečenie. Je povinné použiť protokol HTTPS, ktorý znemožňuje prezradenia hesla pri prípadnom odpočúvaní komunikácie. Heslo je odovzdávané ako POST parameter (nie GET parameter) preto, aby sa neukladalo v logu komunikácie webového servera.

E-shop na svojej strane zabezpečí, že tovar (služba) poskytnutý v rámci zaplatenej transakcie (identifikovanej pomocou unikátneho transaction ID) bude vydaný Platiteľom iba raz (aj pri opakovanom odovzdaní výsledku rovnakej platby na server Klienta).

Presmerovanie Platiteľa na web Klienta

Platiteľ je na základe stavu platby presmerovaný na jedno z troch URL, ktoré e-shop zvolil pri aktivácii služby. Identifikátory platby sú odovzdané ako GET parametre HTTP protokolu. Systém klienta musí byť schopný ošetriť dve základné situácie:

  • Pri presmerovaní platiteľa na web klienta výsledok platby ešte nie je známy. Platba je v stave PENDING. Táto situácia je úplne bežná a e-shop ju nesmie platiteľovi prezentovať ako chybu. Systém čaká buď na pripísanie platby na bankový účet alebo na potvrdenie od poskytovateľa platby. Konečný výsledok platby sa e-shop dozvie neskôr buď odovzdaním výsledku platby na pozadí alebo e-mailom alebo na klientskom portáli.
  • Ak sa platobná brána dozvie výsledok platby okamžite po uskutočnení platby platiteľom, potom je platiteľ smerovaný na príslušné URL (PAID alebo CANCELLED). Ak e-shop implementoval odovzdávanie výsledku platby na pozadí, potom sa presmerovanie na web Klienta vykoná až po úspešnom odovzdaní výsledku platby na pozadí. Platiteľovi nemožno odoslať tovar alebo službu, ktorú objednal, iba na základe URL použitej na presmerovanie, pretože platiteľ by mohol výsledok platby podstrčiť zmenou URL vo webovom prehliadači.

Príklad presmerovania Platiteľa na web Klienta - HTTP request

GET /result_ok.php?refId=2010102600&transId=AB12-EF34-IJ56 HTTP/2
Host: eshop.com

Platobná brána v e-shope (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. Jednak je možné platobnú bránu zobraziť priamo v košíku alebo pomocou vyskakovacieho okna 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. Pri ostatných platobných metód dôjde vždy k presmerovanie platiteľa na novú stránku.

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">
    <iframe id='comgate-iframe' src ="[platební URL]" frameborder="0px"></iframe>
</div>

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

// funkce pro otevření iframu s bránou
function comgateOpen() {
    var comgate_container = document.getElementById("comgate-container");
    comgate_container.style.display = "block";
}
// funkce pro zavření iframu s bránou
function comgateClose() {
    var comgate_container = document.getElementById("comgate-container");
    comgate_container.style.display = "none";
}

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>

Presmerovanie zákazníka po dokončení platby

Po dokončení platby zákazníkom dochádza k jeho presmerovaniu do e-shopu na URL, ktorú ste nastavili na klientskom portáli. 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.

Prvou možnosťou je presmerovať vonkajšiu stránku na vami určenú URL. Tým dôjde k obnoveniu celej stránky.

Javascriptový kód pre vnútornú stránku

window.top.location = window.self.location

Druhou možnosťou je zo stránky vnútri iframe poslať správu vonkajšej stránke a na vonkajšej strane túto udalosť spracovať. Nemusí teda dôjsť k obnoveniu celej stránky.

Pozor, skutočný výsledok platby je potrebné získať na pozadí štandardným spôsobom. Z bezpečnostných dôvodov nie je možné spoliehať na výsledok odovzdaný správou z iframe.

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:

window.parent.postMessage('[id platby]|PAID', '*');

Javascriptový kód pre vonkajšiu stránku, ktorý spracuje prichádzajúcu správu z iframe:

// odchycení zprávy poslané z iframu pomocí postMessage
    if (window.addEventListener ){
        window.addEventListener('message', function (e) {
            // přijde mi id a výsledek platby, oddělovač je “roura”
            let message = e.data.split('|', 2);
            let message_id =  message[0];
            let message_result =  message[1];
            let result = '';
            if (message_result === 'PAID') {
    // obsloužení stavu PAID
    [...]
            } else {
    // obsloužení dalších stavů, atd ...
    [...]
            }
        }, false);

Platobná brána v iframe z pohľadu platcuIframe

Platobná brána Comgate umožňuje užívateľom opakovať platbu, ak sa im nepodarilo dokončiť platbu na prvýkrát. Zobrazenie platobnej brány v iframe užívateľovi je závislé od zvolenej platobnej metódy a tiež, či sa výber platobných metód nachádza na strane e-shopu alebo na strane Comgate.

V prípade, že je výber platobných metód na strane e-shopu a platba je tak založená už s platobnou metódou, musí byť na zobrazenie iframe zvolená metóda platby kartou. Ak sa užívateľovi nepodarilo platbu na prvýkrát dokončiť, pre ďalší pokus sa mu opäť zobrazí iba metóda platby kartou. Táto verzia je odporúčaná.

V prípade, že e-shop nezakladá platbu s už vybranou platobnou metódou, užívateľovi sa v iframe zobrazí výber platobných metód. Tu je následne potrebné zvoliť platbu kartou. Ak sa užívateľovi nepodarilo platbu dokončiť, pre ďalší pokus sa mu opäť zobrazí výber platobných metód v iframe.

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. Užívateľ sa už späť do iframe nevráti.

Stavy platieb

  • PENDING – platba bola založená, finálny výsledok platby zatiaľ nie je známy.
  • PAID – platiteľ úspešne dokončil platbu - je možné vydať tovar, resp. sprístupniť službu.
  • CANCELLED – platba nebola zaplatená, tovar nebude vydaný, resp. služba nebude poskytnutá.

Platbu možno považovať za zaplatenú iba v stave PAID. Stav PENDING nie je koncový a môže po ňom nasledovať stav CANCELLED.

Stavy plateb

API protokol - platobná brána Comgate

Zabezpečenie

Komunikácia medzi Comgate platobným systémom a e-shopom sa uskutočňuje troma spôsobmi.

  • Serverová časť e-shopového riešenia sa ako klient pripojí k serverovej časti platobnej brány a vyvolá metódy na založenie platby, získanie stavu platby na pozadí, potvrdenie predautorizácie, zrušenie predautorizácie a získanie zoznamu platobných metód. 
  • Serverová časť platobnej brány sa ako klient pripojí k serverovej časti e-shopového riešenia a vyvolá metódu na odovzdanie výsledku platby na pozadí.
  • Prehliadač platiteľa (používateľa) je presmerovaný z e-shopu na platobnú bránu a následne z platobnej brány späť do e-shopu.

Vo všetkých troch prípadoch je nevyhnutné použitie šifrovaného protokolu HTTPS. Platobná brána podporuje iba bezpečné nastavenie TLS / SSL protokolu s nasledujúcimi povolenými šiframi: https://github.com/cloudflare/sslconfig/blob/master/conf

V prípade komunikácie server - server je komunikácia zabezpečená pomocou hesla (Secret) a nastavenia IP whitelistu. Nastavenie týchto parametrov je možné vykonať v prostredí klientskeho portálu.

Zakladanie platieb je predradené službe CloudFlare. Zoznam povolených IP adries CloudFlare nájdete tu: https://www.cloudflare.com/ips-v4

Rozsah IP adries používaný systémom Comgate je definovaný ako 89.185.236.55/32. Tento rozsah sa používa iba na odovzdanie výsledku platby na pozadí.

Metódy platobnej brány

Platobné tlačidlá

Zrýchlené bankové prevody (platobné tlačidlá) poskytujeme od všetkých významných bánk v Česku, Poľsku a na Slovensku. Zoznam dostupných bánk nájdete v číselníkoch. V prípade platobných tlačidiel je možné využiť funkcie, ako sú refundácia a storno platby.

Platobné tlačidlo nie je možné zobraziť priamo v e-shope (iframe). Platiteľ je vždy presmerovaný do banky.

Platba kartou

Platobná brána akceptuje platby kartou VISA, VISA Electron, Mastercard, Maestro. Platby sú dostupné v menách EUR, CZK, PLN, HUF, USD, GBP a RON, NOK a SEK. Je k dispozícii v 14 jazykoch - v slovenčine, češtine, angličtine, nemčine, francúzštine, poľštine, maďarčine, chorvátčine, slovinčine, rumunčine, nórčine a švédčine.

V rámci platby kartou je možné využiť mnoho funkcií. Medzi ne patrí refundácia platby, storno nedokončenej platby, opakované platby (napríklad pre predplatné s pravidelným strhávaním prostriedkov z karty platiteľa) alebo predautorizácia. Platbu kartou možno tiež zobraziť priamo v e-shope (iframe).

Apple Pay

Služba Apple Pay je súčasťou platobnej brány Comgate. Na zobrazenie služby zákazníkovi stačí mať povolenú metódu platby kartou CARD_CZ_CSOB_2.

V rámci služby nie je možné použiť funkciu Opakované platby kvôli bezpečnostnému princípu Apple Pay a tzv. kartovej tokenizácii. Ostatné funkcie sú k dispozícii.

Zobrazenie služby Apple Pay
Zobrazenie služby Apple Pay sa odvíja podľa toho, či sa výber platobných metód nachádza v košíku e-shopu alebo e-shop využíva výber metód od Comgate. Ďalej je potrebné rozlíšiť, či má dôjsť k presmerovaniu platiteľa na kartovú bránu alebo sa Apple Pay zobrazí priamo v prostredí košíka e-shopu. Rozlišujeme teda tri možnosti zobrazenia Apple Pay:

1. tlačidlo Apple Pay v kartovej bráne
V prípade, že sa výber platobných metód nachádza na strane Comgate, nie sú na zobrazenie služby potrebné žiadne úpravy. Stačí mať povolenú metódu platby kartou CARD_CZ_CSOB_2. Po výbere tejto metódy zo strany platiteľa sa uskutočňuje platba štandardným procesom s presmerovaním na platobnú bránu. Služba sa zobrazí automaticky na kartovej bráne. Tu je zároveň platcovi umožnené zadať číslo karty ručne. Ak sa na bránu dostane platiteľ zo zariadenia či prehliadača, ktoré Apple Pay neumožňujú, bude môcť vykonať aspoň úhradu platobnou kartou.

2. tlačidlo Apple Pay v košíku e-shopu s presmerovaním platiteľa na kartovú bránu
Ak je výber platobných metód na strane e-shopu, platba sa zakladá ako bežná platba, v špecifikácii však treba vyvolať metódu APPLEPAY_REDIRECT. Následne dôjde k presmerovaniu platiteľa na platobnú bránu pomocou získaného platobného odkazu. Tlačidlo Apple Pay sa potom zobrazí na kartové bráne automaticky. Proces platby z pohľadu platcu je následne zhodný s prvou variantom.

Odporúčanie, kedy zobrazovať Apple Pay v košíku e-shopu
Služba Apple Pay je dostupná iba užívateľom, ktorí majú k dispozícii webový prehliadač Safari a vlastné zariadenie od spoločnosti Apple, ktoré disponuje Touch ID alebo Face ID. K týmto zariadeniam patria iPhone, iPad, Apple Watch a počítač Mac. Z tohto dôvodu odporúčame službu zobrazovať v objednávke iba klientom, ktorí platiť s Apple Pay môžu. Návod nájdete priamo na stránkach Apple pre vývojárov.  

Odporúčanie, ako správne zobrazovať Apple Pay
Správne použitie log a názvov Apple Pay nájdete v sprievodcovi Marketingem od Apple Pay. Ako zobraziť tlačidlo Apple Pay, nájdete na stránkach Buttons and Marks. Ďalej odporúčame si prečítať sprievodcu k používaniu CSS štýlov, dostupných v Safari.

3. tlačidlo Apple Pay súčasťou košíka e-shopu, bez presmerovania na kartovú bránu
Túto časť pre vás pripravujeme.

Google Pay

Službu je možné použiť pre platbu online na ľubovoľnom zariadení. Pri platbe online je potrebné mať kartu uloženú na svojom Google účte alebo ju uložiť v rámci prehliadača Chrome v priebehu platby. Pre platbu cez mobilné zariadenie je nutné si Google Pay najskôr stiahnuť pomocou Google Store a pridať tam kartu. Nie je dostupné iba na zariadeniach Apple, ak je dostupný Apple Pay (pozri vyššie).

Zobrazenie služby Google Pay

Zobrazenie služby Google Pay sa odvíja podľa toho, či sa výber platobných metód nachádza v košíku e-shopu alebo e-shop využíva výber metód od Comgate. Ďalej je potrebné rozlíšiť, či má dôjsť k presmerovaniu platiteľa na kartovú bránu alebo sa Google Pay zobrazí priamo v prostredí košíka e-shopu.

1. Tlačidlo Google Pay v kartovej bráne
V prípade, že sa výber platobných metód nachádza na strane Comgate stačí mať povolenú metódu platby kartou CARD_CZ_CSOB_2. Po výbere tejto metódy zo strany platiteľa prebieha platba štandardným procesom s presmerovaním na platobnú bránu. Služba sa zobrazí automaticky na kartovej bráne. Tu je zároveň platiteľovi umožnené zadať číslo karty ručne. Pokiaľ zakladáte platbu s inou metódou ako CARD_CZ_CSOB_2 alebo GOOGLEPAY_REDIRECT, platca po presmerovaní na platobnú bránu musí vybrať “Platba kartou” a potom bude môcť zaplatiť metódou Google Pay alebo kartou.

2. Tlačidlo Google Pay v košíku e-shopu s presmerovaním platiteľa na kartovú bránu
Pokiaľ je výber platobných metód na strane e-shopu, platba sa zakladá ako bežná platba, v požiadavke je však potrebné volať metódu GOOGLEPAY_REDIRECT. Následne dôjde k presmerovaniu platiteľa na platobnú bránu pomocou získaného platobného odkazu. Tlačidlo Google Pay sa potom zobrazí na kartovej bráne automaticky. Proces platby z pohľadu platiteľa je rovnaký s prvým variantom.

Pokiaľ obchodník nerobí kontrolu dostupnosti Google Pay na svojej strane, nemusí byť tento variant vo výsledku dostupný, aj keď si ho platiteľ vybral v košíku eshopu a platba mu s ním bola založená.

Prípady, keď Google Pay sa nezobrazí

Môže sa stať, že Google Pay platiteľovi zobrazený nebude, pokiaľ Google Pay vyhodnotí, že nie je možné platbu cez ich rozhranie realizovať.

Google Pay sa nezobrazí, keď:

  • platiteľ má nepodporovaný prehliadač (Zoznam browsera je tu v angličtine) ,
  • nemáte povolenú metódu Google Pay alebo CARD_CZ_CSOB_2 - ide o zvláštnych prípadoch, keď máte iného providera na platbu kartou alebo Eshop platforma zakazuje Google Pay mimo ich riešenia,
  • je to opakovaná platba (založená s parametrom initRecurring=true),
  • je to verifikačná platba (založená s parametrom verification = true),
  • je to predautorizácia (založená s parametrom preauth=true),
  • máte vo vašom e-shope implementované zobrazenie platobnej brány Comgate v iframe (založená s parametrom "embedded" = true). V súčasnosti analyzujeme možnosť povoliť používanie Google Pay aj pokiaľ máte bránu Comgate v i-frame,
  • rozhranie Google Pay z nejakého iného dôvodu vyhodnotí, že platbu nie je možné vykonať (viac informácií v dokumentácii Google v angličtine).

Odložená platba

Odložená platba umožňuje zákazníkom e-shopu odložiť úhradu nákupu až o niekoľko dní. E-shop svoje peniaze ale dostane v štandardnom čase.

Na zobrazenie metódy platiteľovi (zákazníkovi e-shopu) je potrebné pri založení platby vyvolať metódu platby LATER_ALL. V prípade, že sa výber platobných metód nachádza na strane Comgate, pre platiteľa sú zobrazené všetky dostupné metódy odloženej platby. V prípade, že má e-shop výber platobných metód pri sebe v košíku, odporúčame ako názov metódy pre platiteľa uviesť tento text: „Odložená platba“. Text opisu platobnej metódy je „Nakúpte hneď, zaplaťte neskôr“.

Táto metóda je dostupná len pre menu CZK a občanov Českej republiky.

Opis API metód

Založenie platby

Prístup je chránený validáciou IP adresy a integrita odovzdávaných dát je zabezpečená použitím HTTPS protokolu.

Parametre volania

Parameter

Typ

Povinný

Opis

merchant

string

A

Identifikátor e-shopu v systéme Comgate - nájdete v Klientskom portáli v sekcii Nastavenie obchodov - Prepojenie obchodu.

test

boolean

N

Hodnota „true“ znamená, že platba bude založená ako testovacia, hodnota „false“ znamená produkčnú verziu. Ak parameter chýba, založí sa platba ako produkčná.

country

string

N

Možné hodnoty: ALL, AT, BE, CY, CZ, DE, EE, EL, ES, FI, FR, GB, HR, HU, IE, IT, LT, LU, LV, MT, NL, NO, PL, PT , RO, SL, SK, SV, US. Ak parameter chýba, použije sa automaticky „CZ“. Parameter slúži na obmedzenie výberu platobných metód na platobnej bráne. Je potrebné aby bola zvolená správna kombinácia parametrov „country“ a „curry“ (mena) pre daný región. Napríklad na zobrazenie českých tlačidiel a platby kartou v mene CZK zvoľte kombináciu country = CZ a curry = CZK. Pri slovenských bankových tlačidlách a platbe kartou v EUR zvoľte country = SK a curry = EUR. Pre poľské bankové tlačidlá a platbu kartou v PLN zvoľte country = PL a curry = PLN. Pre ostatné cudzie meny môžete použiť parameter country = ALL alebo ďalší kód krajiny, ktorý platobná brána prijíma.

price

integer

A

Cena za výrobok v centoch alebo halieroch.
Musí byť min. 1 CZK; 0,1 EUR; 1 PLN; 100 HUF; 1 USD; 1 GBP; 5 RON; 0,5 NOK; 0,5 SEK. Max. neobmedzené.

curr

string

A

Kód meny podľa ISO 4217. K dispozícii sú meny: EUR, CZK, PLN, HUF, USD, GBP, RON, NOK, SEK.

label

string

A

Krátky opis produktu (1-16 znakov) - podľa tejto položky je možné filtrovať platby v Klientskom portáli.

refId

string

A

Parameter vhodný na zadanie variabilného symbolu alebo čísla objednávky na strane Klienta (nemusí byť unikátne, tzn., že možno založiť viac platieb s rovnakým refid). V Klientskom portáli a denným csv. je parameter označený ako ID Klienta.

method

string

A

Metóda platby z tabuľky platobných metód, hodnota „ALL“ v prípade, že si má metódu vybrať platiteľa alebo jednoduchý výraz s výberom metód (opísané nižšie).

account

string

N

Identifikátor bankového účtu Klienta, na ktorý Comgate Payments prevedie peniaze. Ak parameter nevyplníte, použije sa predvolený účet Klienta. Zoznam účtov Klienta nájdete na https://portal.comgate.cz/.

email

string

A

Kontaktný e-mail na Platiteľa (na účely prípadnej reklamácie)

phone

string

N

Kontaktný telefón na Platiteľa (na účely prípadnej reklamácie)

name

string

N

IIdentifikátor produktu - táto položka sa nachádza v dennom csv. Klienta pod názvom Produkt.

lang

string

N

Kód jazyka (ISO 639-1), v ktorom budú Platiteľovi zobrazené inštrukcie na dokončenie platby, štandardne povolené hodnoty („sk“, „sk“, „en“, "es", "it" „pl“, „fr“, „ro“, „de“, „hu“, „si“, „hr“), ak parameter chýba, použije sa „cs“ v prípade požiadavky na ďalší jazyk, kontaktujte podpora@comgate.cz.

prepareOnly

boolean

A

V prípade zakladania platby na pozadí vyplňte „true“. Pri zakladaní platby presmerovaním vyplňte buď „false“ alebo parameter nepoužívajte. Aký povolený spôsob založenia platby máte nastavený, zistíte v Klientskom portáli v sekcii Integrácia - Prepojenie obchodu.

secret

string

N

V prípade zakladania platby na pozadí vyplňte heslo pre komunikáciu na pozadí. Pri zakladaní platby presmerovaním parameter ponechajte prázdny alebo ho nepoužívajte.

preauth


boolean

N

V prípade požiadavky na predautorizáciu platby kartou nastavte na „true“. V prípade normálnej platby vyplňte „false“ alebo parameter nepoužívajte. Len na platby kartou.

initRecurring

boolean

N

Príznak pre založenie iniciačnej transakcie pre opakované platby. Len pre Klientov, ktorí majú službu povolenú.

verification

boolean

N

Parameter overovacej platby, v prípade požiadavky na založenie overovacej platby (hodnota „true“) nie je nutné posielať parameter „initRecurring“.

eetReport

boolean

N

Príznak odoslania dát do EET. Ak je vyplnený, preťažuje nastavenie EET v konfigurácii obchodu v Klientskom portáli.

eetData

JSON

N

Štruktúra s dátami na zaevidovanie platby do EET. nastavenia z konfigurácie v Klientskom portáli.

embeddedstringNAk používate štandardné presmerovanie platiteľa na platobnú bránu, parameter nevyplňujte alebo zadajte hodnotu „false“. Parameter sa používa len v prípade, že máte vo vašom e-shope implementované zobrazenie platobnej brány Comgate v iframe. Hodnota „true“ zaistí korektné zobrazenie brány v iframe. Toto možno použiť len na platby kartou. Podrobnejšie informácie nájdete v sekcii tu.

Server platobnej brány zodpovedá len v prípade, že je platba zakladaná na pozadí. Všetky parametre sú „urlencoded“, rovnako ako v prípade HTTP requestu. Ak je platba založená presmerovaním (parameter „prepareOnly“ je „false“), potom server platobnej brány rovno presmeruje Platiteľ na príslušnú URL alebo zobrazí chybové hlásenie.

Parametre odpovede

parameter

typ

povinný

opis

code

integer

A

Návratový kód metódy a opis chyby:

0 OK
1100 neznáma chyba
1102 zadaný jazyk nie je podporovaný
1103 nesprávne zadaná metóda
1104 nemožno načítať platbu
1107 cena platby nie je podporovaná
1200 databázová chyba
1301 neznámy e-shop
1303 prepojenie alebo jazyk chýba
1304 neplatná kategória
1305 chýba opis produktu
1306 vyberte správnu metódu
1308 vybraný spôsob platby nie je povolený
1309 nesprávna čiastka
1310 neznáma mena
1311 neplatný identifikátor bankového účtu Klienta
1316 e-shop nemá povolené opakované platby
1317 neplatná metóda - nepodporuje opakované platby
1319 nemožno založiť platbu, problém na strane banky
1399 neočakávaný výsledok z databázy
1400 chybná otázka
1500 neočakávaná chyba

message

string

A

transId

string

N

Unikátny alfanumerický identifikátor (kód) transakcie, ktorý bude zobrazený Platiteľmi v rôznych fázach platby.

redirect

string

N

URL stránka, kam má byť Platiteľ presmerovaný na realizáciu platby.

Príklad založenia platby presmerovaním (odoslaním webového formulára) - HTTP request

curl -X POST -i --data "merchant=123456&price=10000&curr=CZK&label=Beatles%20-%20Help&refId=2010102600&method=ALL" https://payments.comgate.cz/v1.0/create

Príklad založenia platby na pozadí - HTTP request

curl -X POST -i --data "merchant=merchant_com&price=10000&curr=CZK&label=Beatles%20-%20Help&refId=2010102600&method=ALL&prepareOnly=true&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y https://payments.comgate.cz/v1.0/create

Príklad založenia platby na pozadí - HTTP response

HTTP/2 200 OK
Content-Type: application/x-www-form-urlencoded; charset=utf-8
code=0&message=OK&transId=AB12-CD34-EF56&redirect=https%3A%2F%2Fpayments.comgate.cz%2Fclient%2Finstructions%2Findex%3Fid%3DAB12-CD34-EF56

Výber platobnej metódy

Odporúčame v rámci nákupného procesu v e-shope zobraziť platcovi výber platobných metód a na základe jeho výberu založiť platbu s vyplnením parametra „method“ na jednu konkrétnu hodnotu (napr. platba kartou alebo platba prevodom z ČS apod). Potom dôjde k priamemu zobrazeniu stránky poskytovateľa konkrétnej platby (banka).

V prípade, že parameter „method“ nie je vyplnený jednou konkrétnou hodnotou, dôjde k zobrazeniu ponuky platobných metód na platobnej bráne. Ponuka platobných metód môže byť špecifikovaná jednoduchým výrazom, ktorý sa zadáva do parametra „method“. Výraz sa vždy vyhodnocuje na základe metód, ktoré má e-shop povolené.

Povolené oddeľovače identifikátorov metód sú „+“ pre pripočítanie metódy a „–“  pre odpočítacie metódy z/do výberu.

Príklad:

BANK_ALL + CARD_CZ_CS - BANK_CZ_KB = všetky bankové metódy vrátane platby kartou bez bankového tlačidla Komerční banky.

BANK_CZ_CS_P + BANK_CZ_KB + BANK_CZ_RB = iba bankové tlačidla pri Českej sporiteľni, Komerčnej banke a Reiffeisen Bank (iba tieto 3 na rozdiel od BANK_ALL, ktorý by vybral všetky povolené bankové metódy e-shopu).

Platobná brána umožňuje, aby Platiteľ mal pri výbere platobnej metódy v prostredí brány Comgate predvybranú jednu konkrétnu platobnú metódu. Stačí, aby bol platiteľ presmerovaný na platobnú bránu pomocou získaného platobného odkazu s pridaným parametrom "method" s vybranou metódou.

Platobný odkaz teda môže vyzerať nasledovne:

https://payments.comgate.cz/client/instructions/index?id=ABCDEFGHIJ&method=CARD_CZ_CS

Po príchode na bránu bude mať Platiteľ už zapnutú metódu CARD_CZ_CS, výber metódy ale ďalej zostane na ňom. Táto funkcia má zmysel iba pre platby založené s metódou ALL, BANK_ALL alebo s vlastným výberom metódy.

Predautorizácia

Platobná brána umožňuje zadávať, potvrdzovať a rušiť predautorizácie platieb kartou. Založenie platby sa uskutočňuje štandardne, len je potrebné uviesť parameter „preauth = true“. Potom platca prejde rovnakým procesom ako v prípade normálnej platby. Potom, čo zadá svoje údaje na platobnej bráne, je na jeho platobnej karte rezervovaná príslušná suma. Podľa výsledku tejto operácie prechádza buď do zvláštneho stavu Authorized, alebo v prípade zamietnutia do stavu CANCELLED. Tento stav je ohlásený na pozadí obvyklým postupom opísaným vyššie.

Aby boli peniaze skutočne strhnuté, vyvolá e-shop funkciu na potvrdenie predautorizácie. Ak sa peniaze majú uvoľniť (napr. nie je možné naplniť podmienky kúpnej zmluvy), vyvolá funkciu na zrušenie predautorizácie.

Proces předautorizace

Potvrdenie predautorizácie

V prípade, že e-shop založil platbu s požiadavkou na predautorizáciu platby kartou (s využitím parametra „preauth = true“), vyvolaním tejto funkcie vyžiada strhnutie peňazí, ktoré boli v rámci predautorizácie zablokované. Je možné vykonať ako čiastočné strhnutie transakcie (predautorizovaná suma je nižšia ako suma platby), tak plné strhnutie (suma strhnutia je rovnaká ako suma platby). Volanie možno použiť len na platby, pri ktorých bol ohlásený stav Authorized. URL metódy: https://payments.comgate.cz/v1.0/capturePreauth

Parametre volania

parameter

typ

povinný

opis

merchant

string

A

identifikátor e-shopu v systéme Comgate

transId

string

A

unikátny alfanumerický identifikátor (kód) transakcie (transactionId)

secret

string

A

heslo pre komunikáciu na pozadí

amountstringNčiastka predautorizácie, ktorá má byť z karty strhnutá - môže byť v plnej alebo čiastočnej výške transakcie

Parametre odpovede

parameter

typ

povinný

opis

code

integer

A


message

string

A

návratový kód metódy a opis chyby:
0 OK
1100 neznáma chyba
1104 nemožno načítať platbu
1200 databázová chyba
1301 neznámy e-shop
1303 prepojenie alebo jazyk chýba
1399 neočakávaný výsledok z databázy
1400 chybná otázka
1500 neočakávaná chyba

Príklad potvrdenia predautorizácie – HTTP request:

curl -X POST -i --data "merchant=123456&transId=AB12-CD34-EF56&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y" https://payments.comgate.cz/v1.0/capturePreauth

Príklad potvrdenia predautorizácie – HTTP response:

HTTP/2 200 OK
Content-Type: application/x-www-form-urlencoded; charset=utf-8
code=0&message=OK

Zrušenie predautorizácie

V prípade, že e-shop založil platbu s požiadavkou na predautorizáciu platby kartou (s využitím parametra „preauth = true“), vyvolaním tejto funkcie dáva najavo, že peniaze, ktoré boli v rámci predautorizácie zablokované, nechce inkasovať a peniaze sa na karte môžu opäť uvoľniť. Volanie možno použiť len na platby, pri ktorých bol ohlásený stav Authorized. URL metódy: https://payments.comgate.cz/v1.0/cancelPreauth

Parametre volania

parameter

typ

povinný

opis

merchant

string

A

identifikátor e-shopu v systéme Comgate

transId

string

A

unikátny alfanumerický identifikátor (kód) transakcie (transactionId)

secret

string

A

heslo pre komunikáciu na pozadí

parameter

typ

povinný

opis

code

integer

A


message

string

A

návratový kód metódy a opis chyby:
0 OK
1100 neznáma chyba
1104 nemožno načítať platbu
1200 databázová chyba
1301 neznámy e-shop
1303 prepojenie alebo jazyk chýba
1399 neočakávaný výsledok z databázy
1400 chybná otázka
1500 neočakávaná chyba

Príklad zrušenia predautorizácie – HTTP request:

curl -X POST -i --data "merchant=123456&transId=AB12-CD34-EF56&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y" https://payments.comgate.cz/v1.0/cancelPreauth

Príklad zrušenia predautorizácie – HTTP response:

HTTP/2 200 OK
Content-Type: application/x-www-form-urlencoded; charset=utf-8
code=0&message=OK

Opakované platby, zapamätanie kartových údajov

Platobná brána umožňuje zadávanie opakovaných platieb, t.j. platieb na jedno kliknutie. Prvá (iniciačná) platba sa uskutočňuje štandardným procesom s presmerovaním na platobnú bránu, nasledujúce platby sa už uskutočňujú kompletne na pozadí. Systém tak umožňuje platcovi zaplatiť v priebehu niekoľkých sekúnd bez nutnosti vypĺňať informácie o platobnej karte.

Táto funkcia je dostupná na vyžiadanie. V prípade opakovaných platieb na začiatku zakladáme iniciačnú platbu, ktorá sa zakladá ako bežná platba, len sa v požiadavke nachádza navyše parameter „initRecurring“ - metóda create. Následné opakované platby sú už zakladané metódou recurring a sú viazané na Comgate ID iniciačnej transakcie. Toto ID musí byť v systéme Klienta viazané na konkrétneho Platiteľa.

Po založení opakovanej platby nedochádza k presmerovaniu platcu na platobnú bránu, pretože celý proces sa uskutočňuje na pozadí, Klientovi je len odovzdaný stav založenia platby a ten následne zobrazí tento stav platcovi.

Nasledujúce opakované platby

Založenie druhej a nasledujúcej opakované platby do platobnej brány je možné len pri akceptácii kariet pre e-shopy, ktoré majú službu povolenú. Prvá (iniciačná) platba sa uskutočňuje štandardnou cestou (pozri Založenie platby). Proces založenia druhej a každej ďalšej platby sa uskutočňuje kompletne na pozadí, tieto platby sú viazané na iniciačné cez Comgate ID iniciačné platby. Toto ID sa musí nachádzať v požiadavke v parametri „initRecurringId“. Platiteľovi je v systéme e-shopu ako výsledok zobrazený stav platby. URL metódy: https://payments.comgate.cz/v1.0/recurring 

Parametre volania

parameter

typ

povinný

opis

merchant

string

A

identifikátor e-shopu v systéme Comgate

country

string

N

kód krajiny („CZ“, „SK“, „PL“, „ALL"), ak parameter chýba, použije sa „CZ“

test

boolean

N

Hodnota „true“ znamená, že platba bude založená ako testovacia, hodnota „false“ znamená, že platba bude založená ako produkčná verzia. Ak parameter chýba, založí sa platba ako produkčná.

price

integer

A

Cena za výrobok v centoch alebo halieroch. Musí byť min. 10 CZK (vrátane), max. neobmedzene.

curr

string

A

kód meny podľa ISO 4217, štandardne „CZK“

label

string

A

krátky opis produktu (1 – 16 znakov)

refId

string

A

Referencia platby v systéme e-shopu (nemusí byť unikátna, tzn., že možno založiť viac platieb s rovnakým refid).

account

string

N

Identifikátor bankového účtu e-shopu, na ktorý Comgate prevedie peniaze. Ak parameter nevyplníte, použije sa predvolený účet e-shopu. Zoznam účtov e-shopu nájdete na https://portal.comgate.cz/

email

string

A

kontaktný email na Platiteľa (na účely prípadnej reklamácie)

phone

string

N

kontaktný telefón na Platiteľa (na účely prípadnej reklamácie)

name

string

N

Identifikátor produktu - podľa tejto položky je potom možné sa zorientovať v štatistikách platieb Comgate platobného systému.

prepareOnly

boolean

A

Parameter musí nadobúdať hodnoty „true“. Opakované platby nemožno zakladať presmerovaním.

secret

string

A

heslo pre komunikáciu na pozadí

initRecurringId

string

A

Comgate ID iniciačnej platby

eetReport

boolean

N

Príznak odoslania dát do EET. Ak je vyplnený, preťažuje nastavenie EET v konfigurácii obchodu v Klientskom portáli.

eetData

JSON

N

Štruktúra s dátami na zaevidovanie platby do EET. Zodpovedá parametrom zo špecifikácie protokolu EET. Pokiaľ má e-shop nastavené odosielanie tržby do EET a parameter nebude vyplnený, použije sa predvolené nastavenie z konfigurácie v Klientskom portáli.

Všetky parametre sú urlencoded, rovnako ako v prípade HTTP requestu na založenie štandardnej platby. V odpovedi sa nachádza parameter „code“, podľa ktorého e-shop určí, aký výsledok zobrazí platcovi. Code = 0 znamená úspech, platba bola založená, akýkoľvek iný kód znamená chybu a teda nezaloženie platby.

Parametre odpovede

parameter

typ

povinný

opis

code

integer

A

Návratový kód metódy a opis chyby:
0 OK
1100 neznáma chyba
1102 zadaný jazyk nie je podporovaný
1103 nesprávne zadaná metóda
1104 nemožno načítať platbu
1200 databázová chyba
1301 neznámy e-shop
1303 prepojenie alebo jazyk chýba
1304 neplatná kategória
1305 chýba opis produktu
1308 vybraný spôsob platby nie je povolený
1309 nesprávna čiastka
1310 neznáma mena
1311 neplatný identifikátor bankového účtu e-shopu
1316 e-shop nemá povolené opakované platby
1317 neplatná metóda - nepodporuje opakované platby
1318 iniciačná platba nebola nájdená
1319 nemožno založiť platbu, problém na strane banky
1399 neočakávaný výsledok z databázy
1400 chybná otázka
1500 neočakávaná chyba

message

string

A

transId

string

N

unikátny alfanumerický identifikátor (kód) transakcie, ktorý bude zobrazený Platiteľmi v rôznych fázach platby

Príklad založenia platby na pozadí - HTTP request

curl -X POST -i --data "merchant=123456&price=10000&curr=CZK&label=Beatles%20-%20Help&email= email_platce&refId=2010102600&prepareOnly=true&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y&initRecurringId=AB12-CD34-EF56" https://payments.comgate.cz/v1.0/recurring

Príklad založenia platby na pozadí - HTTP response

HTTP/2 200 OK
Content-Type: application/x-www-form-urlencoded; charset=utf-8
code=0&message=OK&transId=AB34-EF56-XY78

Rekurentné platby (recurring)

Rekurentné platby, tzn. opakované platby s vopred zadefinovanou sumou a periódou (napr. mesačné, týždenné apod.) je možné realizovať pomocou služby Opakované platby, ktorá je opísaná v predchádzajúcich odsekoch.

Refundácia platby

Metóda pre refundáciu je určená pre už založené a preplatené platby. Stav platby musí byť zaplatená (paid). Je možné vykonať ako čiastočnú (refundovaná suma je nižšia ako suma platby), tak plnú refundáciu (suma refundácie je rovnaká ako suma platby). Daná čiastka bude prevedená späť na účet platiteľa. URL metódy: https://payments.comgate.cz/v1.0/refund
Ak platba nebola dokončená a je v stave pending, je možné využiť metódu storno platby.

Parametre odpovede

parameter

typ

povinný

opis

merchant

string

A

identifikátor e-shopu v systéme Comgate

transId

string

A

unikátny alfanumerický identifikátor (kód) transakcie (transactionId)

secret

string

A

heslo pre komunikáciu na pozadí

amount

string

A

čiastka refundácie - môže byť v plnej alebo čiastočnej výške transakcie

curr

string

N

mena refundácie, ak nie je vyplnená, použije sa „CZK“

test

string

N

Hodnota „true“ znamená, že refundácia bude založená ako testovacia. Refundácia a platba bude preverená štandardnou cestou, len nedôjde k refundácii pôvodnej platby.

Ak je vyplnené „false“ alebo je parameter prázdny, je založená ostrá refundácia.

Testovacie transakcie môžu byť refundované iba testovacími refundáciami.

refIdstringNParameter vhodný na zadanie identifikačného čísla refundácie na strane Klienta (nemusí byť unikátna, tzn., že možno založiť viac refundácií s rovnakým refid); v Klientskom portáli v sekcii refundácií a denných csv pri refundácii je parameter označený ako ID Klienta. V prípade, že tento parameter na refundáciu nie je pripojený, k platbe sa zobrazí pôvodná refid založenej platby.

Parametre odpovede

parametertyppovinnýopis
codeintegerA
messagestringA

návratový kód metódy a opis chyby:
0 OK
1100 neznáma chyba
1200 databázová chyba
1400 chybná otázka
1401 refundovaná platba je v stave CANCELLED
1402 čiastka prevyšuje povolenú výšku
1500 neočakávaná chyba

Príklad založenia refundácie - HTTP request:

curl -X POST -i --data "merchant=123456&transId=AB12-CD34-EF56&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y&amount=100" https://payments.comgate.cz/v1.0/refund

Príklad založenia refundácie - HTTP response:

HTTP/2 200 OK
Content-Type: application/x-www-form-urlencoded; charset=utf-8
code=0&message=OK

Storno platby

V prípade, že bola objednávka v e-shope stornovaná a transakcia nemá byť platcom dokončená, je možné využiť storno platby. Na rozdiel od refundácie musí byť platba v stave očakávaná (pending). URL metódy: https://payments.comgate.cz/v1.0/cancel
Vzhľadom na rýchlosť zaplatenia platieb môže byť platba už v stave zaplatená, v takom prípade sa zobrazí chyba a je nutné využiť metódu refundácie.

Parametre volania

parameter

typ

povinný

opis

merchant

string

A

identifikátor e-shopu v systéme Comgate

transId

string

A

unikátny alfanumerický identifikátor (kód) transakcie (transactionId)

secret

string

A

heslo pre komunikáciu na pozadí

Parametre odpovede

element

typ

povinný

opis

code

integer

A


message

string

A

návratový kód metódy a opis chyby:
0 OK
1400 nie je možné prepnúť platbu do cancel stavu (platba nenájdená, platba nie je v stave pending, neoprávnený prístup)

Príklad storna platby - HTTP request:

curl -X POST -i --data "merchant=123456&transId=AB12-CD34-EF56&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y" https://payments.comgate.cz/v1.0/cancel

Príklad storna platby - HTTP response:

HTTP/2 200 OK
Content-Type: application/x-www-form-urlencoded; charset=utf-8
code=0&message=OK

Odovzdanie výsledku platby na pozadí

Platobná brána odovzdáva výsledný stav platby HTTP požiadavkou na server e-shopu. Parametre tohto volania špecifikujú detail práve dokončenej platby.

URL metody: https://adresa-vaseho-e-shopu/absdefg - metóda je volaná na server e-shopu

Parametre volania

parameter

typ

povinný

opis

merchant

string

A

identifikátor e-shopu v systéme Comgate

test

boolean

A

Hodnota „true“ znamená, že platba bola založená ako testovacia, hodnota „false“ znamená produkčnú verziu.

price

integer

A

cena za výrobok v centoch alebo halieroch

curr

string

A

kód meny podľa ISO 4217

label

string

A

krátky opis produktu (1 – 16 znakov)

refId

string

A

referencia platby (variabilný symbol, číslo objednávky) v systéme e-shopu

payerId

string

N

identifikátor Platiteľa v systéme e-shopu

payerNamestringNodovzdanie mena účtu patriaceho Platiteľovi
payerAccstringNodovzdanie čísla účtu Platiteľa

method

string

N

použitá metóda platby, z tabuľky platobných metód

account

string

N

identifikátor bankového účtu e-shopu, na ktorý Comgate Payments prevedie peniaze

email

string

A

kontaktný email na Platiteľa

phone

string

N

kontaktný telefón na Platiteľa

name

string

N

identifikátor produktu - podľa tejto položky je možné vyhľadávať v štatistikách platieb Comgate platobného systému.

transId

string

A

unikátny alfanumerický identifikátor (kód) transakcie (transactionId)

secret

string

A

heslo pre komunikáciu na pozadí

status

string

A

status - aktuálny stav transakcie, hodnoty

PAID - platba bola úspešne zaplatená

CANCELLED - platba nebola dokončená korektne a je zrušená

Authorized - vyžiadaná predautorizácia prebehla úspešne

fee

string

N

Ak má e-shop nastavené automatické strhávanie poplatku za platbu, bude v tomto poli spočítaný poplatok za transakciu, inak bude pole nadobúdať hodnoty "unknown".

eetData

JSON

N

štruktúra s dátami po zaevidovaní platby do EET

Parametre odpovedí

parameter

typ

povinný

opis

code

integer

A

Návratový kód metódy a opis chyby:

systém očakáva HTTP kód 200 v prípade, že výsledok platby bol v poriadku prijatý.

Príklad odovzdania výsledku platby na pozadí - HTTP request

curl -X POST -i --data "merchant=123456&test=false&price=10000&curr=CZK&label=Beatles%20-%20Help&refId=2010102600&method=CARD&email=email_platce&phone=%2B420123456789&transId=AB12-CD34-EF56&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y&status=PAID" https://www.example.com/handler.php

Príklad odovzdania výsledku platby na pozadí - HTTP response

HTTP/2 200 OK
Content-Type: application/x-www-form-urlencoded; charset=utf-8

Opis JSON štruktúry s dátami EET (eetData):

parameter

typ

povinný

opis

fik

string

N

fiškálny identifikačný kód daňovníka

bkp

string

A

bezpečnostný kód daňovníka

pkp

string

N

podpisový kód daňovníka zakódovaný v base64

celk_trzba

integer

A

celková čiastka tržby

poradove_cislo

integer

A

poradové číslo účtenky

zakl_nepodl_dph

integer

N

celková suma plnení oslobodených od DPH, ostatné plnenia

zakl_dan1

integer

N

celkový základ dane so základnou sadzbou DPH

dan1

integer

N

celková DPH so základnou sadzbou

zakl_dan2

integer

N

celkový základ dane s prvou zníženou sadzbou DPH

dan2

integer

N

celková DPH s prvou zníženou sadzbou

zakl_dan3

integer

N

celkový základ dane s druhou zníženou sadzbou DPH

dan3

integer

N

celková DPH s druhou zníženou sadzbou

cest_sluz

integer

N

celková čiastka v režime DPH pre cestovnú službu

pouzit_zboz1

integer

N

celková čiastka v režime DPH pre predaj použitého tovaru so základnou sadzbou

pouzit_zboz2

integer

N

celková čiastka v režime DPH pre predaj použitého tovaru s prvou zníženou sadzbou

pouzit_zboz3

integer

N

celková čiastka v režime DPH pre predaj použitého tovaru s druhou zníženou sadzbou

urceno_cerp_zuct

integer

N

celková suma platieb určená na následné čerpanie alebo zúčtovania

cerp_zuct

integer

N

celková výška platieb, ktoré sú následným čerpaním alebo zúčtovaním

datum_trzby

string

A

dátum tržby vo formáte YYYY-MM-DD HH24: MI:SS

ic_poplatnika

string

N

IČ daňovníka

dic_poplatnika

string

A

DIČ daňovníka

id_provozovny

string

A

označenie podniku

id_pokladny

string

A

označenie pokladničného zariadenia

adresa_poplatnika

string

N

adresa daňovníka

rezim_trzby

string

A

režim, v ktorom bola tržba uskutočnená

Príklad štruktúry EET:

{
"fik": "b3a09b52-7c87-4014-a496-4c7a53cf9125-03",
"bkp": "03ec1d0e-6d9f77fb-1d798ccb-f4739666-a4069bc3",
"pkp": "Ca8sTbURReQjjgcy/znXBKjPOnZof3AxWK5WySpyMrUXF0o7cz1BP6adQzktODKh2d8s
oAhn1R/S07lVDTa/6r9xTuI3NBH/+7YfYz/t92eb5Y6aNvLm6tXfOdE3C94EqmT0SEEz
9rInGXXP1whIKYX7K0HgVrxjdxCFkZF8Lt12XbahhAzJ47LcPxuBZZp6U6wJ2sWI5os3
KY9u/ZchzAUaCec7H56QwkMnu3U3Ftwi/YrxSzQZTmPTpFYKXnYanrFaLDJm+1/yg+VQ
ntoByBM+HeDXigBK+Shaxx+Nd0sSmm1Im4v685BRVdUId+4CobcnSQ3CBsjAhqmIrtWT
GQ==",
"poradove_cislo": "999",
"celk_trzba": "100000",
"zakl_nepodl_dph": "20000",
"zakl_dan1": "83500",
"dan1": "16500",
"zakl_dan2": "200000",
"dan2": "30000",
"zakl_dan3": "400000",
"dan3": "20000",
"cest_sluz": "50000",
"pouzit_zboz1": "10000",
"pouzit_zboz2": "20000",
"pouzit_zboz3": "30000",
"urceno_cerp_zuct": "60000",
"cerp_zuct": "70000",
"datum_trzby": "2017-03-01 15:00:00",
"dic_poplatnika": "CZ12345678",
"id_provozovny": "11",
"id_pokladny": "eshop",
"rezim_trzby": "běžný"
}

Získanie stavu platby na pozadí

Analogická funkcia pre odovzdanie výsledku platby na pozadí, iba iniciovaná Obchodom. Nenahrádza však odovzdanie stavu platby na pozadí, jej implementácia je stále povinná. URL metódy: https://payments.comgate.cz/v1.0/status

Parametre volania

parameter

typ

povinný

opis

merchant

string

A

identifikátor e-shopu v systéme Comgate

transId

string

A

unikátny alfanumerický identifikátor (kód) transakcie (transactionId)

secret

string

A

heslo pre komunikáciu na pozadí

Parametre odpovedí

parameter

typ

povinný

opis

code

integer

A

návratový kód metódy a opis chyby:
0 OK
1100 neznáma chyba
1200 databázová chyba
1400 chybná otázka
1500 neočakávaná chyba
V prípade code = 0 sú v odpovedi nasledujúce parametre:

message

string

A

merchant

string

A

identifikátor e-shopu v systéme Comgate

test

boolean

A

Hodnota „true“ znamená, že platba bola založená ako testovacia, hodnota „false“ znamená produkčnú verziu.

price

integer

A

cena za výrobok v centoch alebo halieroch

curr

string

A

kód meny podľa ISO 4217

label

string

A

krátky opis produktu (1 – 16 znakov)

refId

string

A

referencia platby v systéme e-shopu

payerId

string

N

identifikátor Platiteľa v systéme e-shopu

method

string

N

použitá metóda platby, z tabuľky platobných metód

account

string

N

identifikátor bankového účtu e-shopu, na ktorý Comgate Payments prevedie peniaze

email

string

A

kontaktný email na Platiteľa

phone

string

N

kontaktný telefón na Platiteľa

name

string

N

Identifikátor produktu - podľa tejto položky je potom možné sa zorientovať v štatistikách platieb Comgate platobného systému.

transId

string

A

unikátny alfanumerický identifikátor (kód) transakcie (transactionId)

secret

string

A

heslo pre komunikáciu na pozadí

status

string

A

aktuálny stav transakcie, hodnoty
PENDING - platba je založená, finálny výsledok nie je známy
PAID - platba bola úspešne zaplatená
CANCELLED - platba nebola dokončená korektne a je zrušená
Authorized - vyžiadaná predautorizácia prebehla úspešne

payerName

stringNodovzdanie mena účtu patriacemu Platiteľovi
payerAccstringNodovzdanie čísla účtu Platiteľa

fee

string

N

ak má e-shop nastavené automatické strhávanie poplatku za platbu, bude v tomto poli spočítaný poplatok za transakciu, inak bude pole nadobúdať hodnotu „unknown“

eetData

JSON

N

Štruktúra s dátami po zaevidovaní platby do EET. Rovnaká štruktúra, ako v prípade.

Príklad získania stavu platby - HTTP request

curl -X POST -i --data "merchant=123456&transId=AB12-CD34-EF56&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y" https://payments.comgate.cz/v1.0/status

Príklad získania stavu platby - HTTP response

HTTP/2 200 OK
Content-Type: application/x-www-form-urlencoded; charset=utf-8
code=0&message=OK&merchant=merchant_com&test=false&price=10000&curr=CZK&label=Beatles%20-%20Help&refId=2010102600&method=CARD&email=platce_email&phone=%2B420123456789&transId=AB12-CD34-EF56&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y&status=PAID

Získanie povolených metód

Metóda na získanie nastavenia, ktoré má e-shop povolené v Comgate Payments Platobnom Systéme. Touto metódou možno získať zoznam dostupných platobných metód na realizáciu platieb. URL metódy: https://payments.comgate.cz/v1.0/methods

Parametre volania

parameter

typ

povinný

opis

merchant

string

A

identifikátor e-shopu v systéme Comgate

secret

string

A

heslo pre komunikáciu na pozadí

type

string

N

Formát vrátených dát („xml“ alebo „json“). Pokiaľ nebude vyplnené, použije sa „xml“.

lang

string

N

Výber, v akom jazyku budú opisy metód. Povolené hodnoty sú „cs“, „en“, „pl“. Pokiaľ nebude vyplnené, použije sa „cs“.

currstringNVyplnením parametra na hodnoty CZK alebo EUR dôjde k vráteniu metód, ktoré podporujú zadanú menu.
countrystringN

Kód krajiny („CZ“, „SK“), parameter slúži na obmedzenie výberu možných spôsobov pre zadanú krajinu.

V odpovedi sa nachádza XML alebo JSON, podľa zvoleného parametra. Obidva formáty majú rovnakú úroveň zanorenia.

Parametre odpovede

element

typ

povinný

opis

/methods/method/id

string

A

dostupná metóda platby

/methods/method/name

string

A

názov metódy, vo zvolenom jazyku

/methods/method/description

string

A

dlhší opis metódy, vo zvolenom jazyku

/methods/method/logo

string

A

HTTP link na logo metódy

V prípade chyby majú dáta nasledujúci tvar.

Parametre odpovede

element

typ

povinný

opis

/error/code

string

A

návratový kód metódy a opis chyby:

/error/message

string

A

0 OK
1100 neznáma chyba
1200 databázová chyba
1300 e-shop nemá žiadnu metódu
1400 chybná otázka
1500 neočakávaná chyba

/error/extraMessage

string

N

upresnenie chybového hlásenia

Príklad získania povolených platobných metód - HTTP request:

curl -X POST -i --data "merchant=123456&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y&type=xml&lang=cs" https://payments.comgate.cz/v1.0/methods

Príklad získania povolených platobných metód - HTTP response:

HTTP/2 200 OK
Content-Type: application/xml; charset=utf-8
<?xml version="1.0" encoding="UTF-8"?>
<methods>
<methods>
<id>BANK_CZ_CS_P</id>
<name>Česká spořitelna - PLATBA 24</name>
<description>On-line platba pro majitele účtu u České spořitelny.</description><logo>https://payments.comgate.cz/assets/images/logos/BANK_CZ_CS_P.png</logo>
<methods>
<methods>
<id>BANK_CZ_FB_P</id>
<name>Fio banka - PayMyway</name>
<description>On-line platba pro majitele účtu u Fio banky.</description><logo>https://payments.comgate.cz/assets/images/logos/BANK_CZ_FB.png</logo>
<methods>
<methods>HTTP/2 200 OK

HTTP/2 200 OK
Content-Type: application/json; charset=utf-8
{
"methods": [

"id": "BANK_CZ_CS_P",
"name": "Česká spořitelna - PLATBA 24",
"description": "On-line platba pro majitele účtu u České spořitelny.",
"logo": "https://payments.comgate.cz/assets/images/logos/BANK_CZ_CS_P.png"
},
{
"id": "BANK_CZ_FB",
"name": "Fio banka - PayMyway",
"description": "On-line platba pro majitele účtu u Fio banky.",
"logo": "https://payments.comgate.cz/assets/images/logos/BANK_CZ_FB.png"
}
] 
} 

Príklad získania povolených platobných metód - HTTP response v prípade chyby:

HTTP/2 200 OK
Content-Type: application/xml; charset=utf-8
<?xml version="1.0" encoding="UTF-8"?>
<error>
<code>1400</code>
<message>Unauthorized access!</message>
</error>

HTTP/2 200 OK
Content-Type: application/json; charset=utf-8
{
"error": {
"code": 1400,
"message": "Unauthorized access!"
} 
} 

Zasielanie tržby do EET

Do systému EET musí obchodník evidovať každú platbu vykonanú kartou alebo v hotovosti. Daňoví platcovia musia posielať detail dane, neplatcovia DPH iba celkovú sumu. Ďalšie informácie sú obsiahnuté v EET riešení.

Najprv sa obchodník musí zaregistrovať do EET a stiahnuť si certifikát na zabezpečenú komunikáciu. Následne obchodník vykoná konfiguráciu prepojenia s EET v rozhraní klientskeho portálu.

Ak je EET správne nastavené v klientskom portáli, potom je možné prejsť na založenie platby. V rámci platieb EET sa rozlišujú dva režimy:

  1. Automatický (predvolený) režim umožňuje obchodníkovi posielať platby do EET bez toho, aby musel implementovať niečo navyše do komunikačného protokolu platobnej brány Comgate. Tento režim slúži neplatcom DPH a platiteľom DPH, ktorí predávajú tovar len v jednej daňovej sadzbe zodpovedajúcej nastaveniu na klientskom portáli. Ak je platba vykonaná v zahraničnej mene, bude do EET zaevidovaná v Sk a ako kurz na prepočet sa použije kurz danej meny vyhlásený ČNB z predchádzajúceho dňa.

  2. Rozšírený režim prináša nutnosť upraviť komunikačný protokol platobnej brány Comgate. Do protokolu bude obchodník posielať kompletný rozpad čiastky pre EET v parametri „eetData“ (viď príklad nižšie, názvy parametrov sú podľa špecifikácie EET). Tento režim je nutný pre všetkých, ktorí predávajú tovar vo viacerých sadzbách DPH, pre cestovné služby, ktoré predávajú a uplatňujú vouchery alebo predávajú použitý tovar. Dáta sa odovzdávajú vo formáte JSON, sumy sú uvádzané v halieroch.


Opis JSON štruktúry s dátami EET (eetData):

parameter

typ

povinný

opis

celk_trzba

integer

A

celková čiastka tržby

zakl_nepodl_dph

integer

N

celková suma plnení oslobodených od DPH, ostatné plnenia

zakl_dan1

integer

N

celkový základ dane so základnou sadzbou DPH

dan1

integer

N

celková DPH so základnou sadzbou

zakl_dan2

integer

N

celkový základ dane s prvou zníženou sadzbou DPH

dan2

integer

N

celková DPH s prvou zníženou sadzbou

zakl_dan3

integer

N

celkový základ dane s druhou zníženou sadzbou DPH

dan3

integer

N

celková DPH s druhou zníženou sadzbou

cest_sluz

integer

N

celková čiastka v režime DPH pre cestovnú službu

pouzit_zboz1

integer

N

celková čiastka v režime DPH pre predaj použitého tovaru so základnou sadzbou

pouzit_zboz2

integer

N

celková čiastka v režime DPH pre predaj použitého tovaru s prvou zníženou sadzbou

pouzit_zboz3

integer

N

celková čiastka v režime DPH pre predaj použitého tovaru s druhou zníženou sadzbou

urceno_cerp_zuct

integer

N

celková suma platieb určená na následné čerpanie alebo zúčtovanie

cerp_zuct

integer

N

celková výška platieb, ktoré sú následným čerpaním alebo zúčtovaním

Príklad štruktúry EET:

1. Zákaznice zakoupila obnošenou bundu za 330 Kč, nové nenošené punčocháče za 50 Kč a potraviny za 115 Kč.
{
"celk_trzba": "49500",
"zakl_nepodl_dph": "0",
"zakl_dan1": "4132",
"dan1": "868",
"zakl_dan2": "10000",
"dan2": "1500",
"zakl_dan3": "0",
"dan3": "0",
"cest_sluz": "0",
"pouzit_zboz1": "33000",
"pouzit_zboz2": "0",
"pouzit_zboz3": "0",
"urceno_cerp_zuct": "0",
"cerp_zuct": "0"
}

2. Zákazník vložil celou částku 500 Kč do své elektronické peněženky a zároveň z této peněženky
uhradil nákup zboží v ceně 200 Kč včetně DPH.
{
"celk_trzba": "50000",
"zakl_nepodl_dph": "0",
"zakl_dan1": "16528",
"dan1": "3472",
"zakl_dan2": "0",
"dan2": "0",
"zakl_dan3": "0",
"dan3": "0",
"cest_sluz": "0",
"pouzit_zboz1": "0",
"pouzit_zboz2": "0",
"pouzit_zboz3": "0",
"urceno_cerp_zuct": "50000",
"cerp_zuct": "20000"
}

3. Zákazník zaplatil celkem 18 000 Kč, z této částky zakoupil zájezd v ceně 17 500 Kč, za 200 Kč nakoupil zboží a 300 Kč přibylo na jeho zákaznickém účtu pro následné čerpání (nabíjení „kreditu“).
{
"celk_trzba": "1800000",
"zakl_nepodl_dph": "0",
"zakl_dan1": "16528",
"dan1": "3472",
"zakl_dan2": "0",
"dan2": "0",
"zakl_dan3": "0",
"dan3": "0",
"cest_sluz": "1750000",
"pouzit_zboz1": "0",
"pouzit_zboz2": "0",
"pouzit_zboz3": "0",
"urceno_cerp_zuct": "30000",
"cerp_zuct": "0"
}

Verifikačné, overovacie platby

Ak chce e-shop využiť opakované platby v budúcnosti a chce Platiteľa „registrovať“ teraz, môže využiť overovaciu transakciu. Pri vyplnení parametra „verification“ na hodnotu „true“ dôjde k založeniu overovacej transakcie. Hneď ako Platiteľ platbu uhradí, dôjde k jej automatickej refundácii, nie je teda nutné následne platbu refundovať ručne. Overovacia transakcia inak funguje rovnako ako iniciačná transakcia, tzn. je možné zakladať opakované platby s využitím jej Comgate ID. Z dôvodu limitácie zo strany bánk nie je možné kombinovať opakované platby a predautorizáciu.

API na sťahovanie súborov

Zoznam prevodov v rámci dňa

Metóda transferList slúži na získanie informácie, aké prevody boli uskutočnené v rámci daného dňa. URL metódy: https://payments.comgate.cz/v1.0/transferList

Parametre volania

parametertyppovinnýopis
merchantstringAidentifikátor e-shopu v systéme Comgate
secretstringA

heslo pre komunikáciu na pozadí

datestringAuveďte dátum uskutočnenia prevodu
testbooleanNak vyplníte true, metóda vráti vopred definovaný vzorový prevod

Príklad získanie zoznamu prevodov v rámci dňa - HTTP request

curl -X POST -i --data "merchant=123456&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y&date=YYYY-MM-DD" https://payments.comgate.cz/v1.0/transferList

Príklad získanie zoznamu prevodov v rámci dňa - HTTP response

HTTP/2 200 OK
Content-Type: application/json; charset=UTF-8
[{"transferId":1234567,"transferDate":"2023-01-25","accountCounterparty":"0\/0000","accountOutgoing":"123456789\/0000","variableSymbol":"12345678"}]

Detail bankového prevodu

Metóda singleTransfer zobrazuje detailné informácie ku konkrétnemu bankovému prevodu. Povinný parameter „transferId“ získa obchodník pomocou metódy transferList. URL metódy https://payments.comgate.cz/v1.0/singleTransfer

Parametre volania

parametertyppovinnýopis
merchantstringAidentifikátor e-shopu v systéme Comgate
secretstringA

heslo pre komunikáciu na pozadí

transferIdstringA

uveďte prevody, ktoré boli uskutočnené v rámci daného dňa. Zoznam získate pomocou metódy transferList.

testbooleanN

vhodné na testovanie - Ak je hodnota true, vrátia sa detaily k vopred definovaným vzorovým prevodom

Príklad získania detailu ku konkrétnemu bank. prevodu - HTTP request

curl -X POST -i --data "merchant=123456&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y&transferId=5217530" https://payments.comgate.cz/v1.0/singleTransfer

Príklad získania detailu ku konkrétnemu bank. prevodu - HTTP response

1 = platba
2 = refundácia
3 = mesačný poplatok
4 = ostatné poplatky, chargeback a ručné pohyby
5 = sumárne riadok

HTTP/2 200
Content-Type: application/json; charset=UTF-8
[ 
  {       
     "typ": 1,
     "Merchant": "135261",
     "Datum založení": "2019-07-23 11:40:20",
     "Datum zaplacení": "2019-07-23 11:42:02",
     "Datum převodu": "2019-07-25",
     "Měsíc fakturace": null,
     "ID ComGate": "QWDZ-AGRU-1F6L", 
     "Metoda": "Platba kartou",       
     "Produkt": null,       
     "Popis": "ComGate s.r.o.",       
     "E-mail plátce": "info@comgate.cz",       
     "Variabilní symbol platby": "86230990",       
     "Variabilní symbol převodu": "86616655",       
     "ID od klienta": "5331940",       
     "Měna": "HUF",       
     "Potvrzená částka": "12480,00",       
     "Převedená částka": "12356,45",       
     "Poplatek celkem": "123,55",       
     "Poplatek mezibankovní": "24,96",       
     "Poplatek asociace": "33,70",       
     "Poplatek zpracovatel": "64,89"   
}, 
{       
     "typ": 5,       
     "Merchant": "-",       
     "Datum založení": null,       
     "Datum zaplacení": null,       
     "Datum převodu": "2019-07-25",       
     "Měsíc fakturace": null,       
     "ID ComGate": null,       
     "Metoda": null,       
     "Produkt": "suma",       
     "Popis": "-",       
     "E-mail plátce": "-",       
     "Variabilní symbol platby": "-",       
     "Variabilní symbol převodu": "86616655",       
     "ID od klienta": "-",       
     "Měna": "HUF",       
     "Potvrzená částka": "54910,00",       
     "Převedená částka": "54366,40",       
     "Poplatek celkem": "543,60",       
     "Poplatek mezibankovní": "109,82",       
     "Poplatek asociace": "148,27",       
     "Poplatek zpracovatel": "285,51"   
}
]

CSV k vybranému prevodu

Vďaka metóde csvSingleTransfer si možno stiahnuť denný výpis vo formáte CSV. URL metódy: https://payments.comgate.cz/v1.0/csvSingleTransfer

Parametre volania

parametertyppovinnýopis
merchantstringAidentifikátor e-shopu v systéme Comgate
secretstringA

heslo pre komunikáciu na pozadí

transferIdstringA

Uveďte prevody, ktoré boli uskutočnené v rámci daného dňa. Zoznam získate pomocou metódy transferList.

downloadstringNAk nie je vyplnené alebo je false, tak vracia dáta: názov súboru a jeho obsah; ak je true, tak vracia rovno CSV súbor.
testbooleanNAk je hodnota true, vráti ukážkový CSV súbor.

Príklad sťahovania výpisu vo formáte csv ku konkrétnemu bankovému prevodu - HTTP request

curl -X POST -i --data "merchant=123456&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y&transferId=5217530&download=false" https://payments.comgate.cz/v1.0/csvSingleTransfer

Príklad sťahovania výpisu vo formáte csv ku konkrétnemu bankovému prevodu - HTTP response

HTTP/2 200 OK
Content-Type: application/json; charset=UTF-8
{
"nazev": "vypis-YYYY-MM-DD.csv",
"csv": base64 encoded csv
}

ABO k vybranému prevodu

Vďaka metóde aboSingleTransfer si možno stiahnuť denný výpis vo formáte ABO. URL metódy: https://payments.comgate.cz/v1.0/aboSingleTransfer

Parametre volania

parametertyppovinnýopis
merchantstringAidentifikátor e-shopu v systéme Comgate
secretstringA

heslo pre komunikáciu na pozadí

transferIdstringA

uveďte prevody, ktoré boli uskutočnené v rámci daného dňa. Zoznam získate pomocou metódy transferList.

downloadstringNAk nie je vyplnené alebo je false, tak vracia dáta: názov súboru a jeho obsah; ak je true, tak vracia rovno ABO súbor.
typestringNParameter „type“ môže nadobúdať hodnoty „v1“ a „"v2“. Pod „v1“" získate ABO verziu s poplatkami uvedenými zvlášť ku každej platbe, pod „v2“ potom ABO so súhrnným poplatkom v jednom riadku. Pokiaľ nebude parameter vyplnený, automaticky obdržíte typ „v1“.
testbooleanNAk je hodnota true, vráti ukážkový ABO súbor.

Príklad sťahovania rozpisu ABO ku konkrétnemu bankovému prevodu - HTTP request

curl -X POST -i --data "merchant=123456&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y&transferId=transfer_id&download=true&type=v1" https://payments.comgate.cz/v1.0/aboSingleTransfer

Príklad sťahovania rozpisu ABO ku konkrétnemu bankovému prevodu - HTTP response

HTTP/2 200 OK
Content-Type: application/json; charset=UTF-8
{
"nazev": "vypis-YYYY-MM-DD.gpc",
"abo": base64 encoded abo/gpc file
}

CSV pre prevody v rámci dňa

Priame preberanie CSV súborov pre konkrétny deň metódou csvDowload. Stiahnutý súbor vo formáte ZIP bude obsahovať jeden alebo viac súborov CSV, ak je viac prevodov v rámci dňa. Možno využiť napr. na volanie pomocou wget. URL metódy: https://payments.comgate.cz/v1.0/csvDownload

Parametre volania

parametertyppovinnýopis
merchantstringAidentifikátor e-shopu v systéme Comgate
secretstringA

heslo pre komunikáciu na pozadí

datestringA

povinný len za jeden deň

testbooleanNAk je hodnota true, vráti ukážkový CSV súbor vo formáte ZIP.

Príklad sťahovania csv pre prevody v rámci dňa - HTTP request

curl -X POST -i --data "merchant=123456&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y&date=YYYY-MM-DD" https://payments.comgate.cz/v1.0/csvDownload

Príklad sťahovania csv pre prevody v rámci dňa - HTTP response

HTTP/2 200 OK
Content-Type: application/zip
Content-Disposition: attachment; filename="vypis-csv-YYYY-MM-DD.zip"
Content-Length: delka_souboru
ZIP soubor obsahující CSV k převodům za den v parametru ke stažení jako response

ABO pre prevody v rámci dňa

Priame preberanie ABO súborov pre konkrétny deň metódou aboDowload. Stiahnutý súbor vo formáte ZIP bude obsahovať jeden alebo viac súborov ABO.

Možno využiť napr. na volanie pomocou wget.

URL metódy: https://payments.comgate.cz/v1.0/aboDownload

Parametre volania

parametertyppovinnýopis
merchantstringAidentifikátor e-shopu v systéme Comgate
secretstringA

heslo pre komunikáciu na pozadí

datestringA

povinný len za jeden deň

type stringNParameter „type“ môže nadobúdať hodnoty „v1“ a „"v2“. Pod „v1“" získate ABO verziu s poplatkami uvedenými zvlášť ku každej platbe, pod „v2“ potom ABO so súhrnným poplatkom v jednom riadku. Pokiaľ nebude parameter vyplnený, automaticky obdržíte typ „v1“.
testbooleanNAk je hodnota true, vráti ukážkový ABO súbor vo formáte ZIP.

Príklad sťahovania ABO pre prevody v rámci dňa - HTTP request

curl -X POST -i --data "merchant=123456&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y&date=YYYY-MM-DD&type=v2" https://payments.comgate.cz/v1.0/aboDownload

Príklad sťahovania ABO pre prevody v rámci dňa - HTTP response

HTTP/2 200 OK
Content-Type: application/zip
Content-Disposition: attachment; filename="vypis-csv-YYYY-MM-DD.zip"
Content-Length: delka_souboru
ZIP soubor obsahující ABO k převodům za den v parametru ke stažení jako response

Číselníky

Stavy platieb

stav

opis

PENDING

Platba bola založená, finálny výsledok platby zatiaľ nie je známy.

PAID

Platiteľ úspešne zaplatil platbu - je možné vydať tovar, resp. sprístupniť službu.

CANCELLED

Platba nebola zaplatená, tovar nebude vydaný, resp. služba nebude poskytnutá. Vo výnimočných prípadoch sa môže stať, že tento stav bude zmenený na stav PAID.

AUTHORIZED

Predautorizácia platby prebehla úspešne (peniaze na karte platcu boli zablokované). Čaká sa na ďalšiu požiadavku, ktorou bude potvrdená alebo zrušená.

Platobné metódy

typ

opis

identifikátor


Platobnú metódu si vyberie Platiteľ v rozcestníku.

ALL

Platobná karta

poskytovateľ automaticky

CARD_ALL 

Odložená platbaposkytovateľ automatickyLATER_ALL
odložená platba od Equa bánkLATER_PLATIMPAK

Bankovné platby

banku Platiteľ vyberie v rozcestníku Comgate Payments

BANK_ALL

bankový prevod iných bánk

BANK_CZ_OTHER

bankové tlačidlo Raiffeisen Bank

BANK_CZ_RB

bankové tlačidlo Komerčné Banky

BANK_CZ_KB

bankové tlačidlo FIO Banky

BANK_CZ_FB

bankové tlačidlo Českej sporiteľne

BANK_CZ_CS_P

bankové tlačidlo mBank

BANK_CZ_MB_P

bankové tlačidlo ČSOB

BANK_CZ_CSOB_P

bankové tlačidlo Era

BANK_CZ_PS_P

bankové tlačidlo UniCredit Bank

BANK_CZ_UC

bankové tlačidlo Slovenských sporiteľne

BANK_SK_SP

bankové tlačidlo VÚB Banky

BANK_SK_VUB

bankové tlačidlo Tatra Banky

BANK_SK_TB

bankové prevod iných bánkBANK_SK_OTHER
bankové tlačidlo Alior BankBANK_PL_ALR
bankové tlačidlo BGŻ BNP Paribas PolskaBANK_PL_BGZ
bankové tlačidlo BlikBANK_PL_BL
bankové tlačidlo Bank MillenniumBANK_PL_BM
bankové tlačidlo Bank Ochrony ŚrodowiskaBANK_PL_BOS
bankové tlačidlo Bank PocztowyBANK_PL_BP
bankové tlačidlo BPSBANK_PL_BPS
bankové tlačidlo Banki SpółdzielczeBANK_PL_BSP
bankové tlačidlo BZ WBKBANK_PL_BZ
bankové tlačidlo Credit AgricoleBANK_PL_CA
bankové tlačidlo Citi HandlowyBANK_PL_CH
bankové tlačidlo Deutsche BankBANK_PL_DB
bankové tlačidlo EurobankBANK_PL_EB
bankové tlačidlo GetIn OnlineBANK_PL_GO
bankové tlačidlo Idea BankBANK_PL_IDB
bankové tlačidlo ING Bank ŚląskiBANK_PL_ING
bankové tlačidlo InteligoBANK_PL_INT
bankové tlačidlo mBankBANK_PL_MB
bankové tlačidlo Nest BankBANK_PL_NEB
bankové tlačidlo Noble BankBANK_PL_NOB
bankové tlačidlo Plus BankBANK_PL_PB
bankové tlačidlo Bank PekaoBANK_PL_PEK
bankové tlačidlo PKO BPBANK_PL_PKO
bankové tlačidlo Raiffeisen PolbankBANK_PL_RB
bankové tlačidlo T-Mobile Usługi BankoweBANK_PL_TM
bankové tlačidlo Toyota BankBANK_PL_TOB
bankové tlačidlo Volkswagen Bank

BANK_PL_VWB

Staršie verzie protokolov k stiahnutiu

Bol tento článok užitočný?
What's Next
©2021 ComGate Payments, a.s.