Protokol API platební brány

Specifikace HTTP POST protokolu

Propojení mezi eshopem a platební branou ComGate je realizované pomocí přesměrování plátce z eshopu na platební bránu. Po provedení platby je plátce přesměrován zpět do eshopu. Zároveň na pozadí probíhá komunikace mezi serverem eshopu a serverem platební brány (server - server). Detailní popis komunikačního protokolu naleznete níže na této stránce. Další související informace naleznete na stránkách, které popisují proces platby z pohledu uživatele a eshopu, počáteční nastavení v klientském portálu, doporučený způsob testování integrace platební brány nebo detailní popis napojení na EET.

Ukázková implementace v jazyce PHP ke stažení zde.

Průběh platby

Založení platby – volitelné

Krok založení platební brány je volitelný, je však vhodné ho implementovat v případě, kdy požadujete jistotu zabezpečeného založení platby. Vynechání implementace tohoto kroku je možné v případě, kdy jednotlivé platby nepotřebujete v systému identifikovat, ale stačí vám informace, že vám někdo zaplatil určitou částku. Je to vhodné například při implementaci dárcovských příspěvků nebo dobíjení prostředků na virtuální účet zákazníka, kdy vás zajímá jen, kdo dobíjel a jakou částku, ale nepotřebujete rozlišovat jednotlivá dobití zákazníka nebo dobití omezovat na minimální částku atd. Pro klasický eshop, kde platíte za konkrétní zboží, je však vynechání tohoto kroku nevhodné.

Platbu eshop zakládá HTTP požadavkem na server platební brány. Parametry platby, včetně unikátního referenčního čísla platby, jsou předány jako POST parametry HTTP protokolu. Tato komunikace probíhá mezi serverem Klienta a serverem platební brány. Plátce ji nevidí a nemůže měnit parametry platby. Server platební brány vrátí Klientovi unikátní identifikátor transaction ID (identifikátor v ComGate platebním systému) a URL adresu, na kterou má přesměrovat Plátce.

Příklad založení platby na pozadí – HTTP request:
POST /v1.0/create HTTP/1.1 Host: payments.comgate.cz Content-Type: application/x-www-form-urlencoded; charset=utf-8 merchant=merchant_com&price=10000&curr=CZK&label=Beatles%20-0%Help!&refId=2010102600&cat=DIGITAL&method=ALL&prepareOnly=true&secret=ZXhhbXBsZS5jb206QUJDeHl6

Příklad založení platby na pozadí – HTTP response:
HTTP/1.1 200 OK Content-Type: application/x-www-form-urlencoded; charset=utf-8 code=0&message=OK&transId=AB12-EF34-IJ56&redirect=https%3A%2F%2Fpayments.comgate.cz%2Fclient%2Finstructions%2F%3Fid%3DABCDEFGHIJ

Komunikace mezi systémem Klienta a platební bránou je zabezpečena pomocí hesla a IP whitelistu (přístup je povolen pouze z IP adres systému Klienta). Nezbytné je použití protokolu HTTPS, který znemožňuje prozrazení hesla při případném odposlouchávání komunikace. Heslo je předáváno jako POST parametr (nikoliv GET parametr) proto, aby se neukládalo v logu komunikace webového serveru.

Přesměrování na web platební brány

Pokud byla platba založena v předchozím kroku na pozadí, zajistí eshop přesměrování plátce na adresu, kterou vrátil platební bráně v HTTP odpovědi. Přesměrování se obvykle provádí odesláním HTTP odpovědi 302:

HTTP odpověď 302
HTTP/1.1 302 Found Location: https://payments.comgate.cz/client/instructions?id=ABCDEFGHIJ

V případě vynechání prvního kroku založení platby na pozadí je platba založena až při přesměrování Plátce z webu Klienta na server platební brány nebo odesláním webového formuláře z webu Klienta na server platební brány. Parametry platby, včetně unikátního referenčního čísla platby, jsou předány jako GET nebo POST parametry HTTP protokolu.

Příklad založení platby přesměrováním (odesláním webového formuláře) – HTTP request
POST /v1.0/create HTTP/1.1 Host: payments.comgate.cz Content-Type: application/x-www-form-urlencoded; charset=utf-8 merchant=merchant_com&price=10000&curr=CZK&label=Beatles%20-20Help!&refId=2010102600&cat=DIGITAL&method=ALL

Předání výsledku platby na pozadí (push) – povinné

Implementace této části vám zajistí automatické předání informace o stavu každé platební transakce přímo na váš server v okamžiku, kdy je stav platby známý. Tento krok je možné vynechat v případě, že Vám pro zjištění informací o provedených platbách stačí e-mailová notifikace či ruční vyhledání.

Výsledek platby je Klientovi předán HTTP požadavkem ze serveru platební brány na server Klienta. Identifikátory a výsledek platby jsou předány jako POST parametry HTTP protokolu. Tato komunikace probíhá na pozadí.

Plátce je přesměrován na webové stránky Klienta a identifikátory platby jsou předány jako GET parametry HTTP protokolu. Odeslání zboží nebo služby Plátci musí být vázáno na předání výsledku platby na pozadí, nikoliv na výsledné přesměrování Plátce na webové stránky Klienta, protože informace předané přesměrováním může Plátce snadno podvrhnout.

Příklad předání výsledku platby na pozadí – HTTP request
POST /handler.php HTTP/1.1 Host: eshop.com Content-Type: application/x-www-form-urlencoded; charset=utf-8 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

Příklad předání výsledku platby na pozadí – HTTP response
HTTP/1.1 200 OK Content-Type: application/x-www-form-urlencoded; charset=utf-8 code=0&message=OK

Komunikace mezi systémem Klienta a serverem platební brány je zabezpečena pomocí hesla a IP whitelistu. Přístup musí být povolen pouze z IP adresy serveru platební brány. Rozsahy IP adres jsou definovány v sekci Zabezpečení. Je povinné použít protokol HTTPS, který znemožňuje prozrazení hesla při případném odposlouchávání komunikace. Heslo je předáváno jako POST parametr (nikoliv GET parametr) proto, aby se neukládalo v logu komunikace webového serveru.

Eshop na svojí straně zajistí, že zboží (služba) poskytnuté v rámci zaplacené transakce (identifikované pomocí unikátního transaction ID) bude vydáno Plátci pouze jednou (i při opakovaném předání výsledku stejné platby na server Klienta).

Přesměrování Plátce na web Klienta

Plátce je na základě stavu platby přesměrován na jedno ze tří URL, které eshop zvolil při aktivaci služby. Identifikátory platby jsou předány jako GET parametry HTTP protokolu. Systém klienta musí být schopen ošetřit dvě základní situace:

při přesměrování Plátce na web Klienta výsledek platby ještě není známý. Platba je ve stavu PENDING. Tato situace je naprosto běžná a eshop ji nesmí Plátci prezentovat jako chybu. Systém čeká buď na připsání platby na bankovní účet, nebo na potvrzení od Poskytovatele platby. Konečný výsledek platby se eshop dozví později buď předáním výsledku platby na pozadí, nebo emailem, nebo v klientském portálu.
pokud se platební brána dozví výsledek platby okamžitě po provedení platby Plátcem, pak je Plátce směrován na příslušné URL (PAID nebo CANCELLED). Jestliže eshop implementoval předávání výsledku platby na pozadí, pak se přesměrování na web Klienta provede až po úspěšném předání výsledku platby na pozadí. Plátci nelze odeslat zboží nebo službu, kterou objednal, pouze na základě URL použité pro přesměrování, protože Plátce by mohl výsledek platby podvrhnout změnou URL ve webovém prohlížeči.

