API metódy platby (1.0)

create

Prístup je chránený validáciou IP adresy a integrita odovzdávaných dát je zabezpečená použitím HTTPS protokolu.
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.

Výber platobnej metódy
V rámci nákupného procesu v e-shope je možné zobraziť plátcovi výber platebných metód a na základe jeho výberu založiť platbu s konkrétnou metódou. V momente, keď je plátcovi zobrazená platobná brána, automaticky sa zobrazí predom vybraná platobná metóda. Nastavenie vybranej platobnej metódy je možné vyplnením parametra 'method'. Prostredníctvom tohto parametra je možné platobné metódy aj rôzne filtrovať.
Viac tu: https://apidoc.comgate.cz/sk/metody-platebni-brany/

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.

UPOZORNENIE

Adresa URL a štruktúra kódu platby sa môže zmeniť. Vždy používajte adresu vrátenú rozhraním API a nemanipulujte s ňou. Ak chcete platobný kód uložiť, použite parameter transId. Nikdy neparazitujte na údajoch z konkrétnych pozícií v texte, tie sa tiež môžu zmeniť.

Všetky hodnoty obsahujúce špeciálne znaky musia byť v UTF-8.

Request Body schema: application/x-www-form-urlencoded

Vytvorenie novej platby

merchant required	string Identifikátor e-shopu v systéme Comgate - nájdete v Klientskom portáli v sekcii Nastavenie obchodov - Prepojenie obchodu.
test	boolean Default: true 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 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, SI, SK, SE, 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 required	integer <int32> Cena za výrobok v centoch alebo halieroch. Pre menu HUF nemôžete zadať cenu s desatinnými miestami. V tomto prípade musí cena vždy končiť 00. 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. 1 000 000 CZK; 40 000 EUR; 170 000 PLN; 12 500 000 HUF; 45 000 USD; 35 000 GBP; 190 000 RON; 400 000 NOK; 390 000 SEK.
curr required	string Kód meny podľa ISO 4217. K dispozícii sú meny: EUR, CZK, PLN, HUF, USD, GBP, RON, NOK, SEK.
label required	string Krátky opis produktu (1-16 znakov) - podľa tejto položky je možné filtrovať platby v Klientskom portáli.
refId required	string 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 required	string 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. Viac tu: https://apidoc.comgate.cz/sk/metody-platebni-brany/
account	string Identifikátor bankového účtu Klienta, na ktorý Comgate prevedie peniaze. Ak parameter nevyplníte, použije sa predvolený účet Klienta. Zoznam účtov Klienta nájdete na https://portal.comgate.cz/.
email required	string Kontaktný email platiteľa. Povinný je len jeden z údajov, emailová adresa alebo telefónne číslo.
phone required	string Telefónne číslo platiteľa v medzinárodnom formáte +420777112233. Povinný je len jeden z údajov, emailová adresa alebo telefónne číslo.
fullName required	string Meno a priezvisko plátcu, napr. Josef Novák.
billingAddrCity	string Fakturačná adresa - mesto. (napr. Hradec Králové).
billingAddrStreet	string Fakturačná adresa - ulica. (napr. Jiráskova 115).
billingAddrPostalCode	string Fakturačná adresa - PSČ. (napr. 50304).
billingAddrCountry	string Fakturačná adresa - krajina, vo formáte ISO 3166 alpha-2 (napr. CZ, SK, US, GB).
delivery	string Spôsob doručenia - jedna z dostupných možností: HOME_DELIVERY, PICKUP, ELECTRONIC_DELIVERY. Možnosť PICKUP zahŕňa všetky miesta na vyzdvihnutie, vyzdvihovacie boxy, atď.
homeDeliveryCity	string Doručovacia adresa - mesto. Vyplňuje sa len v prípade delivery=HOME_DELIVERY (napr. Hradec Králové).
homeDeliveryStreet	string Doručovacia adresa - ulica. Vyplňuje sa len v prípade delivery=HOME_DELIVERY (napr. Štefanikova 421).
homeDeliveryPostalCode	string Doručovacia adresa - PSČ. Vyplňuje sa len v prípade delivery=HOME_DELIVERY (napr. 50341).
homeDeliveryCountry	string Doručovacia adresa - krajina, vo formáte ISO 3166 alpha-2. Vyplňuje sa len v prípade delivery=HOME_DELIVERY (napr. CZ, SK, US, GB).
category	string Kategória produktu v košíku - jedna z dostupných možností, ktorá najlepšie opisuje košík: PHYSICAL_GOODS_ONLY, OTHER. Možnosť OTHER zahŕňa darčekové karty, poukážky alebo služby.
name	string Identifikátor produktu - táto položka sa nachádza v dennom csv. Klienta pod názvom Produkt.
lang	string Kód jazyka (ISO 639-1), v ktorom budú Platiteľovi zobrazené inštrukcie na dokončenie platby, štandardne povolené hodnoty ('bg', 'cs', 'da', 'de', 'el', 'en', 'es', 'et', 'fi', 'fr', 'hr', 'hu', 'it', 'lt', 'lv', 'nl', 'no', 'pl', 'pt', 'ro', 'si', 'sk', 'sv', 'vi'), ak parameter chýba, použije sa 'cs' v prípade požiadavky na ďalší jazyk, kontaktujte podpora@comgate.cz.
prepareOnly required	boolean Default: false 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 required	string 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 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 Príznak pre založenie iniciačnej transakcie pre opakované platby. Len pre Klientov, ktorí majú službu povolenú.
verification	boolean Parameter overovacej platby, v prípade požiadavky na založenie overovacej platby (hodnota 'true') nie je nutné posielať parameter 'initRecurring'.
expirationTime	string Délka expirace platby. Povolená hodnota je celé číslo následované písmenem zvolené časové jednotky: 'm' (minuty), 'h' (hodiny) nebo 'd' (dny). Například '30m' (30 minut) nebo '10h' (10 hodin) nebo '2d' (2 dny). Jednotky nelze kombinovat. Výsledná délka musí být v rozmezí 30 minut až 7 dní. Pokud není vyplněno, použije se hodnota v nastavení obchodu zvolená v Klientském portálu.
dynamicExpiration	boolean Hodnota 'true' znamená, že u platby bude použita dynamická expirace, hodnota 'false' znamená, že dynamická expirace použita nebude. Pokud není vyplněno, použije se hodnota v nastavení obchodu zvolená v Klientském portálu.
url_paid	string Posamezne nastavitve za posamezna plačila. Na primer: 'https://www.example.com/result.php?id=${id}&refId=${refId}'
url_cancelled	string Posamezne nastavitve za posamezna plačila. Na primer: 'https://www.example.com/result.php?id=${id}&refId=${refId}'
url_pending	string Posamezne nastavitve za posamezna plačila. Na primer: 'https://www.example.com/result.php?id=${id}&refId=${refId}'
chargeUnregulatedCardFees	boolean Pomocou tohto parametra zapnete alebo vypnete prenos poplatkov na platiteľa pri platbe neregulovanou kartou a zároveň vypnete metódu Apple Pay a Google Pay (ak nie je parametrom 'enableApplePayGooglePay' nastavené inak). Povolené hodnoty sú 'true' alebo 'false'. Použitie tohto parametra je možné len po schválení a zapnutí zo strany Comgate. Nie všetky e-commerce riešenia tento parameter podporujú.
enableApplePayGooglePay	boolean Nastavte na 'false' pre vypnutie platobnej metódy Apple Pay a Google Pay pre konkrétnu platbu, aj keď sú tieto metódy vo vašom nastavení účtu povolené. Nastavte na 'true' pre zapnutie platobnej metódy Apple Pay a Google Pay pre konkrétnu platbu, aj keď je použitý parameter 'chargeUnregulatedCardFees'. Ak je použitý parameter 'chargeUnregulatedCardFees', tak je predvolená hodnota parametra 'enableApplePayGooglePay' 'false'. V opačnom prípade je predvolená hodnota 'true'.

