API metody platby (1.0)

create

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.

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.

Výběr platební metody
V rámci nákupního procesu je v e-shopu možné plátci zobrazit výběr platebních metod a na základě jeho výběru založit platbu s konkrétní metodou. Ve chvíli, kdy je plátci zobrazena platební brána, dojde k automatickému zobrazení předem vybrané platební metody. Nastavit vybranou platební metodu je možné vyplněním parametru 'method'. Prostřednictvím tohoto parametru je možné platební metody i různě filtrovat.
Více zde: https://apidoc.comgate.cz/metody-platebni-brany

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.

UPOZORNĚNÍ

URL adresa a struktura kódu založené platby se může měnit. Vždy použijte adresu, kterou vám vrátí API, a nijak do ní nezasahujte. Pokud chcete uložit kód platby, použijte parametr transId. Nikdy neparsujte data z konkrétních pozic v textu, mohou se též měnit.

Všechny hodnoty obsahující speciální znaky musí být v UTF-8.

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

Vytvořit novou platbu

merchant required	string identifikátor e-shopu v systému Comgate - naleznete v Klientském portálu v sekci Nastaveni obchodů - Propojeni obchodu.
test	boolean Default: true 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 Možné hodnoty: 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. Pro ostatní země použijte ALL. Pokud parametr chybí, použije se automaticky 'CZ'. Parametr slouží k omezení výběru platebních metod na platební bráně. Je potřeba aby byla zvolena správná kombinace parametrů 'country' a 'curr' (měna) pro daný region. Například pro zobrazení českých tlačítek a platby kartou v měně CZK zvolte kombinaci country=CZ a curr=CZK. U slovenských bankovních tlačítek a platby kartou v EUR zvolte country=SK a curr=EUR. Pro polská bankovní tlačítka a platbu kartou v PLN zvolte country=PL a curr=PLN. Pro ostatní cizí měny můžete použít parametr country=ALL nebo další kód země, který platební brána přijímá.
price required	integer <int32> Cena za produkt v centech nebo haléřích. U měny HUF nelze zadat cenu s desetinnými místy. V tomto případě musí cena vždy končit 00. Musí být 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 měny dle ISO 4217. K dispozici jsou měny: CZK, EUR, PLN, HUF, USD, GBP, RON, NOK, SEK.
label required	string Krátký popis produktu (1-16 znaků) – dle této položky je možné filtrovat platby v Klientském portálu.
refId required	string 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.
method required	string 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. Více zde: https://apidoc.comgate.cz/metody-platebni-brany
account	string Identifikátor bankovního účtu Klienta, na který Comgate 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 required	string Kontaktní email plátce. Povinný je pouze jeden z údajů emailová adresa nebo telefonní číslo.
phone required	string Telefonní číslo plátce v mezinárodním formátu +420777112233. Povinný je pouze jeden z údajů emailová adresa nebo telefonní číslo.
fullName required	string Jméno a příjmení plátce, např. Josef Novák.
billingAddrCity	string Fakturační adresa - město. (např. Hradec Králové).
billingAddrStreet	string Fakturační adresa - ulice. (např. Jiráskova 115).
billingAddrPostalCode	string Fakturační adresa - PSČ. (např. 50304).
billingAddrCountry	string Fakturační adresa - země, ve formátu ISO 3166 alpha-2 (např. CZ, SK, US, GB).
delivery	string Způsob doručení - jedna z dostupných možností: HOME_DELIVERY, PICKUP, ELECTRONIC_DELIVERY. Varianta PICKUP znamená všechna výdejní místa, výdejní boxy apod.
homeDeliveryCity	string Doručovací adresa - město. Vyplňuje se pouze v případě delivery=HOME_DELIVERY (např. Hradec Králové).
homeDeliveryStreet	string Doručovací adresa - ulice. Vyplňuje se pouze v případě delivery=HOME_DELIVERY (např. Štefanikova 421).
homeDeliveryPostalCode	string Doručovací adresa - PSČ. Vyplňuje se pouze v případě delivery=HOME_DELIVERY (např. 50341).
homeDeliveryCountry	string Doručovací adresa - země, ve formátu ISO 3166 alpha-2. Vyplňuje se pouze v případě delivery=HOME_DELIVERY (např. CZ, SK, US, GB).
category	string Kategorie produktu v košíku - jedna z dostupných možností, která nejvíce popisuje košík: PHYSICAL_GOODS_ONLY, OTHER. Varianta OTHER zahrnuje i dárkové karty, vouchery nebo služby.
name	string Identifikátor produktu – tato položka se nachází v denním csv. Klienta pod názvem Produkt.
lang	string Kód jazyka (ISO 639-1), ve kterém budou Plátci zobrazeny instrukce pro dokončení platby, standardně 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'), pokud parametr chybí, použije se 'cs', v případě požadavku na další jazyk, kontaktujte podpora@comgate.cz.
prepareOnly required	boolean Default: false 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. Jaký povolený způsob založení platby máte nastaven, zjistíte v Klientském portálu v sekci Integrace - Propojení obchodu.
secret required	string 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 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 Příznak pro založení iniciační transakce pro opakované platby. Pouze pro Klienty, kteří mají službu povolenou.
verification	boolean Parametr ověřovací platby, v případě požadavku na založení ověřovací platby (hodnota 'true') není nutné posílat parametr '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. Více o dynamické expiraci najdete v článku zde.
url_paid	string Individuální nastavení pro jednotlivé platby. Např. 'https://www.example.com/result.php?id=${id}&refId=${refId}'
url_cancelled	string Individuální nastavení pro jednotlivé platby. Např. 'https://www.example.com/result.php?id=${id}&refId=${refId}'
url_pending	string Individuální nastavení pro jednotlivé platby. Např. 'https://www.example.com/result.php?id=${id}&refId=${refId}'