Příklad přesměrování Plátce na web Klienta – HTTP request
GET /result_ok.php?refId=2010102600&transId=AB12-EF34-IJ56 HTTP/1.1 Host: eshop.com

Stavy plateb

PENDING – platba byla založená, finální výsledek platby zatím není známý.
PAID – Plátce úspěšně dokončil platbu – je možné vydat zboží, resp. zpřístupnit službu.
CANCELLED – platba nebyla zaplacena, zboží nebude vydáno, resp. služba nebude poskytnuta.

Platbu lze považovat za zaplacenou pouze ve stavu PAID. Stav PENDING není koncový a může po něm následovat stav CANCELLED.

API protokol - platební brána ComGate

Zabezpečení

Komunikace mezi ComGate platebním systémem a e-shopem probíhá třemi způsoby.

serverová část e-shopového řešení se jako klient připojuje k serverové části platební brány a volá metody pro založení platby, získání stavu platby na pozadí, potvrzení předautorizace, zrušení předautortizace a získání seznamu platebních metod
serverová část platební brány se jako klient připojuje k serverové části e-shopového řešení a volá metodu pro předání výsledku platby na pozadí
prohlížeč plátce (uživatele) je přesměrován z e-shopu na platební bránu a následně z platební brány zpět do e-shopu.

Ve všech třech případech je nezbytné použití šifrovaného protokolu HTTPS. Platební brána podporuje pouze bezpečné nastavení TLS/SSL protokolu s následujícími povolenými šiframi: https://github.com/cloudflare/sslconfig/blob/master/conf

V případě komunikace server-server je komunikace zabezpečena pomocí hesla (secret) a nastavení IP whitelistu. Nastavení těchto parametrů je možné provést v prostředí klientského portálu.

Zakládaní plateb je předřazená služba Cloudflare. Seznam povolených IP adres Cloudflare naleznete zde: https://www.cloudflare.com/ips-v4

Rozsah IP adres používaný systémem ComGate je definován jako 89.185.236.55/32. Tento rozsah se používá pouze pro předání výsledku platby na pozadí.

Další typy karetních transakcí

Předautorizace

Platební brána umožňuje zadávat, potvrzovat a rušit předautorizace plateb kartou. Založení platby probíhá standardně, pouze je potřeba uvést parametr preauth=true. Poté plátce projde stejným procesem jako v případě normální platby. Poté, co zadá své údaje na platební bráně, je na jeho platební kartě zarezervována příslušná částka. Podle výsledku této operace přechází buď do zvláštního stavu AUTHORIZED, nebo v případě zamítnutí do stavu CANCELLED. Tento stav je ohlášen na pozadí obvyklým postupem popsaným výše.

Aby byly peníze skutečně strženy, volá e-shop funkci pro potvrzení předautorizace. Pokud se peníze mají uvolnit (např. není možné naplnit podmínky kupní smlouvy), volá funkci pro zrušení předautorizace.

Obrázek API protokol - Potvrzení platby- platební brána ComGate

API protokol - platební brána ComGate

Opakované platby (card-on-file)

Platební brána umožňuje zadávání opakovaných plateb, to je plateb na jedno kliknutí. První (iniciační) platba probíhá standardním procesem s přesměrováním na platební bránu, následující platby už probíhají kompletně na pozadí. Systém tak umožňuje plátci zaplatit během několika sekund bez nutnosti vyplňovat informace o platební kartě.

Tato funkcionalita je dostupná na vyžádání. V případě opakovaných plateb na začátku zakládáme iniciační platbu, která se zakládá jako běžná platba, pouze se v požadavku nachází navíc parametr initRecurring - metoda create. Následné opakované platby jsou už zakládány metodou recurring a jsou vázány na ComGate ID iniciační transakce. Toto ID musí být v systému Klienta vázáno na konkrétního Plátce.

Po založení opakované platby nedochází k přesměrování Plátce na platební bránu, protože celý proces probíhá na pozadí, Klientovi je pouze předán stav založení platby, a ten následně zobrazí tento stav Plátci.

Ověřovací transakce

Pokud chce e-shop využít opakovaných plateb v budoucnu, ale chce Plátce „registrovat“ nyní, může využít ověřovací transakce. Při vyplnění parametru verification hodnotou „true“ dojde k založení iniciační transakce, která je ihned po zaplacení automaticky refundována.

Z pohledu opakovaných plateb se tato transakce jeví jako běžná iniciační, další platby jsou tedy opět navázány na tuto. Z důvodu limitací ze strany bank není možné kombinovat opakované platby a předautorizace.

Rekurentní platby (recurring)

Rekuretní platby, tzn. opakované platby s předem definovanou částkou a periodou (např. měsíčí, týdenní apod.) lze realizovat pomocí služby Opakované platby, která je popsána předchozích odstavcích.

Předvyplněné karetní údaje

Platební brána umožňuje zapamatování karetních údajů Plátce tak, že při následné platbě na platební bráně dojde k automatickému předvyplnění čísla karty a údaje o platnosti, pro dokončení platby postačí zadat CVV kód. V tomto případě dochází na přesměrování Plátce na web platební brány, narozdíl od funkčnosti Opakovaných plateb, kde následná platba může proběhnout plně na pozadí, bez účasti Plátce.

Tato funkcionalita je dostupná na vyžádání. Pro její využití je nutné při založení platby vyplnit parametr PayerId. Obchodník (merchant) musí zajistit ověření a přihlášení Plátce v rámci eshopu.

Popis API metod

Založení platby

Přístup je chráněn validací IP adresy a integrita předávaných dat je zajištěna použitím HTTPS protokolu. URL metody: https://payments.comgate.cz/v1.0/create