Responses

Response Schema: application/x-www-form-urlencoded

code required	integer 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 required	string
transId	string Unikátny alfanumerický identifikátor (kód) transakcie, ktorý bude zobrazený Platiteľmi v rôznych fázach platby.
redirect	string URL stránka, kam má byť Platiteľ presmerovaný na realizáciu platby.

Request samples

cURL
PHP
Java
Python
C#

# You can also use wget
curl -X POST https://payments.comgate.cz/v1.0/create \
--data "&merchant=123456&test=1&price=1000&curr=CZK&label=Product 123&refId=order445566&method=ALL&email=platce@email.com&fullName=Jan Novák&delivery=HOME_DELIVERY&category=PHYSICAL_GOODS_ONLY&prepareOnly=1&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y" \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Accept: application/x-www-form-urlencoded'

cancel

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

Request Body schema: application/x-www-form-urlencoded

Zrušenie platby

merchant required	string identifikátor e-shopu v systéme Comgate
transId required	string unikátny alfanumerický identifikátor (kód) transakcie (transactionId)
secret required	string heslo pre komunikáciu na pozadí

Responses

Response Schema: application/x-www-form-urlencoded

code required	integer 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)
message required	string

Request samples

cURL
PHP
Java
Python
C#

# You can also use wget
curl -X POST https://payments.comgate.cz/v1.0/cancel \
--data "&merchant=123456&transId=AB12-CD34-EF56&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y" \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Accept: application/x-www-form-urlencoded'