Responses

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

code required	integer 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 required	string
transId	string Unikátní alfanumerický identifikátor (kód) transakce, který bude zobrazen Plátci v různých fázích platby.
redirect	string URL stránky, kam má být Plátce přesměrován pro realizaci 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 případě, že byla objednávka v e-shopu stornována a transakce nemá být plátcem dokončena, je možné využít storno platby. Na rozdíl od refundace musí být platba ve stavu očekávaná (pending).
Vzhledem k rychlosti zaplacení plateb může být platba již ve stavu zaplacená, v takovém případě se zobrazí chyba a je nutné využít metodu refundace.

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

Zrušení platby

merchant required	string identifikátor e-shopu v systému Comgate
transId required	string unikátní alfanumerický identifikátor (kód) transakce (transactionId)
secret required	string heslo pro komunikaci na pozadí

Responses

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

code required	integer návratový kód metody a popis chyby: 0 OK 1400 není možné přepnout platbu do cancel stavu (platba nenalezena, platba není ve stavu pending, neoprávněný pří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, zapamatování karetních údajů
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.

Následující opakované platby
Založení druhé a následující opakované platby do platební brány je možné pouze při akceptaci karet pro e-shopy, které 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.

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 a zaplacena, jakýkoliv jiný kód znamená chybu a tudíž nezaložení platby.

Rekurentní platby (recurring)
Rekurentí platby, tzn. opakované platby s předem definovanou částkou a periodou (např. měsíční, týdenní apod.) lze realizovat pomocí služby Opakované platby, která je popsána v předchozích odstavcích.
Testovací rekurentní platby (s výjimkou iniciační) založené s e-mailem 'recurring.cancelled@comgate.cz' budou automaticky označeny jako CANCELLED (nezaplacené)

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

merchant required	string identifikátor e-shopu v systému Comgate
test	boolean 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 required	string Cena za produkt v centech nebo haléřích. Musí být min. 10 CZK (včetně), max. neomezeno.
curr required	string kód měny dle ISO 4217, standardně 'CZK'
label required	string krátký popis produktu (1-16 znaků)
refId required	string Reference platby v systému e-shopu (nemusí být unikátní, tzn., že lze založit více plateb se stejným refId).
account	string 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/.
name	string Identifikátor produktu - dle této položky je potom možné se zorientovat ve statistikách plateb Comgate platebního systému.
secret required	string heslo pro komunikaci na pozadí
initRecurringId required	string Comgate ID iniciační platby

Responses

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

code required	integer 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 1320 neplatný email pro opakovanou platbu 1399 neočekávaný výsledek z databáze 1400 chybný dotaz 1500 neočekávaná chyba
message required	string
transId	string unikátní alfanumerický identifikátor (kód) transakce, který bude zobrazen Plátci v různých fázích 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

Refundace platby
Metoda pro refundaci je určena pro již založené a proplacené platby. Stav platby musí být zaplacená (paid). Je možné provést jak částečnou (refundovaná částka je nižší, než částka platby), tak plnou refundaci (částka refundace je rovna částce platby). Daná částka bude převedena zpět na účet plátce.
Pokud platba nebyla dokončena a je ve stavu pending, je možné využít metodu storno platby.

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

Vrácení platby

merchant required	string identifikátor e-shopu v systému Comgate
transId required	string unikátní alfanumerický identifikátor (kód) transakce (transactionId)
secret required	string heslo pro komunikaci na pozadí
amount required	string částka refundace – může být v plné nebo částečné výši transakce. Částka refundace se zadává v centech nebo haléřích. U měny HUF nelze zadat částku s desetinnými místy. V tomto případě musí částka vždy končit 00.
test	string 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 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.

Responses

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

code required	integer Návratový kód metody a popis chyby: 0 OK 1100 neznáma chyba 1200 databázová chyba 1400 chybný dotaz 1401 refundovaná platba je v stavu CANCELLED 1402 částka převyšuje povolenou 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

Refundace terminálové platby
Metoda pro refundaci je určena pro již založené a proplacené terminálové platby. Stav platby musí být zaplacená (paid). Je možné provést jak částečnou (refundovaná částka je nižší, než částka platby), tak plnou refundaci (částka refundace je rovna částce platby). Daná částka bude převedena zpět na účet plátce.
Pokud platba nebyla dokončena a je ve stavu pending, je možné využít metodu storno platby.
Serverové API nemusí mít záznam o platbě ihned k dispozici. Proto je vhodné nejprve zavolat refundaci z pokladny na terminálu. A volání API využít v případě, že nelze refundaci zavolat z pokladny na terminálu.
Pro využití této metody je nutné nejprve v Klientském portálu nastavit v sekci Nastavení obchodu - Terminály u daného terminálu povolené IP adresy, ze kterých se budou refundace provádět.

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

Refundace terminálové platby

merchant required	string identifikátor e-shopu v systému Comgate - naleznete V Klientském portálu v sekci Nastavení obchodů - Terminály
secret required	string heslo pro komunikaci na pozadí
vs required	string variabilní symbol platby
amount required	string částka refundace – může být v plné nebo částečné výši transakce
date required	string datum provedení transakce

Responses

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

code required	integer Návratový kód metody a popis chyby: 0 OK 1100 neznáma chyba 1200 databázová chyba 1400 chybný dotaz 1401 refundovaná platba je v stavu CANCELLED 1402 částka převyšuje povolenou 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 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. Je možné provést jak částečné stržení transakce (předautorizovaná částka je nižší, než částka platby), tak plné stržení (částka stržení je rovna částce platby). Volání lze použít pouze pro platby, u nichž byl ohlášen stav AUTHORIZED.

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

Potvrzení předběžné autorizace

merchant required	string identifikátor e-shopu v systému Comgate
transId required	string unikátní alfanumerický identifikátor (kód) transakce (transactionId)
secret required	string heslo pro komunikaci na pozadí
amount	string částka předautorizace, která má být z karty stržena - může být v plné nebo částečné výši transakce

Responses

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

code required	integer 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
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 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.

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

Zrušení předautorizace

merchant required	string identifikátor e-shopu v systému Comgate
transId required	string unikátní alfanumerický identifikátor (kód) transakce (transactionId)
secret required	string heslo pro komunikaci na pozadí

Responses

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

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

Metoda transferList slouží k získání informace, jaké převody byly uskutečněny v rámci daného dne.

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

merchant required	string identifikátor e-shopu v systému Comgate
secret required	string heslo pro komunikaci na pozadí
date required	string uveďte datum uskutečnění převodu
test	boolean Default: false pokud vyplníte true, metoda vrátí předem definovaný vzorový převod

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

Metoda singleTransfer zobrazuje detailní informace ke konkrétnímu bankovnímu převodu.
Povinný parametr 'transferId' získá obchodník pomocí metody transferList.

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

merchant required	string identifikátor e-shopu v systému Comgate
secret required	string heslo pro komunikaci na pozadí
transferId required	string uveďte převody, které byly uskutečněny v rámci daného dne. Seznam získáte pomocí Metoda transferList.
test	boolean Default: false vhodné pro testování - Pokud je honota true, vrátí se detaily k předem definovaným vzorovým převodům

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/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

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

csvSingleTransfer

Díky metodě csvSingleTransfer si lze stáhnout denní výpis ve formátu CSV.

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

merchant required	string identifikátor e-shopu v systému Comgate
secret required	string heslo pro komunikaci na pozadí
transferId required	string uveďte převody, které byly uskutečněny v rámci daného dne. Seznam získáte pomocí Metoda transferList.
download	string Pokud není vyplněno, nebo je false, tak vrací data : název souboru a jeho obsah; pokud je true, tak vrací rovnou CSV soubor.
test	boolean Default: false Pokud je hodnota true, vrátí ukázkový CSV soubor.

Responses

Response Schema: application/json

nazev	string Název staženého souboru CSV
csv	string Soubor CSV s kódování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

Díky metodě aboSingleTransfer si lze stáhnout denní výpis ve formátu ABO.

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

merchant required	string identifikátor e-shopu v systému Comgate
secret required	string heslo pro komunikaci na pozadí
transferId required	string uveďte převody, které byly uskutečněny v rámci daného dne. Seznam získáte pomocí Metoda transferList.
download	string Pokud není vyplněno, nebo je false, tak vrací data : název souboru a jeho obsah; pokud je true, tak vrací rovnou ABO soubor.
type	string parametr 'type' může nabývat hodnot 'v1' a 'v2'. Pod 'v1' získáte ABO verzi s poplatky uvedenými zvlášť ke každé platbě, pod 'v2' pak ABO s poplatkem souhrnným v jednom řádku. Pokud nebude parametr vyplněn, automaticky obdržíte typ 'v1'.
encoding	string Default: "utf8" Kódování znaků může mít hodnoty utf8 nebo win1250. Pokud není hodnota vyplněna je hodnota parametru defaultně ve formátu utf8.
test	boolean Default: false Pokud je hodnota true, vrátí ukázkový ABO soubor.

Responses

Response Schema: application/json

nazev	string název souboru
abo	string soubor abo/gpc v kódování base64

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

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.

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

merchant required	string identifikátor e-shopu v systému Comgate
secret required	string heslo pro komunikaci na pozadí
date required	string povinný pouze za jeden den
test	boolean Default: false Pokud je hodnota true, vrátí ukázkový CSV soubor ve formátu 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

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.

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

merchant required	string identifikátor e-shopu v systému Comgate
secret required	string heslo pro komunikaci na pozadí
date required	string povinný pouze za jeden den
type	string parametr 'type' může nabývat hodnot 'v1' a 'v2'. Pod 'v1' získáíte ABO verzi s poplatky uvedenými zvlášť ke každé platbě, pod 'v2' pak ABO s poplatek souhrným v jednom řádku. Pokud nebude parametr vyplněn, automaticky obdržíte typ 'v1'.
encoding	string Kódování znaků může mít hodnoty utf8 nebo win1250. Pokud není hodnota vyplněna je hodnota parametru defaultně ve formátu utf8.
test	boolean Default: false Pokud je hodnota true, vrátí ukázkový CSV soubor ve formátu 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ískání povolených metod
Metoda pro získání nastavení, které má e-shop povolené v Comgate Platebním Systému. Touto metodou lze získat seznam dostupných platebních metod pro realizaci plateb.
V odpovědi se nachází XML nebo JSON, podle zvoleného parametru. Oba formáty mají stejnou úroveň zanoření.

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

Získání platebních metod

merchant required	string identifikátor e-shopu v systému Comgate
secret required	string heslo pro komunikaci na pozadí
type	string Formát vrácených dat ('xml' nebo 'json'). Pokud nebude vyplněno, použije se 'xml'.
lang	string Výběr, v jakém jazyce budou popisy metod. Povolené hodnoty jsou 'bg', 'cs', 'da', 'de', 'el', 'en', 'es', 'et', 'fi', 'fr', 'hr', 'hu', 'it', 'lt', 'lv', 'nl', 'no', 'pl', 'pt', 'ro', 'si', 'sk', 'sv', 'vi'. Pokud nebude vyplněno, použije se 'cs'.
curr	string Vyplněním parametru na hodnoty CZK nebo EUR dojde k vrácení metod, které podporují zadanou měnu (CZK, EUR, PLN, HUF, USD, GBP, RON, NOK, SEK).
country	string Kód země ('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'), parametr slouží k omezení výběru platebních metod pro zadanou zemi.
price	integer <int32> Cena za produkt v centech nebo haléřích. U měny HUF nelze zadat cenu s desetinnými místy. V tomto případě musí cena vždy končit 00. Musí být 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 Příznak pro iniciační transakce pro opakované platby. Pouze pro Klienty, kteří mají službu povolenou.
verification	boolean Default: false Parametr ověřovací platby, v případě požadavku na založení ověřovací platby (hodnota ‘true’) není nutné posílat parametr ‘initRecurring’.
preauth	boolean Default: false 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.
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í.
embedded	boolean Parametr 'embedded' slouží k filtrování metod v případě, že se brána bude zobrazovat v iframe. Dojde k odfiltrování platebních metod, které není možné na platební bráně v iframe zobrazit. Pokud zobrazujete platební bránu v iframe, použijte 'embedded=true'.
userAgent	string Parametr 'userAgent' slouží k identifikaci webového prohlížeče zákazníka. Odfiltruje platební metody nekompatibilní s daným zařízením.

Responses

Response Schema: application/json

required

Array of objects

Dostupné metody

Array

id	string ID metody
group	string Skupina metody
groupLabel	string Popis skupiny metody
name	string Název metody
name_short	string Krátký název metody
description	string Popis metody
logo	string Logo metody
logo_240	string 240px logo metody
cblogo	string Centrované větší logo metody
clogo	string Centrované logo metody
sblogo	string Čtvercové větší logo metody
slogo	string Čtvercové logo metody

Response Schema: application/json

required

Array of objects

Chyba

Array

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

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ískání stavu platby na pozadí
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á.

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

Získat stav platby

merchant required	string identifikátor e-shopu v systému Comgate
transId required	string unikátní alfanumerický identifikátor (kód) transakce (transactionId)
secret required	string heslo pro komunikaci na pozadí

Responses

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

code required	string Návratový kód metody
message required	string popis chyby v závislosti na návratovém kódu: 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:
merchant required	string identifikátor e-shopu v systému Comgate
test required	string Hodnota 'true' znamená, že platba byla založena jako testovací, hodnota 'false' znamená produkční verzi.
price required	string cena za produkt v centech nebo haléřích
curr required	string kód měny dle ISO 4217
label required	string krátký popis produktu (1-16 znaků)
refId required	string reference platby v systému e-shopu
payerId	string identifikátor Plátce v systému e-shopu
method	string použitá metoda platby, z tabulky platebních metod
account	string identifikátor bankovního účtu e-shopu, na který Comgate převede peníze
email required	string kontaktní email na Plátce
name	string identifikátor produktu - dle této položky je potom možné se zorientovat ve statistikách plateb Comgate platebního systému.
transId required	string unikátní alfanumerický identifikátor (kód) transakce (transactionId)
secret required	string heslo pro komunikaci na pozadí
status required	string 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ě
payerName	string předání jména účtu patřící Plátci
payerAcc	string předání čísla účtu Plátce
fee	string pokud má e-shop nastavené automatické strhávání poplatku za platbu, bude v tomto poli spočítaný poplatek za transakci v centech nebo halířích, jinak bude pole nabývat hodnoty 'unknown'
vs	string variabilní symbol platby (nemusí být vždy dostupné)
cardValid	string expirace karty plátce dostupná u opakovaných iniciačních plateb
cardNumber	string částečné číslo karty plátce dostupné u opakovaných iniciačních plateb
appliedFee	integer Částka přirážky aplikovaná za neregulované typy karet.
appliedFeeType	string Typ přirážky aplikované za neregulované typy karet jako je 'EU_UNREGULATED', 'NON_EU_BUSINESS', 'NON_EU_CONSUMER' i nepřirážkový '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'