Parametry volání
Parametr	Typ	Povinný	Popis
merchant	string	A	identifikátor e-shopu v systému ComGate - naleznete v Klientském portálu v sekci Nastaveni obchodů - Propojeni obchodu.
test	boolean	N	Hodnota „true“ znamená, že platba bude založena jako testovací, hodnota „false“ znamená produkční verzi. Pokud parametr chybí, založí se platba jako produkční.
country	string	N	kód země („CZ“, „SK“, „PL“, „ALL“), pokud parametr chybí, použije se „CZ“, parametr slouží k omezení výběru platebních metod na ComGate platební bráně
price	integer	A	Cena za produkt v centech nebo haléřích. Musí být min. 10 CZK (včetně), 1 EUR, 10 PLN, 100 HUF, 1 USD, 1 GBP max. neomezeno.
curr	string	A	kód měny dle ISO 4217, standardně „CZK“
label	string	A	krátký popis produktu (1-16 znaků); dle této položky je možné filtrovat platby v Klientském portálu
refId	string	A	parametr vhodný k zadaní variabilního symbolu nebo čísla objednávky na straně Klienta (nemusí být unikátní, tzn., že lze založit více plateb se stejným refId); v Klientském portálu a denním csv. je parametr označen jako ID Klienta
payerId	string	N	Identifikátor Plátce v systému Klienta. Identifikátor musí být ověřen například přihlášením Plátce do systému Klienta pomocí hesla, pokud není, tak parametr nevyplňujte. Používá se při platbě kartou, kde platební brána ukládá čísla karet Plátců, takže při další platbě Plátce nemusí číslo karty znovu zadávat. Tato funkce musí být pro konkrétního Klienta povolena v systému karetního zpracovatele.
method	string	A	metoda platby, z tabulky platebních metod, hodnota „ALL“ v případě, že si má metodu vybrat plátce, nebo jednoduchý výraz s výběrem metod (popsáno níže)
account	string	N	identifikátor bankovního účtu Klienta, na který ComGate Payments převede peníze. Pokud parametr nevyplníte, použije se výchozí účet Klienta. Seznam účtů Klienta najdete na https://portal.comgate.cz/
email	string	A	kontaktní email na Plátce (pro účely případné reklamace)
phone	string	N	kontaktní telefon na Plátce (pro účely případné reklamace)
name	string	N	identifikátor produktu - tato položka se nachází v denním csv. Klienta pod názvem Produkt
lang	string	N	kód jazyka (ISO 639-1), ve kterém budou Plátci zobrazeny instrukce pro dokončení platby, standardně povolené hodnoty („cs”, „sk“, „en”, "pl", "fr", "ro" ), pokud parametr chybí, použije se „cs“, v případě požadavku na další jazyk, kontaktujte platby-podpora@comgate.cz
prepareOnly	boolean	N	V případě zakládání platby na pozadí vyplňte „true“. Při zakládání platby přesměrováním vyplňte buď „false“ nebo parametr nepoužívejte.
secret	string	N	V případě zakládání platby na pozadí vyplňte heslo pro komunikaci na pozadí. Při zakládání platby přesměrováním parametr ponechte prázdný, nebo jej nepoužívejte.
preauth	boolean	N	V případě požadavku na předautorizaci platby kartou nastavte na „true“. V případě normální platby vyplňte „false“ nebo parametr nepoužívejte. Pouze pro platby kartou.
initRecurring	boolean	N	Příznak pro založení iniciační transakce pro opakované platby. Pouze pro Klienty, kteří mají službu povolenou.
verification	boolean	N	Parametr ověřovací platby, v případě požadavku na založení ověřovací platby (hodnota „true“) není nutné posílat parametr initRecurring.
embedded	boolean	N	Parametr se používá při platbě kartou na bráně ČSOB (metoda CARD_CZ_CSOB_2). Hodnota „true“ zajistí zobrazení karetní brány v iframe. Pokud chcete zobrazit standardní bránu, parametr nevyplňujte nebo zadejte hodnotu „false“. Tato funkcionalita je na speciální povolení.
eetReport	boolean	N	Příznak odeslání dat do EET. Pokud je vyplněno, přetěžuje nastavení EET v konfiguraci obchodu v Klientském Portálu.
eetData	JSON	N	Struktura s daty pro zaevidování platby do EET. Odpovídá parametrům ze specifikace protokolu EET. Pokud má e-shop nastaveno odesílání tržby do EET a parametr nebude vyplněn, použije se výchozí nastavení z konfigurace v Klientském Portálu.

Server platební brány odpovídá pouze v případě, že je platba zakládána na pozadí. Všechny parametry jsou urlencoded, stejně jako v případě HTTP requestu. Pokud je platba založena přesměrováním (parametr prepareOnly je “false”), pak server platební brány rovnou přesměruje Plátce na příslušnou URL nebo zobrazí chybovou zprávu.

Parametry odpovědi
parametr	typ	povinný	popis
code	integer	A	návratový kód metody a popis chyby: 0 OK 1100 neznámá chyba 1102 zadaný jazyk není podporován 1103 nesprávně zadaná metoda 1104 nelze načíst platbu 1107 cena platby není podporovaná 1200 databázová chyba 1301 neznámý e-shop 1303 propojení nebo jazyk chybí 1304 neplatná kategorie 1305 chybí popis produktu 1306 vyberte správnou metodu 1308 vybraný způsob platby není povolen 1309 nesprávná částka 1310 neznámá měna 1311 neplatný identifikátor bankovního účtu Klienta 1316 e-shop nemá povolené opakované platby 1317 neplatná metoda – nepodporuje opakované platby 1319 nelze založit platbu, problém na straně banky 1399 neočekávaný výsledek z databáze 1400 chybný dotaz 1500 neočekávaná chyba
message	string	A
transId	string	N	unikátní alfanumerický identifikátor (kód) transakce, který bude zobrazen Plátci v různých fázích platby
redirect	string	N	URL stránky, kam má být Plátce přesměrován pro realizaci platby

Příklad založení platby přesměrováním (odesláním webového formuláře) – HTTP request
POST /v1.0/create HTTP/1.1 Host: payments.comgate.cz Content-Type: application/x-www-form-urlencoded; charset=utf-8 merchant=merchant_com&price=10000&curr=CZK&label=Beatles%20-%20Help!&refId=2010102600&cat=DIGITAL&method=ALL

Příklad založení platby na pozadí – HTTP request
POST /v1.0/create HTTP/1.1 Host: payments.comgate.cz Content-Type: application/x-www-form-urlencoded; charset=utf-8 merchant=merchant_com&price=10000&curr=CZK&label=Beatles%20-%20Help!&refId=2010102600&cat=DIGITAL&method=ALL&prepareOnly=true&secret=ZXhhbXBsZS5jb206QUJDeHl6

Příklad založení platby na pozadí – HTTP response
HTTP/1.1 200 OK Content-Type: application/x-www-form-urlencoded; charset=utf-8 code=0&message=OK&transId=AB12-EF34-IJ56&redirect= https%3A%2F%2Fpayments.comgate.cz%2Fclient%2Finstructions%2Findex%3Fid%3DABCDEFGHIJ

Výběr platební metody

Doporučujeme v rámci nákupního procesu v e-shopu zobrazit plátci výběr platebních metod a na základě jeho výběru založit platbu s vyplněním parametru method na jednu konkrétní hodnotu (např. platba kartou nebo platba převodem z ČS apod). Potom dojde k přímému zobrazení stránky poskytovatele konkrétní platby (banka).

V případě, že parametr method není vyplněn jednou konkrétní hodnotou, dojde k zobrazení nabídky platebních metod na platební bráně. Nabídka platebních metod může být specifikována jednoduchým výrazem, který se zadává do parametru method. Výraz se vždy vyhodnocuje na základě metod, které má e-shop povolené.

Povolené oddělovače identifikátorů metod jsou „+“ pro přičtení metody a „-“ pro odečtení metody z/do výběru.

Příklad:

BANK_ALL + CARD_CZ_CS – BANK_CZ_KB = všechny bankovní metody včetně platby kartou bez bankovního tlačítka Komerční banky

BANK_CZ_CS_P + BANK_CZ_KB + BANK_CZ_RB = pouze bankovní tlačítka u České spořitelny, Komerční banky a Reiffeisen Bank (pouze tyto 3 na rozdíl od BANK_ALL, který by vybral všechny povolené bankovní metody e-shopu)

Platební brána umožňuje, aby Plátce měl při výběru platební metody v prostředí brány ComGate předvybranou jednu konkrétní platební metodu. Stačí, aby byl plátce přesměrován na platební bránu pomocí získaného platebního odkazu s přidaným parametrem „method“ s vybranou metodou.

Platební odkaz tedy může vypadat následovně:
https://payments.comgate.cz/client/instructions/index?id=ABCDEFGHIJ&method=CARD_CZ_CS

Po příchodu na bránu bude mít Plátce již zaškrtnutou metodu CARD_CZ_CS, výběr metody ale dále zůstane na něm. Tato funkce má smysl pouze pro platby založené s metodou ALL, BANK_ALL nebo s vlastním výběrem metody.

Opakované platby

V případě, že e-shop vyplní parametr initRecurring, dojde k založení iniciační transakce k opakovaným platbám. Na ComGate ID této transakce je pak možné zakládat opakované platby. Parametry odpovědi se v tomto případě nijak nemění. Založení iniciační platby je možné pouze pro e-shopy, kteří mají službu povolenou, a při použití platby kartou.