recurring

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.

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 vytvorená a zaplatená, akýkoľvek iný kód znamená chybu a teda nezaloženie platby.

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.
Testovacie opakované platby (okrem iniciačných) vytvorené pomocou e-mailu 'recurring.cancelled@comgate.cz' budú automaticky označené ako CANCELLED (nezaplatené)

Request Body schema: application/x-www-form-urlencoded

merchant required	string identifikátor e-shopu v systéme Comgate
test	boolean 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 required	string Cena za výrobok v centoch alebo halieroch. Musí byť min. 10 CZK (vrátane), max. neobmedzene.
curr required	string kód meny podľa ISO 4217, štandardne 'CZK'
label required	string krátky opis produktu (1 – 16 znakov)
refId required	string 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 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/
name	string Identifikátor produktu - podľa tejto položky je potom možné sa zorientovať v štatistikách platieb Comgate platobného systému.
secret required	string heslo pre komunikáciu na pozadí
initRecurringId required	string Comgate ID iniciačnej platby

Responses

Response Schema: application/x-www-form-urlencoded

code required	integer 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 1320 neplatný email pre opakovanú platbu 1399 neočakávaný výsledok z databázy 1400 chybná otázka 1500 neočakávaná chyba
message required	string
transId	string unikátny alfanumerický identifikátor (kód) transakcie, ktorý bude zobrazený Platiteľmi v rôznych fázach platby

Request samples

cURL
PHP
Java
Python
C#

# You can also use wget
curl -X POST https://payments.comgate.cz/v1.0/recurring \
--data "&merchant=123456&test=1&price=10000&curr=CZK&refId=2010102600&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y&initRecurringId=AB12-CD34-EF56" \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Accept: application/x-www-form-urlencoded'

refund

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.
Ak platba nebola dokončená a je v stave pending, je možné využiť metódu storno platby.

Request Body schema: application/x-www-form-urlencoded

Vrátenie platby

merchant required	string identifikátor e-shopu v systéme Comgate
transId required	string unikátny alfanumerický identifikátor (kód) transakcie (transactionId)
secret required	string heslo pre komunikáciu na pozadí
amount required	string čiastka refundácie - môže byť v plnej alebo čiastočnej výške transakcie. Suma refundácie sa zadáva v centoch alebo halieroch. Pre menu HUF nie je možné zadať sumu s desatinnými miestami. V tomto prípade musí suma vždy končiť 00.
test	string 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.
refId	string Parameter 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.

Responses

Response Schema: application/x-www-form-urlencoded

code required	integer 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
message required	string

Request samples

cURL
PHP
Java
Python
C#

# You can also use wget
curl -X POST https://payments.comgate.cz/v1.0/refund \
--data "&merchant=123456&transId=AB12-CD34-EF56&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y&amount=10000&test=1" \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Accept: application/x-www-form-urlencoded'

refundPos

Refundácia terminálovej platby
Metóda pre refundáciu je určená pre už založené a preplatené terminálové 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.
Ak platba nebola dokončená a je v stave pending, je možné využiť metódu storno platby. Serverové API nemusia mať záznam o platbe ihneď k dispozícii. Preto je vhodné najskôr zavolať refundáciu z pokladne na termináli. A volanie API využiť v prípade, že nemožno refundáciu zavolať z pokladne na termináli.
Pre využitie tejto metódy je nutné najskôr v Klientskom portáli nastaviť v sekcii Nastavenie obchodu - Terminály pri danom termináli povolenej IP adresy, z ktorých sa budú refundácie vykonávať.

Request Body schema: application/x-www-form-urlencoded

Refundácia terminálovej platby

merchant required	string identifikátor e-shopu v systéme Comgate - nájdete V Klientskom portáli v sekcii Nastavenie obchodov - Terminály
secret required	string heslo pre komunikáciu na pozadí
vs required	string variabilný symbol platby
amount required	string čiastka refundácie - môže byť v plnej alebo čiastočnej výške transakcie
date required	string dátum vykonania transakcie

Responses

Response Schema: application/x-www-form-urlencoded

code required	integer 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
message required	string

Request samples

cURL
PHP
Java
Python
C#

# You can also use wget
curl -X POST https://payments.comgate.cz/v1.0/refundPos \
--data "&merchant=123456&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y&vs=7654321&amount=10000&date=2000-02-22" \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Accept: application/x-www-form-urlencoded'

capturePreauth

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.

Request Body schema: application/x-www-form-urlencoded

Potvrdenie predbežnej autorizácie

merchant required	string identifikátor e-shopu v systéme Comgate
transId required	string unikátny alfanumerický identifikátor (kód) transakcie (transactionId)
secret required	string heslo pre komunikáciu na pozadí
amount	string čiastka predautorizácie, ktorá má byť z karty strhnutá - môže byť v plnej alebo čiastočnej výške transakcie

Responses

Response Schema: application/x-www-form-urlencoded

code required	integer 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
message required	string

Request samples

cURL
PHP
Java
Python
C#

# You can also use wget
curl -X POST https://payments.comgate.cz/v1.0/capturePreauth \
--data "&merchant=123456&transId=AB12-CD34-EF56&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y" \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Accept: application/x-www-form-urlencoded'

cancelPreauth

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.

Request Body schema: application/x-www-form-urlencoded

Zrušenie predautorizácie

merchant required	string identifikátor e-shopu v systéme Comgate
transId required	string unikátny alfanumerický identifikátor (kód) transakcie (transactionId)
secret required	string heslo pre komunikáciu na pozadí

Responses

Response Schema: application/x-www-form-urlencoded

code required	integer 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
message required	string

Request samples

cURL
PHP
Java
Python
C#

# You can also use wget
curl -X POST https://payments.comgate.cz/v1.0/cancelPreauth \
--data "&merchant=123456&transId=AB12-CD34-EF56&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y" \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Accept: application/x-www-form-urlencoded'

transferList

Metóda transferList slúži na získanie informácie, aké prevody boli uskutočnené v rámci daného dňa.

Request Body schema: application/x-www-form-urlencoded

merchant required	string identifikátor e-shopu v systéme Comgate
secret required	string heslo pre komunikáciu na pozadí
date required	string uveďte dátum uskutočnenia prevodu
test	boolean Default: false ak vyplníte true, metóda vráti vopred definovaný vzorový prevod

Responses

Response Schema: application/json

Array

transferId	integer
transferDate	string <date>
accountCounterparty	string
accountOutgoing	string
variableSymbol	string

Request samples

cURL
PHP
Java
Python
C#

# You can also use wget
curl -X POST https://payments.comgate.cz/v1.0/transferList \
--data "&merchant=123456&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y&date=2023-03-22" \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Accept: application/x-www-form-urlencoded'

Response samples

Content type

application/json

[{"transferId": 1234567,
"transferDate": "2023-01-25",
"accountCounterparty": "0/0000",
"accountOutgoing": "123456789/0000",
"variableSymbol": "12345678"
}
]

singleTransfer

Metóda singleTransfer zobrazuje detailné informácie ku konkrétnemu bankovému prevodu. Povinný parameter 'transferId' získa obchodník pomocou metódy transferList.

Request Body schema: application/x-www-form-urlencoded

merchant required	string identifikátor e-shopu v systéme Comgate
secret required	string heslo pre komunikáciu na pozadí
transferId required	string uveďte prevody, ktoré boli uskutočnené v rámci daného dňa. Zoznam získate pomocou metódy transferList.
test	boolean Default: false vhodné na testovanie - Ak je hodnota true, vrátia sa detaily k vopred definovaným vzorovým prevodom