Verifikační, ověřovací platby

Při vyplnění parametru verification na hodnotou „true“ dojde k založení ověřovací transakce. Jakmile Plátce platbu uhradí, dojde k její automatické refundaci, není tedy nutné následně platbu refundovat ručně. Ověřovací transakce jinak funguje stejně jako iniciační transakce, tzn. je možné zakládat opakované platby s využitím jejího ComGate ID.

Iframe karetní brány

Platební brána pro platby kartou umožňuje zobrazení optimalizované pro iframe. Tato funkcionalita je vhodná v případě, že nechcete Plátce přesměrovávat na platební bránu, ale zobrazit ji v rámci svého systému. Tato funkcionalita je dostupná na vyžádání.

Zasílání tržby do EET

Do systému EET musí obchodník evidovat každou platbu provedenou kartou nebo v hotovosti. Daňoví plátci musí posílat detail daně, neplátci DPH pouze celkovou částku. Další informace jsou obsaženy v EET řešení.

Nejprve se obchodník musí zaregistrovat do EET a stáhnout si certifikát pro zabezpečenou komunikaci. Následně obchodník provede konfiguraci propojení s EET v rozhraní klientského portálu.

Pokud je EET správně nastaveno v klientském portálu, pak je možné přejít k založení platby. V rámci plateb EET se rozlišují dva režimy:

Automatický (výchozí) režim umožňuje obchodníkovi posílat platby do EET, aniž by musel implementovat něco navíc do komunikačního protokolu platební brány ComGate. Tento režim slouží neplátcům DPH a plátcům DPH, kteří prodávají zboží pouze v jedné daňové sazbě odpovídající nastavení v klientském portálu. Pokud je platba provedena v zahraniční měně, bude do EET zaevidovaná v Kč a jako kurz pro přepočet se použije kurz dané měny vyhlášený ČNB z předchozího dne.
Rozšířený režim přináší nutnost upravit komunikační protokol platební brány ComGate. Do protokolu bude obchodník posílat kompletní rozpad částky pro EET v parametru eetData (viz příklad níže, názvy parametrů jsou dle specifikace EET). Tento režim je nutný pro všechny, kdo prodávají zboží ve více sazbách DPH, cestovní služby, prodávají a uplatňují vouchery nebo prodávají použité zboží. Data se předávají ve formátu JSON, částky jsou uváděny v haléřích.

Popis JSON struktury s daty EET (eetData):
Parametr	typ	povinný	Popis
celk_trzba	integer	A	Celková částka tržby
zakl_nepodl_dph	integer	N	Celková částka plnění osvobozených od DPH, ostatních plnění
zakl_dan1	integer	N	Celkový základ daně se základní sazbou DPH
dan1	integer	N	Celková DPH se základní sazbou
zakl_dan2	integer	N	Celkový základ daně s první sníženou sazbou DPH
dan2	integer	N	Celková DPH s první sníženou sazbou
zakl_dan3	integer	N	Celkový základ daně s druhou sníženou sazbou DPH
dan3	integer	N	Celková DPH s druhou sníženou sazbou
cest_sluz	integer	N	Celková částka v režimu DPH pro cestovní službu
pouzit_zboz1	integer	N	Celková částka v režimu DPH pro prodej použitého zboží se základní sazbou
pouzit_zboz2	integer	N	Celková částka v režimu DPH pro prodej použitého zboží s první sníženou sazbou
pouzit_zboz3	integer	N	Celková částka v režimu DPH pro prodej použitého zboží s druhou sníženou
urceno_cerp_zuct	integer	N	Celková částka plateb určená k následnému čerpání nebo zúčtování
cerp_zuct	integer	N	Celková částka plateb, které jsou následným čerpáním nebo zúčtováním

Příklad struktury 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"
}

Předání výsledku platby na pozadí (push)

Platební brána předává výsledný stav platby HTTP požadavkem na server e-shopu. Parametry tohoto volání specifikují detail právě dokončené platby.

URL metody: https://adresa-vaseho-e-shopu/absdefg - metoda je volána na server e-shopu

Parametry volání
parametr	Typ	povinný	Popis
merchant	string	A	identifikátor e-shopu v systému ComGate
test	boolean	A	hodnota „true“ znamená, že platba byla založena jako testovací, hodnota „false“ znamená produkční verzi.
price	integer	A	cena za produkt v centech nebo haléřích
curr	string	A	kód měny dle ISO 4217
label	string	A	krátký popis produktu (1-16 znaků)
refId	string	A	reference platby (variabilní symbol, číslo objednávky) v systému e-shopu
payerId	string	N	identifikátor Plátce v systému e-shopu
payerName	string	N	předání jména účtu patřící Plátci
payerAcc	string	N	předání čísla účtu Plátce
method	string	N	použitá metoda platby, z tabulky platebních metod
account	string	N	identifikátor bankovního účtu e-shopu, na který ComGate Payments převede peníze
email	string	A	kontaktní email na Plátce
phone	string	N	kontaktní telefon na Plátce
name	string	N	identifikátor produktu - dle této položky je možné vyhledávat ve statistikách plateb ComGate platebního systému.
transId	string	A	unikátní alfanumerický identifikátor (kód) transakce (transactionId)
secret	string	A	heslo pro komunikaci na pozadí
status	string	A	aktuální stav transakce, hodnoty „PAID“ - platba byla úspěšně zaplacena „CANCELLED“ - platba nebyla dokončena korektně a je zrušena „AUTHORIZED” - vyžádaná předautorizace proběhla úspěšně
fee	string	N	pokud má e-shop nastavené automatické strhávání poplatku za platbu, bude v tomto poli spočítaný poplatek za transakci, jinak bude pole nabývat hodnoty „unknown“
eetData	JSON	N	Struktura s daty po zaevidování platby do EET.

Parametry odpovědi
Parametr	Typ	povinný	Popis
code	integer	A	návratový kód metody a popis chyby: systém očekává návratový kód 0 a popis „OK“, v případě, že výsledek platby byl v pořádku přijat

Příklad předání výsledku platby na pozadí – HTTP request
POST /handler.php HTTP/1.1 Host: eshop.com Content-Type: application/x-www-form-urlencoded; charset=utf-8 merchant=merchant_com&test=false&price=10000&curr=CZK&label=Beatles%20-%20Help!&refId=2010102600&cat=DIGITAL&method=CARD&email=info%40customer.com&phone=%2B420123456789&transId=AB12-EF34-IJ56&secret=ZXhhbXBsZS5jb206QUJDeHl6&status=PAID

Příklad předání výsledku platby na pozadí – HTTP response
HTTP/1.1 200 OK Content-Type: application/x-www-form-urlencoded; charset=utf-8code=0&message=OK