Responses

Response Schema: application/json

Array

typ	integer
Merchant	string
Datum založení	string
Datum zaplacení	string
Datum převodu	string
Měsíc fakturace	string
ID Comgate	string
Metoda	string
Produkt	string
Popis	string
E-mail plátce	string
Variabilní symbol platby	string
Variabilní symbol převodu	string
ID od klienta	string
Měna	string
Potvrzená částka	string
Převedená částka	string
Poplatek celkem	string
Poplatek mezibankovní	string
Poplatek asociace	string
Poplatek zpracovatel	string
Typ karty	string

Request samples

cURL
PHP
Java
Python
C#

# You can also use wget
curl -X POST https://payments.comgate.cz/v1.0/singleTransfer \
--data "&merchant=123456&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y&transferId=1234567" \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Accept: application/x-www-form-urlencoded'

Response samples

Content type

application/json

[{"typ": 1,
"Merchant": "123456",
"Datum založení": "2023-01-06 14:11:30",
"Datum zaplacení": "2023-01-06 14:21:30",
"Datum převodu": "2023-01-10",
"Měsíc fakturace": null,
"ID Comgate": "AAAA-BBBB-CCCC",
"Metoda": "Card payment",
"Produkt": null,
"Popis": "description eshop payment",
"E-mail plátce": "name.lastname@email.cz",
"Variabilní symbol platby": "123456789",
"Variabilní symbol převodu": "123456789",
"ID od klienta": "1234",
"Měna": "EUR",
"Potvrzená částka": "10,00",
"Převedená částka": "10,00",
"Poplatek celkem": "0,35",
"Poplatek mezibankovní": "0,25",
"Poplatek asociace": "0,25",
"Poplatek zpracovatel": "-0,15",
"Typ karty": "EU_UNREGULATED"
}
]

csvSingleTransfer

Vďaka metóde csvSingleTransfer si možno stiahnuť denný výpis vo formáte CSV.

Request Body schema: application/x-www-form-urlencoded

merchant required	string identifikátor e-shopu v systéme Comgate
secret required	string heslo pre komunikáciu na pozadí
transferId required	string Uveďte prevody, ktoré boli uskutočnené v rámci daného dňa. Zoznam získate pomocou metódy transferList.
download	string Ak 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.
test	boolean Default: false Ak je hodnota true, vráti ukážkový CSV súbor.

Responses

Response Schema: application/json

nazev	string Názov stiahnutého súboru CSV
csv	string Súbor CSV s kódovaním Base64

Request samples

cURL
PHP
Java
Python
C#

# You can also use wget
curl -X POST https://payments.comgate.cz/v1.0/csvSingleTransfer \
--data "&merchant=123456&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y&transferId=5217530&download=false" \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Accept: application/x-www-form-urlencoded'

Response samples

Content type

application/json

{"nazev": "vypis-YYYY-MM-DD.csv",
"csv": "base64 encoded csv"
}

aboSingleTransfer

Vďaka metóde aboSingleTransfer si možno stiahnuť denný výpis vo formáte ABO.

Request Body schema: application/x-www-form-urlencoded

merchant required	string identifikátor e-shopu v systéme Comgate
secret required	string heslo pre komunikáciu na pozadí
transferId required	string uveďte prevody, ktoré boli uskutočnené v rámci daného dňa. Zoznam získate pomocou metódy transferList.
download	string Ak 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.
type	string Parameter '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'.
encoding	string Default: "utf8" Kódovanie znakov môže byť utf8 alebo win1250. Ak hodnota nie je vyplnená, predvolená hodnota parametra je utf8.
test	boolean Default: false Ak je hodnota true, vráti ukážkový ABO súbor.

Responses

Response Schema: application/json

nazev	string názov súboru
abo	string base64 kódovaný súbor abo/gpc

Request samples

cURL
PHP
Java
Python
C#

# You can also use wget
curl -X POST https://payments.comgate.cz/v1.0/aboSingleTransfer \
--data "&merchant=123456&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y&transferId=transfer_id&download=true&type=v1" \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Accept: application/x-www-form-urlencoded'

Response samples

Content type

application/json

{"nazev": "vypis-YYYY-MM-DD.gpc",
"abo": "base64_encoded_abo_file"
}

csvDownload

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.

Request Body schema: application/x-www-form-urlencoded