Popis JSON struktury s daty EET (eetData):
parametr	typ	povinný	Popis
fik	string	N	Fiskální identifikační kód poplatníka
bkp	string	A	Bezpečnostní kód poplatníka
pkp	string	N	Podpisový kód poplatníka zakódovaný v base64
celk_trzba	integer	A	Celková částka tržby
poradove_cislo	integer	A	Pořadové číslo účtenky
zakl_nepodl_dph	integer	N	Celková částka plnění osvobozených od DPH, ostatních plnění
zakl_dan1	integer	N	Celkový základ daně se základní sazbou DPH
dan1	integer	N	Celková DPH se základní sazbou
zakl_dan2	integer	N	Celkový základ daně s první sníženou sazbou DPH
dan2	integer	N	Celková DPH s první sníženou sazbou
zakl_dan3	integer	N	Celkový základ daně s druhou sníženou sazbou DPH
dan3	integer	N	Celková DPH s druhou sníženou sazbou
cest_sluz	integer	N	Celková částka v režimu DPH pro cestovní službu
pouzit_zboz1	integer	N	Celková částka v režimu DPH pro prodej použitého zboží se základní sazbou
pouzit_zboz2	integer	N	Celková částka v režimu DPH pro prodej použitého zboží s první sníženou sazbou
pouzit_zboz3	integer	N	Celková částka v režimu DPH pro prodej použitého zboží s druhou sníženou
urceno_cerp_zuct	integer	N	Celková částka plateb určená k následnému čerpání nebo zúčtování
cerp_zuct	integer	N	Celková částka plateb, které jsou následným čerpáním nebo zúčtováním
datum_trzby	string	A	Datum tržby ve formátu YYYY-MM-DD HH24:MI:SS
ic_poplatnika	string	N	IČ poplatníka
dic_poplatnika	string	A	DIČ poplatníka
id_provozovny	string	A	Označení provozovny
id_pokladny	string	A	Označení pokladního zařízení
adresa_poplatnika	string	N	Adresa poplatníka
rezim_trzby	string	A	Režim, ve kterém byla tržba uskutečněna

Příklad struktury 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ískání stavu platby na pozadí (get)

Analogická funkce pro předání výsledku platby na pozadí, pouze iniciovaná Obchodem. Nenahrazuje však předání stavu platby na pozadí, její implementace je stále povinná. URL metody: https://payments.comgate.cz/v1.0/status

Parametry volání
parametr	typ	povinný	Popis
merchant	string	A	identifikátor e-shopu v systému ComGate
transId	string	A	unikátní alfanumerický identifikátor (kód) transakce (transactionId)
secret	string	A	heslo pro komunikaci na pozadí

Parametry odpovědi
parametr	typ	povinný	popis
code	integer	A	návratový kód metody a popis chyby: 0 OK 1100 neznámá chyba 1200 databázová chyba 1400 chybný dotaz 1500 neočekávaná chyba V případě code=0 jsou v odpovědi následující parametry:
message	string	A
merchant	string	A	identifikátor e-shopu v systému ComGate
test	boolean	A	Hodnota „true“ znamená, že platba byla založena jako testovací, hodnota „false“ znamená produkční verzi.
price	integer	A	cena za produkt v centech nebo haléřích
curr	string	A	kód měny dle ISO 4217
label	string	A	krátký popis produktu (1-16 znaků)
refId	string	A	reference platby v systému e-shopu
payerId	string	N	identifikátor Plátce v systému e-shopu
method	string	N	použitá metoda platby, z tabulky platebních metod
account	string	N	identifikátor bankovního účtu e-shopu, na který ComGate Payments převede peníze
email	string	A	kontaktní email na Plátce
phone	string	N	kontaktní telefon na Plátce
name	string	N	identifikátor produktu - dle této položky je potom možné se zorientovat ve statistikách plateb ComGate platebního systému.
transId	string	A	unikátní alfanumerický identifikátor (kód) transakce (transactionId)
secret	string	A	heslo pro komunikaci na pozadí
status	string	A	aktuální stav transakce, hodnoty „PENDING“ - platba je založena, finální výsledek není známý „PAID“ - platba byla úspěšně zaplacena „CANCELLED“ - platba nebyla dokončena korektně a je zrušena „AUTHORIZED” - vyžádaná předautorizace proběhla úspěšně
fee	string	N	pokud má e-shop nastavené automatické strhávání poplatku za platbu, bude v tomto poli spočítaný poplatek za transakci, jinak bude pole nabývat hodnoty „unknown“
eetData	JSON	N	Struktura s daty po zaevidování platby do EET. Stejná struktura, jako v případě

Příklad získání stavu platby – HTTP request
POST /v1.0/status HTTP/1.1 Host: payments.comgate.cz Content-Type: application/x-www-form-urlencoded; charset=utf-8 merchant=merchant_com&transId=XA52-3R2M-EB9C&secret=ZXhhbXBsZS5jb206QUJDeHl6

Příklad získání stavu platby – HTTP response
HTTP/1.1 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=info%40customer.com&phone=%2B420123456789&transId=AB12-EF34-IJ56&secret=ZXhhbXBsZS5jb206QUJDeHl6&status=PAID

Refundace platby - pouze s povolením

Metoda pro refundaci již založené a proplacené platby. Je možné provést jak částečnou (refundovaná částka je nižší, než částka platby), tak plnou (částka refundace je rovna částce platby). Daná částka bude převedena zpět na účet plátce. URL metody: https://payments.comgate.cz/v1.0/refund

Parametry volání
parametr	typ	povinný	Popis
merchant	string	A	identifikátor e-shopu v systému ComGate
transId	string	A	unikátní alfanumerický identifikátor (kód) transakce (transactionId)
secret	string	A	heslo pro komunikaci na pozadí
amount	string	A	částka refundace - může být v plné nebo částečné výši transakce
curr	string	N	měna refundace, pokud není vyplněno, použije se „CZK“
test	string	N	Hodnota „true“ znamená, že refundace bude založena jako testovací. Refundace a platba bude prověřena standardní cestou, pouze nedojde k refundaci původní platby. Pokud je vyplněno „false“ nebo je parametr prázdný, je založena ostrá refundace. Testovací transakce mohou být refundovány pouze testovací refundací.
refId	string	N	parametr vhodný k zadaní identifikačního čísla refundace na straně Klienta (nemusí být unikátní, tzn., že lze založit více refundací se stejným refId); v Klientském portálu v sekci refundací a denním csv u refundace je parametr označen jako ID Klienta. V případě, že tento parametr k refundaci není připojen, k platbě se zobrazí původní refId založené platby.

Parametry odpovědi
parametr	typ	povinný	popis
code	integer	A
message	string	A	návratový kód metody a popis chyby: 0 OK 1100 neznámá chyba 1200 databázová chyba 1400 chybný dotaz 1401 refundovaná platba je ve stavu CANCELLED 1500 neočekávaná chyba

Příklad založení refundace – HTTP request:
POST /v1.0/refund HTTP/1.1 Host: payments.comgate.cz Content-Type: application/x-www-form-urlencoded; charset=utf-8 merchant=merchant_com&transId=XA52-3R2M-EB9C&secret=ZXhhbXBsZS5jb206QUJDeHl6amount=100

Příklad založení refundace – HTTP response:
HTTP/1.1 200 OK Content-Type: application/x-www-form-urlencoded; charset=utf-8 code=0&message=OK

Získání povolených platebních metod

Metoda pro získání nastavení, které má e-shop povolené v ComGate Payments Platebním Systému. Touto metodou lze získat seznam dostupných platebních metod pro realizaci plateb. URL metody: https://payments.comgate.cz/v1.0/methods

Parametry volání
parametr	typ	povinný	Popis
merchant	string	A	identifikátor e-shopu v systému ComGate
secret	string	A	heslo pro komunikaci na pozadí
type	string	N	Formát vrácených dat („xml“ nebo „json“). Pokud nebude vyplněno, použije se „xml“.
lang	string	N	Výběr, v jakém jazyce budou popisy metod. Povolené hodnoty jsou „cs“, „en“, „pl“. Pokud nebude vyplněno, použije se „cs“.
curr	string	N	Vyplněním parametru na hodnoty CZK nebo EUR dojde k vrácení metod, které podporují zadanou měnu.
country	string	N	kód země („CZ“, „SK“), parametr slouží k omezení výběru platebních metod pro zadanou zemi