merchant required	string identifikátor e-shopu v systéme Comgate
secret required	string heslo pre komunikáciu na pozadí
date required	string povinný len za jeden deň
test	boolean Default: false Ak je hodnota true, vráti ukážkový CSV súbor vo formáte ZIP.

Responses

Response Schema: application/zip

string <binary>

Request samples

cURL
PHP
Java
Python
C#

# You can also use wget
curl -X POST https://payments.comgate.cz/v1.0/csvDownload \
--data "&merchant=123456&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y&date=YYYY-MM-DD" \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Accept: application/x-www-form-urlencoded'

aboDownload

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.

Request Body schema: application/x-www-form-urlencoded

merchant required	string identifikátor e-shopu v systéme Comgate
secret required	string heslo pre komunikáciu na pozadí
date required	string povinný len za jeden deň
type	string Parameter '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'.
encoding	string Kódovanie znakov môže byť utf8 alebo win1250. Ak hodnota nie je vyplnená, predvolená hodnota parametra je utf8.
test	boolean Default: false Ak je hodnota true, vráti ukážkový CSV súbor vo formáte ZIP.

Responses

Response Schema: application/zip

string <binary>

Request samples

cURL
PHP
Java
Python
C#

# You can also use wget
curl -X POST https://payments.comgate.cz/v1.0/aboDownload \
--data "&merchant=123456&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y&date=YYYY-MM-DD" \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Accept: application/x-www-form-urlencoded'

methods

Získanie povolených metód
Metóda na získanie nastavenia, ktoré má e-shop povolené v Comgate Platobnom Systéme. Touto metódou možno získať zoznam dostupných platobných metód na realizáciu platieb.
V odpovedi sa nachádza XML alebo JSON, podľa zvoleného parametra. Obidva formáty majú rovnakú úroveň zanorenia.

Request Body schema: application/x-www-form-urlencoded

Získanie platobných metód

merchant required	string identifikátor e-shopu v systéme Comgate
secret required	string heslo pre komunikáciu na pozadí
type	string Formát vrátených dát ('xml' alebo 'json'). Pokiaľ nebude vyplnené, použije sa 'xml'.
lang	string Výber, v akom jazyku budú opisy metód. Povolené hodnoty sú 'bg', 'cs', 'da', 'de', 'el', 'en', 'es', 'et', 'fi', 'fr', 'hr', 'hu', 'it', 'lt', 'lv', 'nl', 'no', 'pl', 'pt', 'ro', 'si', 'sk', 'sv', 'vi'. Pokiaľ nebude vyplnené, použije sa 'cs'.
curr	string Vyplnením parametra na hodnoty CZK alebo EUR dôjde k vráteniu metód, ktoré podporujú zadanú menu (CZK, EUR, PLN, HUF, USD, GBP, RON, NOK, SEK).
country	string Kód krajiny ('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', 'SE', 'US'), parameter slúži na obmedzenie výberu možných spôsobov pre zadanú krajinu.
price	integer <int32> Cena za výrobok v centoch alebo halieroch. Pre menu HUF nemôžete zadať cenu s desatinnými miestami. V tomto prípade musí cena vždy končiť 00. 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. 1 000 000 CZK; 40 000 EUR; 170 000 PLN; 12 500 000 HUF; 45 000 USD; 35 000 GBP; 190 000 RON; 400 000 NOK; 390 000 SEK.
initRecurring	boolean Default: false Príznak pre iniciačnej transakcie pre opakované platby. Len pre Klientov, ktorí majú službu povolenú.
verification	boolean Default: false Parameter overovacej platby, v prípade požiadavky na založenie overovacej platby (hodnota ‘true’) nie je nutné posielať parameter ‘initRecurring’.
preauth	boolean Default: false 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.
expirationTime	string Dĺžka expirácie platby. Povolená hodnota je celé číslo nasledované písmenom zvolenej časovej jednotky: 'm' (minúty), 'h' (hodiny) alebo 'd' (dni). Napríklad '30m' (30 minút) alebo '10h' (10 hodín) alebo '2d' (2 dni). Jednotky nemožno kombinovať. Výsledná dĺžka musí byť v rozmedzí 30 minút až 7 dní.
embedded	boolean Parameter 'embedded' slúži na filtrovanie metód v prípade, že sa brána bude zobrazovať v iframe. Dôjde k odfiltrovaniu platobných metód, ktoré nie je možné na platobnej bráne v iframe zobraziť. Pokiaľ zobrazujete platobnú bránu v iframe, použite 'embedded=true'.
userAgent	string Parameter 'userAgent' slúži na identifikáciu webového prehliadača zákazníka. Odfiltruje platobné metódy nekompatibilné s daným zariadením.