V odpovědi se nachází XML nebo JSON, podle zvoleného parametru. Oba formáty mají stejnou úroveň zanoření.

Parametry odpovědi
element	typ	povinný	popis
/methods/method/id	string	A	dostupná metoda platby
/methods/method/name	string	A	název metody, ve zvoleném jazyce
/methods/method/description	string	A	delší popis metody, ve zvoleném jazyce
/methods/method/logo	string	A	HTTP link na logo metody

V případě chyby mají data následující tvar.

Parametry odpovědi
element	typ	povinný	popis
/error/code	string	A	návratový kód metody a popis chyby:
/error/message	string	A	0 OK 1100 neznámá chyba 1200 databázová chyba 1300 e-shop nemá žádnou metodu 1400 chybný dotaz 1500 neočekávaná chyba
/error/extraMessage	string	N	upřesnění chybového hlášení

Příklad získání povolených platebních metod – HTTP request:
POST /v1.0/methods HTTP/1.1 Host: payments.comgate.cz Content-Type: application/x-www-form-urlencoded; charset=utf-8 merchant=merchant_com&secret=ZXhhbXBsZS5jb206QUJDeHl6&type=xml&lang=cs

Příklad získání povolených platebních metod – HTTP response:
HTTP/1.1 200 OK Content-Type: application/xml; charset=utf-8 <?xml version="1.0" encoding="UTF-8"?> <methods> <method> <id>BANK_CZ_AB</id> <name>Air Bank</name> <description>Bankovní převod pro majitele účtu u Air Bank.</description> <logo>https://payments.comgate.cz/assets/images/logos/BANK_CZ_AB.png</logo> </method> <method> <id>BANK_CZ_CTB</id> <name>Citibank</name> <description>Bankovní převod pro majitele účtu u Citibank.</description> <logo>https://payments.comgate.cz/assets/images/logos/BANK_CZ_CTB.png</logo> </method> <method> <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> </method> <method> <id>BANK_CZ_FB</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> </method> </methods>

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"methods": [
{
"id": "BANK_CZ_AB",
"name": "Air Bank",
"description": "Bankovní převod pro majitele účtu u Air Bank.",
"logo": "https://payments.comgate.cz/assets/images/logos/BANK_CZ_AB.png"
},
{
"id": "BANK_CZ_CTB",
"name": "Citibank",
"description": "Bankovní převod pro majitele účtu u Citibank.",
"logo": "https://payments.comgate.cz/assets/images/logos/BANK_CZ_CTB.png"
},
{
"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"
}
]
}

Příklad získání povolených platebních metod – HTTP response v případě chyby:
HTTP/1.1 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/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
"error": {
"code": 1400,
"message": "Unauthorized access!"
}
}

Opakované platby – založení druhé a následující platby

Založení opakované platby do platební brány je možné pouze při akceptaci karet pro e-shopy, kteří mají službu povolenou. První (iniciační) platba probíhá standardní cestou (viz Založení platby). Proces založení druhé a každé další platby probíhá kompletně na pozadí, tyto platby jsou vázány na iniciační přes ComGate ID iniciační platby. Toto ID se musí nacházet v požadavku v parametru initRecurringId. Plátci je v systému e-shopu jako výsledek zobrazen stav platby. URL metody: https://payments.comgate.cz/v1.0/recurring

Parametry volání
parametr	typ	povinný	Popis
merchant	string	A	identifikátor e-shopu v systému ComGate
country	string	N	kód země („CZ“, „SK“, „PL“, „ALL“), pokud parametr chybí, použije se „CZ“
test	boolean	N	Hodnota „true“ znamená, že platba bude založena jako testovací, hodnota „false“ znamená produkční verzi. Pokud parametr chybí, založí se platba jako produkční.
price	integer	A	Cena za produkt v centech nebo haléřích. Musí být min. 10 CZK (včetně), max. neomezeno.
curr	string	A	kód měny dle ISO 4217, standardně „CZK“
label	string	A	krátký popis produktu (1-16 znaků)
refId	string	A	reference platby v systému e-shopu (nemusí být unikátní, tzn., že lze založit více plateb se stejným refId)
payerId	string	N	Identifikátor Plátce v systému e-shopu. Identifikátor musí být ověřen například přihlášením Plátce do e-shopu pomocí hesla, pokud není, tak parametr nevyplňujte. Používá se při platbě kartou, kde platební brána ukládá čísla karet Plátců, takže při další platbě Plátce nemusí číslo karty znovu zadávat. Tato funkce musí být pro konkrétní e-shop povolena v systému platební brány.
account	string	N	Identifikátor bankovního účtu e-shopu, na který ComGate převede peníze. Pokud parametr nevyplníte, použije se výchozí účet e-shopu. Seznam účtů e-shopu najdete na https://portal.comgate.cz/
email	string	A	kontaktní email na Plátce (pro účely případné reklamace)
phone	string	N	kontaktní telefon na Plátce (pro účely případné reklamace)
name	string	N	Identifikátor produktu - dle této položky je potom možné se zorientovat ve statistikách plateb ComGate platebního systému.
prepareOnly	boolean	A	Parametr musí nabývat hodnoty „true“. Opakované platby nelze zakládat přesměrováním.
secret	string	A	Heslo pro komunikaci na pozadí.
initRecurringId	string	A	ComGate ID iniciační platby.
eetReport	boolean	N	Příznak odeslání dat do EET. Pokud je vyplněno, přetěžuje nastavení EET v konfiguraci obchodu v Klientském Portálu.
eetData	JSON	N	Struktura s daty pro zaevidování platby do EET. Odpovídá parametrům ze specifikace protokolu EET. Pokud má e-shop nastaveno odesílání tržby do EET a parametr nebude vyplněn, použije se výchozí nastavení z konfigurace v Klientském Portálu.

Všechny parametry jsou urlencoded, stejně jako v případě HTTP requestu pro založení standardní platby. V odpovědi se nachází parametr code, podle kterého e-shop určí, jaký výsledek zobrazí plátci. Code = 0 znamená úspěch, platba byla založena, jakýkoliv jiný kód znamená chybu a tudíž nezaložení platby.

Parametry odpovědi
parametr	typ	povinný	popis
code	integer	A	návratový kód metody a popis chyby: 0 OK 1100 neznámá chyba 1102 zadaný jazyk není podporován 1103 nesprávně zadaná metoda 1104 nelze načíst platbu 1200 databázová chyba 1301 neznámý e-shop 1303 propojení nebo jazyk chybí 1304 neplatná kategorie 1305 chybí popis produktu 1308 vybraný způsob platby není povolen 1309 nesprávná částka 1310 neznámá měna 1311 neplatný identifikátor bankovního účtu e-shopu 1316 e-shop nemá povolené opakované platby 1317 neplatná metoda - nepodporuje opakované platby 1318 iniciační platba nebyla nalezena 1319 nelze založit platbu, problém na straně banky 1399 neočekávaný výsledek z databáze 1400 chybný dotaz 1500 neočekávaná chyba
message	string	A
transId	string	N	unikátní alfanumerický identifikátor (kód) transakce, který bude zobrazen Plátci v různých fázích platby

Příklad založení platby na pozadí – HTTP request
POST /v1.0/recurring HTTP/1.1 Host: payments.comgate.cz Content-Type: application/x-www-form-urlencoded; charset=utf-8 merchant=merchant_com&price=10000&curr=CZK&label=Beatles%20-%20Help!&email= email%40platce.cz&refId=2010102600&prepareOnly=true&secret=ZXhhbXBsZS5jb206QUJDeHl6&initRecurringId=AB12-EF34-IJ56

Příklad založení platby na pozadí – HTTP response
HTTP/1.1 200 OK Content-Type: application/x-www-form-urlencoded; charset=utf-8 code=0&message=OK&transId=AB34-EF56-XY78

Potvrzení předautorizace

V případě, že e-shop založil platbu s požadavkem na předautorizaci platby kartou (s využitím parametru preauth=true), voláním této funkce vyžádá stržení peněz, které byly v rámci předautorizace zablokovány. Volání lze použít pouze pro platby, u nichž byl ohlášen stav AUTHORIZED. URL metody: https://payments.comgate.cz/v1.0/capturePreauth

Parametry volání
parametr	typ	povinný	popis
merchant	string	A	identifikátor e-shopu v systému ComGate
transId	string	A	unikátní alfanumerický identifikátor (kód) transakce (transactionId)
secret	string	A	heslo pro komunikaci na pozadí

Parametry odpovědi
parametr	typ	povinný	popis
code	integer	A
message	string		návratový kód metody a popis chyby: 0 OK 1100 neznámá chyba 1104 nelze načíst platbu 1200 databázová chyba 1301 neznámý e-shop 1303 propojení nebo jazyk chybí 1399 neočekávaný výsledek z databáze 1400 chybný dotaz 1500 neočekávaná chyba

Příklad potvrzení předautorizace – HTTP request:
POST /v1.0/capturePreauth HTTP/1.1 Host: payments.comgate.cz Content-Type: application/x-www-form-urlencoded; charset=utf-8 merchant=merchant_com&transId=XA52-3R2M-EB9C&secret=ZXhhbXBsZS5jb206QUJDeHl6

Příklad potvrzení předautorizace – HTTP response:
HTTP/1.1 200 OK Content-Type: application/x-www-form-urlencoded; charset=utf-8 code=0&message=OK

Zrušení předautorizace

V případě, že e-shop založil platbu s požadavkem na předautorizaci platby kartou (s využitím parametru preauth=true), voláním této funkce dává najevo, že peníze, které byly v rámci předautorizace zablokovány, nechce inkasovat a peníze se na kartě mohou opět uvolnit. Volání lze použít pouze pro platby, u nichž byl ohlášen stav AUTHORIZED. URL metody: https://payments.comgate.cz/v1.0/cancelPreauth

Parametry volání
parametr	typ	povinný	Popis
merchant	string	A	identifikátor e-shopu v systému ComGate
transId	string	A	unikátní alfanumerický identifikátor (kód) transakce (transactionId)
secret	string	A	heslo pro komunikaci na pozadí

parametr	typ	povinný	popis
code	integer	A
message	string		návratový kód metody a popis chyby: 0 OK 1100 neznámá chyba 1104 nelze načíst platbu 1200 databázová chyba 1301 neznámý e-shop 1303 propojení nebo jazyk chybí 1399 neočekávaný výsledek z databáze 1400 chybný dotaz 1500 neočekávaná chyba

Příklad zrušení předautorizace – HTTP request:
POST /v1.0/cancelPreauth HTTP/1.1 Host: payments.comgate.cz Content-Type: application/x-www-form-urlencoded; charset=utf-8 merchant=merchant_com&transId=XA52-3R2M-EB9C&secret=ZXhhbXBsZS5jb206QUJDeHl6

Příklad zrušení předautorizace – HTTP response:
HTTP/1.1 200 OK Content-Type: application/x-www-form-urlencoded; charset=utf-8 code=0&message=OK

Číselníky

Stavy plateb
stav	Popis
PENDING	Platba byla založená, finální výsledek platby zatím není známý
PAID	Plátce úspěšně zaplatil platbu – je možné vydat zboží, resp. zpřístupnit službu.
CANCELLED	Platba nebyla zaplacena, zboží nebude vydáno, resp. služba nebude poskytnuta. Ve výjimečných případech se může stát, že tento stav bude změněn na stav PAID.
AUTHORIZED	Předautorizace platby proběhla úspěšně (peníze na kartě plátce byly zablokovány). Čeká se na další požadavek, kterým bude potvrzena nebo zrušena.

Platební metody
typ	Popis	identifikátor
	Platební metodu si vybere Plátce v rozcestníku	ALL
Platební karta	Poskytovatel automaticky	CARD_ALL (nebo CARD)
Bankovní platby	Banku Plátce vybere v rozcestníku ComGate Payments	BANK_ALL
	Bankovní převod Air Bank	BANK_CZ_AB
	Bankovní převod ČSOB	BANK_CZ_CSOB
	Bankovní převod Equa Bank	BANK_CZ_EB
	Bankovní převod jiných bank	BANK_CZ_OTHER
	Bankovní tlačítko Raiffeisen Bank	BANK_CZ_RB
	Bankovní tlačítko Komerční Banky	BANK_CZ_KB
	Bankovní tlačítko GE Money Bank	BANK_CZ_GE
	Bankovní tlačítko Sberbank CZ	BANK_CZ_VB
	Bankovní tlačítko FIO Banky	BANK_CZ_FB
	Bankovní tlačítko České spořitelny	BANK_CZ_CS_P
	Bankovní tlačítko mBank	BANK_CZ_MB_P
	Bankovní tlačítko ČSOB	BANK_CZ_CSOB_P
	Bankovní tlačítko era	BANK_CZ_PS_P
	Bankovní tlačítko UniCredit Bank	BANK_CZ_UC
	Bankovní tlačítko Slovenské spořiteľňy	BANK_SK_SP
	Bankovní tlačítko VÚB Banky	BANK_SK_VUB
	Bankovní tlačítko Tatra Banky	BANK_SK_TB
	Bankovní tlačítko ČSOB	BANK_SK_CSOB
	Bankovní tlačítko Poštovná Banka	BANK_SK_PB
	Bankovní převod Prima Bank	BANK_SK_DEXIA
	Bankovní převod Fio Banky	BANK_SK_FB
	Bankovní převod jiných bank	BANK_SK_OTHER
	Bankovní tlačítko Alior Bank	BANK_PL_ALR
	Bankovní tlačítko BGŻ BNP Paribas Polska	BANK_PL_BGZ
	Bankovní tlačítko Blik	BANK_PL_BL
	Bankovní tlačítko Bank Millennium	BANK_PL_BM
	Bankovní tlačítko Bank Ochrony Środowiska	BANK_PL_BOS
	Bankovní tlačítko Bank Pocztowy	BANK_PL_BP
	Bankovní tlačítko BPS	BANK_PL_BPS
	Bankovní tlačítko Banki Spółdzielcze	BANK_PL_BSP
	Bankovní tlačítko BZ WBK	BANK_PL_BZ
	Bankovní tlačítko Credit Agricole	BANK_PL_CA
	Bankovní tlačítko Citi Handlowy	BANK_PL_CH
	Bankovní tlačítko Deutsche Bank	BANK_PL_DB
	Bankovní tlačítko Eurobank	BANK_PL_EB
	Bankovní tlačítko GetIn Online	BANK_PL_GO
	Bankovní tlačítko Idea Bank	BANK_PL_IDB
	Bankovní tlačítko ING Bank Śląski	BANK_PL_ING
	Bankovní tlačítko Inteligo	BANK_PL_INT
	Bankovní tlačítko mBank	BANK_PL_MB
	Bankovní tlačítko Nest Bank	BANK_PL_NEB
	Bankovní tlačítko Noble Bank	BANK_PL_NOB
	Bankovní tlačítko Plus Bank	BANK_PL_PB
	Bankovní tlačítko Bank Pekao	BANK_PL_PEK
	Bankovní tlačítko PKO BP	BANK_PL_PKO
	Bankovní tlačítko Raiffeisen Polbank	BANK_PL_RB
	Bankovní tlačítko T-Mobile Usługi Bankowe	BANK_PL_TM
	Bankovní tlačítko Toyota Bank	BANK_PL_TOB
	Bankovní tlačítko Volkswagen Bank	BANK_PL_VWB