Responses

Response Schema: application/json

required

Array of objects

Dostupné metódy

Array

id	string ID metódy
group	string Skupina metódy
groupLabel	string Popis skupiny metódy
name	string Názov metódy
name_short	string Krátky názov metódy
description	string Popis metódy
logo	string Logo metódy
logo_240	string 240px logo metódy
cblogo	string Centrované väčšie logo metódy
clogo	string Centrované logo metódy
sblogo	string Štvorcové väčšie logo metódy
slogo	string Štvorcové logo metódy

Response Schema: application/json

required

Array of objects

Chyba

Array

code	string
message	string návratový kód metódy a opis chyby: 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
extraMessage	string upresnenie chybového hlásenia

Request samples

cURL
PHP
Java
Python
C#

# You can also use wget
curl -X POST https://payments.comgate.cz/v1.0/methods \
--data "&merchant=123456&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y&type=json" \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Accept: application/x-www-form-urlencoded'

Response samples

Content type

application/json

{"methods": [{"id": "string",
"group": "string",
"groupLabel": "string",
"name": "string",
"name_short": "string",
"description": "string",
"logo": "string",
"logo_240": "string",
"cblogo": "string",
"clogo": "string",
"sblogo": "string",
"slogo": "string"
}
]
}

status

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

Request Body schema: application/x-www-form-urlencoded

Získať stav platby

merchant required	string identifikátor e-shopu v systéme Comgate
transId required	string unikátny alfanumerický identifikátor (kód) transakcie (transactionId)
secret required	string heslo pre komunikáciu na pozadí

Responses

Response Schema: application/x-www-form-urlencoded

code required	string Návratový kód metódy
message required	string 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:
merchant required	string identifikátor e-shopu v systéme Comgate
test required	string Hodnota 'true' znamená, že platba bola založená ako testovacia, hodnota 'false' znamená produkčnú verziu.
price required	string cena za výrobok v centoch alebo halieroch
curr required	string kód meny podľa ISO 4217
label required	string krátky opis produktu (1 – 16 znakov)
refId required	string referencia platby v systéme e-shopu
payerId	string identifikátor Platiteľa v systéme e-shopu
method	string použitá metóda platby, z tabuľky platobných metód
account	string identifikátor bankového účtu e-shopu, na ktorý Comgate prevedie peniaze
email required	string kontaktný email na Platiteľa
name	string Identifikátor produktu - podľa tejto položky je potom možné sa zorientovať v štatistikách platieb Comgate platobného systému.
transId required	string unikátny alfanumerický identifikátor (kód) transakcie (transactionId)
secret required	string heslo pre komunikáciu na pozadí
status required	string 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	string odovzdanie mena účtu patriacemu Platiteľovi
payerAcc	string odovzdanie čísla účtu Platiteľa
fee	string ak má e-shop nastavené automatické strhávanie poplatku za platbu, bude v tomto poli spočítaný poplatok za transakciu v centoch alebo halieroch, inak bude pole nadobúdať hodnotu 'unknown'
vs	string variabilný symbol platby (nie je vždy k dispozícii)
cardValid	string expirácia karty platiteľa dostupná pri opakovaných iniciačných platbách
cardNumber	string čiastočné číslo karty platiteľa dostupné pri opakovaných iniciačných platbách
appliedFee	integer Výška príplatku aplikovaná za neregulované typy kariet.
appliedFeeType	string Typ príplatku aplikovaného za neregulované typy kariet ako je 'EU_UNREGULATED', 'NON_EU_BUSINESS', 'NON_EU_CONSUMER' aj nepríplatkový 'EU_CONSUMER'.

Request samples

cURL
PHP
Java
Python
C#

# You can also use wget
curl -X POST https://payments.comgate.cz/v1.0/status \
--data "&merchant=123456&transId=AB12-CD34-EF56&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y" \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Accept: application/x-www-form-urlencoded'