API pro stahování souborů

Seznam převodů v rámci dne

Metoda transferList slouží k získání informace, jaké převody byly uskutečněny v rámci daného dne.
URL metody: https://payments.comgate.cz/v1.0/transferList

Parametry volání
parametr	typ	povinný	popis
merchant	string	A	identifikátor e-shopu v systému ComGate
secret	string	A	heslo pro komunikaci na pozadí
date	string	A	metoda vrací převody za jeden den

Příklad získání seznamu převodů v rámci dne - HTTP request
POST /v1.0/transferList HTTP/1.1 Host: payments.comgate.cz Content-Type: application/x-www-form-urlencoded; charset=utf-8 merchant=135258&secret=wi9VplRz0UNqoxFqSM4udyxyA1ia5z32&date=2019-07-25

Příklad získání seznamu převodů v rámci dne - HTTP response
HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 [{"transferId":5211530,"transferDate":"2019-07-25","accountCounterparty":"0\/0000","accountOutgoing":"281481882\/0300","variableSymbol":"86616655"}]

Detaily ke konkrétnímu bankovnímu převodu

Metoda singleTransfer zobrazuje detailní informace ke konkrétnímu bankovnímu převodu.
Povinný parametr transferId získá obchodník pomocí metody transferList.
URL metody: https://payments.comgate.cz/v1.0/singleTransfer

Parametry volání
parametr	typ	povinný	popis
merchant	string	A	identifikátor e-shopu v systému ComGate
secret	string	A	heslo pro komunikaci na pozadí
transferId	string	A	detaily ke konkrétnímu bankovnímu převodu

Příklad získání detailu ke konkrétnímu bank. převodu - HTTP request
POST /v1.0/singleTransfer HTTP/1.1 Host: payments.comgate.cz Content-Type: application/x-www-form-urlencoded; charset=utf-8 merchant=135258&secret=wi9VplRz0UNqoxFqSM4udyxyA1ia5z32&transferId=5211530

Příklad získání detailu ke konkrétnímu bank. převodu - HTTP response
1 = platba
2 = refundace
3 = měsíční poplatek
4 = ostatní poplatky, chargebacky a ruční pohyby
5 = sumární řádek
HTTP/1.1 200 OK 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 soubor ke konkrétnímu bankovnímu převodu

Díky metodě csvSingleTransfer si lze stáhnout denní výpis ve formátu CSV.
URL metody: https://payments.comgate.cz/v1.0/csvSingleTransfer

Parametry volání
parametr	typ	povinný	popis
merchant	string	A	identifikátor e-shopu v systému ComGate
secret	string	A	heslo pro komunikaci na pozadí
transferId	string	A	detaily ke konkrétnímu bankovnímu převodu
download	string	N	pokud není vyplněno, nebo je false, tak vrací data : název souboru a jeho obsah; pokud je true, tak vrací rovnou CSV soubor

Příklad stahování výpisu ve formátu csv ke konkrétnímu bankovnímu převodu - HTTP request
POST /v1.0/csvSingleTransfer HTTP/1.1 Host: payments.comgate.cz Content-Type: application/x-www-form-urlencoded; charset=utf-8 merchant=135258&secret=wi9VplRz0UNqoxFqSM4udyxyA1ia5z32&transferId=5211530&download=false

Příklad stahování výpisu ve formátu csv ke konkrétnímu bankovnímu převodu - HTTP response
HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 { "nazev": "vypis-2019-07-25.csv", "csv": base64 encoded csv }

ABO výpis ke konkrétnímu bankovnímu převodu

Díky metodě aboSingleTransfer si lze stáhnout denní výpis ve formátu ABO.
URL metody: https://payments.comgate.cz/v1.0/aboSingleTransfer

Parametry volání
parametr	typ	povinný	popis
merchant	string	A	identifikátor e-shopu v systému ComGate
secret	string	A	heslo pro komunikaci na pozadí
transferId	string	A	detaily ke konkrétnímu bankovnímu převodu
download	string	N	pokud není vyplněno, nebo je false, tak vrací data : název souboru a jeho obsah; pokud je true, tak vrací rovnou CSV soubor

Příklad stahování rozpisu ABO ke konkrétnímu bankovnímu převodu - HTTP request
POST /v1.0/aboSingleTransfer HTTP/1.1 Host: payments.comgate.cz Content-Type: application/x-www-form-urlencoded; charset=utf-8 merchant=135258&secret=wi9VplRz0UNqoxFqSM4udyxyA1ia5z32&transferId=5211530&download=true

Příklad stahování rozpisu ABO ke konkrétnímu bankovnímu převodu - HTTP response
HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 { "nazev": "vypis-2019-07-25.gpc", "abo": base64 encoded abo/gpc file }

Stažení CSV souborů pro převody v rámci dne

Přímé stažení CSV souborů pro konkrétní den metodou csvDowload. Stažený soubor ve formátu ZIP bude obsahovat jeden nebo více souborů CSV, pokud je více převodů v rámci dne. Lze využít např. pro volání pomocí wget.
URL metody: https://payments.comgate.cz/v1.0/csvDownload

Parametry volání
parametr	typ	povinný	popis
merchant	string	A	identifikátor e-shopu v systému ComGate
secret	string	A	heslo pro komunikaci na pozadí
date	string	A	povinný pouze za jeden den

Příklad stahování csv pro převody v rámci dne - HTTP request
POST /v1.0/csvDownload HTTP/1.1 Host: payments.comgate.cz Content-Type: application/x-www-form-urlencoded; charset=utf-8 merchant=135258&secret=wi9VplRz0UNqoxFqSM4udyxyA1ia5z32&date=2019-07-25

Příklad stahování csv pro převody v rámci dne - HTTP response
HTTP/1.1 200 OK Content-Type: application/zip Content-Disposition: attachment; filename="vypis-csv-2019-07-25.zip" Content-Length: delka souboru ZIP soubor obsahující CSV k převodům za den v parametru ke stažení jako response

Stažení ABO souborů pro převody v rámci dne

Přímé stažení ABO souborů pro konkrétní den metodou aboDowload. Stažený soubor ve formátu ZIP bude obsahovat jeden nebo více souborů ABO.
Lze využít např. pro volání pomocí wget.
URL metody: https://payments.comgate.cz/v1.0/aboDownload

Parametry volání
parametr	typ	povinný	popis
merchant	string	A	identifikátor e-shopu v systému ComGate
secret	string	A	heslo pro komunikaci na pozadí
date	string	A	povinný pouze za jeden den

Příklad stahování ABO pro převody v rámci dne - HTTP request
POST /v1.0/aboDownload HTTP/1.1 Host: payments.comgate.cz Content-Type: application/x-www-form-urlencoded; charset=utf-8 merchant=135258&secret=wi9VplRz0UNqoxFqSM4udyxyA1ia5z32&date=2019-07-25

Příklad stahování ABO pro převody v rámci dne - HTTP response
HTTP/1.1 200 OK Content-Type: application/zip Content-Disposition: attachment; filename="vypis-csv-2019-07-25.zip" Content-Length: delka souboru ZIP soubor obsahující ABO k převodům za den v parametru ke stažení jako response

Přehled starých verzí protokolu je zde.