V REST variantě API podporujeme pouze datové formáty JSON a XML.
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, 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.
Přesměrování na platbu pomocí transId
Doporučujeme, aby si obchodník při založení platby vždy uložil kompletní URL pro přesměrování, která je vrácena v parametru redirect a tuto adresu používal pro všechna budoucí přesměrování (včetně emailů). V nouzových případech je možné plátce přesměrovat na platební bránu i prostřednictvím identifikátoru transakce transId. K tomuto přesměrování lze využít adresu: https://payments.comgate.cz/XXXX-XXXX-XXXX. Pokud však platba nebude v systému Comgate nalezena, zobrazí se servisní chybová stránka. Dále také nikdy sami neměňte, zda má být platba přesměrována na domény pay1, pay2, pay3, pay4, pay5 a pay6, systém si to určí při založení platby sám a na jiné subdoméně platba pravděpodobně nebude fungovat správně.
Přesměrování
Pro zakládání platby přesměrováním použijte endpoint /v2.0/paymentRedirect/merchant/{merchant_id}, se stejnými parametry jako u základní create.
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.
| authorization required | string Autorizační hlavička je ve tvaru: 'Authorization: Basic [base64_encode(merchant:secret)]'. Merchant je identifikátor e-shopu v systému Comgate - naleznete v Klientském portálu v sekci Nastaveni obchodů - Propojeni obchodu. Secret je heslo. |
Vytvořit novou platbu
| test | boolean Default: false 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. |
| 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. 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. |
| 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', 'ru', 'sl', 'sk', 'sv', 'uk', 'vi'), pokud parametr chybí, použije se 'cs', v případě požadavku na další jazyk, kontaktujte podpora@comgate.cz. |
| 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}' |
| chargeUnregulatedCardFees | boolean Pomocí tohoto parametru zapnete nebo vypnete přenesení poplatků na plátce při platbě neregulovanou kartou a zároveň vypnete metodu Apple Pay a Google Pay (pokud není parametrem 'enableApplePayGooglePay' nastaveno jinak). Povolené hodnoty jsou 'true' nebo 'false'. |
| enableApplePayGooglePay | boolean Nastavte na 'false' pro vypnutí platební metody Apple Pay a Google Pay pro konkrétní platbu, i když jsou ve vašem nastavení účtu tyto metody povoleny. |
| threeDSPreference | string Preference 3D Secure ověření karetních plateb. Povolené hodnoty jsou 'STANDARD', 'SKIP' nebo 'FORCE'. |
| code required | integer Návratový kód metody a popis chyby: |
| 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. |
{- "test": true,
- "country": "string",
- "price": 1000,
- "curr": "CZK",
- "label": "Product 123",
- "refId": "order445566",
- "method": "ALL",
- "account": "string",
- "email": "platce@email.com",
- "phone": "string",
- "fullName": "Jan Novák",
- "billingAddrCity": "string",
- "billingAddrStreet": "string",
- "billingAddrPostalCode": "string",
- "billingAddrCountry": "string",
- "delivery": "HOME_DELIVERY",
- "homeDeliveryCity": "string",
- "homeDeliveryStreet": "string",
- "homeDeliveryPostalCode": "string",
- "homeDeliveryCountry": "string",
- "category": "PHYSICAL_GOODS_ONLY",
- "name": "string",
- "lang": "string",
- "preauth": true,
- "initRecurring": true,
- "verification": true,
- "expirationTime": "string",
- "dynamicExpiration": true,
- "url_paid": "string",
- "url_cancelled": "string",
- "url_pending": "string",
- "chargeUnregulatedCardFees": true,
- "enableApplePayGooglePay": true,
- "threeDSPreference": "string"
}{- "code": 0,
- "message": "OK",
- "transId": "AB12-CD34-EF56",
}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.
| transId required | string Example: AAAA-BBBB-CCCC unikátní alfanumerický identifikátor (kód) transakce (transactionId) |
| authorization required | string Autorizační hlavička je ve tvaru: 'Authorization: Basic [base64_encode(merchant:secret)]'. Merchant je identifikátor e-shopu v systému Comgate - naleznete v Klientském portálu v sekci Nastaveni obchodů - Propojeni obchodu. Secret je heslo. |
| code required | integer Návratový kód metody a popis chyby: |
| message required | string |
# You can also use wget curl -X DELETE https://payments.comgate.cz/v2.0/payment/transId/{transId}.json \ -H 'Authorization: Basic MTIzNDU2Omd4NHE4T1YzVEp0Nm5vSm5maGpxSkt5WDNaNlljaDB5'
{- "code": 0,
- "message": "OK"
}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á.
Odpověď endpointu může obsahovat i další pole, která odpovídají parametrům zadaným při založení platby (/create).
| transId required | string Example: AAAA-BBBB-CCCC unikátní alfanumerický identifikátor (kód) transakce (transactionId) |
| authorization required | string Autorizační hlavička je ve tvaru: 'Authorization: Basic [base64_encode(merchant:secret)]'. Merchant je identifikátor e-shopu v systému Comgate - naleznete v Klientském portálu v sekci Nastaveni obchodů - Propojeni obchodu. Secret je heslo. |
| code required | integer Návratový kód metody |
| message required | string Popis chyby v závislosti na návratovém kódu: |
| 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. |
| phone | string Telefonní číslo plátce, je-li k dispozici |
| transId required | string unikátní alfanumerický identifikátor (kód) transakce (transactionId) |
| status required | string aktuální stav transakce, hodnoty |
| 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 vyjma Apple Pay a Google Pay |
| 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'. |
| paymentErrorReason | string Důvod zamítnutí platby, pokud je k dispozici. V případě více pokusů plátce o provedení platby se vrací důvod zamítnutí posledního pokusu. Možné hodnoty: |
| threeDSPreference | string Preference 3D Secure uplatněná na platbu. Vrací se pouze u karetních plateb, pokud je nastavení 3D Secure pro e-shop zapnuté. Možné hodnoty: 'STANDARD' (standardní 3D Secure), 'SKIP' (3D Secure ověření bylo vynecháno), 'FORCE' (3D Secure ověření bylo vyžádáno), 'NOT_ALLOWED' (parametr byl zaslán v /create, ale nastavení 3D Secure není pro e-shop zapnuté). |
| threeDSApplied | boolean Informace, zda bylo na platbu skutečně uplatněno 3D Secure ověření. Vrací se společně s threeDSPreference u karetních plateb, pokud je nastavení 3D Secure pro e-shop zapnuté. |
# You can also use wget curl -X GET https://payments.comgate.cz/v2.0/payment/transId/{transId}.json \ -H 'Authorization: Basic MTIzNDU2Omd4NHE4T1YzVEp0Nm5vSm5maGpxSkt5WDNaNlljaDB5'
{- "code": 0,
- "message": "OK",
- "test": "false",
- "price": "10000",
- "curr": "CZK",
- "label": "Beatles - Help",
- "refId": "2010102600",
- "payerId": "string",
- "method": "ALL",
- "account": "string",
- "email": "platce@email.com",
- "name": "string",
- "phone": "string",
- "transId": "AB12-CD34-EF56",
- "status": "PAID",
- "payerName": "string",
- "payerAcc": "string",
- "fee": "string",
- "vs": "string",
- "cardValid": "string",
- "cardNumber": "string",
- "appliedFee": 0,
- "appliedFeeType": "string",
- "paymentErrorReason": "string",
- "threeDSPreference": "string",
- "threeDSApplied": true
}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)
Rekurentní platby, tzn. opakované platby, u nichž si obchodník prostřednictvím API sám určuje částku i časový rozestup jednotlivých plateb, lze realizovat pomocí služby Opakované platby popsané výše. Správu opakovaných plateb (částku a periodu) provádí obchodník na své straně.
Testovací rekurentní platby (s výjimkou iniciační) založené s e-mailem 'recurring.cancelled@comgate.cz' budou automaticky označeny jako CANCELLED (nezaplacené)
| authorization required | string Autorizační hlavička je ve tvaru: 'Authorization: Basic [base64_encode(merchant:secret)]'. Merchant je identifikátor e-shopu v systému Comgate - naleznete v Klientském portálu v sekci Nastaveni obchodů - Propojeni obchodu. Secret je heslo. |
| 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 | integer <int32> 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. 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. |
| initRecurringId required | string Comgate ID iniciační platby |
| code required | integer Návratový kód metody a popis chyby: |
| 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 |
{- "test": true,
- "price": 10000,
- "curr": "CZK",
- "label": "string",
- "refId": "2010102600",
- "account": "string",
- "name": "string",
- "initRecurringId": "AB12-CD34-EF56"
}{- "code": 0,
- "message": "OK",
- "transId": "string"
}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.
| authorization required | string Autorizační hlavička je ve tvaru: 'Authorization: Basic [base64_encode(merchant:secret)]'. Merchant je identifikátor e-shopu v systému Comgate - naleznete v Klientském portálu v sekci Nastaveni obchodů - Propojeni obchodu. Secret je heslo. |
Vrácení platby
| transId required | string unikátní alfanumerický identifikátor (kód) transakce (transactionId) |
| amount required | integer <int32> čá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 | boolean 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. |
| refId | string parametr vhodný k zadaní identifikačního čísla refundace na straně Klienta (nemusí být unikátní, tzn. 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. |
| code required | integer Návratový kód metody a popis chyby: |
| message required | string |
{- "transId": "AB12-CD34-EF56",
- "amount": 10000,
- "test": true,
- "refId": "string"
}{- "code": 0,
- "message": "OK"
}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.
| authorization required | string Autorizační hlavička je ve tvaru: 'Authorization: Basic [base64_encode(merchant:secret)]'. Merchant je identifikátor e-shopu v systému Comgate - naleznete v Klientském portálu v sekci Nastaveni obchodů - Propojeni obchodu. Secret je heslo. |
Refundace terminálové platby
| vs required | string variabilní symbol platby |
| amount required | integer <int32> částka refundace – může být v plné nebo částečné výši transakce |
| date required | string datum provedení transakce |
| code required | integer Návratový kód metody a popis chyby: |
| message required | string |
{- "vs": "7654321",
- "amount": 10000,
- "date": "2000-02-22"
}{- "code": 0,
- "message": "OK"
}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.
| transId required | string Example: AAAA-BBBB-CCCC unikátní alfanumerický identifikátor (kód) transakce (transactionId) |
| authorization required | string Autorizační hlavička je ve tvaru: 'Authorization: Basic [base64_encode(merchant:secret)]'. Merchant je identifikátor e-shopu v systému Comgate - naleznete v Klientském portálu v sekci Nastaveni obchodů - Propojeni obchodu. Secret je heslo. |
Potvrzení předběžné autorizace
| amount | integer <int32> částka předautorizace, která má být z karty stržena - může být v plné nebo částečné výši transakce |
| code required | integer Návratový kód metody a popis chyby: |
| message required | string |
{- "amount": 10000
}{- "code": 0,
- "message": "OK"
}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.
| transId required | string Example: AAAA-BBBB-CCCC unikátní alfanumerický identifikátor (kód) transakce (transactionId) |
| authorization required | string Autorizační hlavička je ve tvaru: 'Authorization: Basic [base64_encode(merchant:secret)]'. Merchant je identifikátor e-shopu v systému Comgate - naleznete v Klientském portálu v sekci Nastaveni obchodů - Propojeni obchodu. Secret je heslo. |
| code required | integer Návratový kód metody a popis chyby: |
| message required | string |
# You can also use wget curl -X DELETE https://payments.comgate.cz/v2.0/preauth/transId/{transId}.json \ -H 'Authorization: Basic MTIzNDU2Omd4NHE4T1YzVEp0Nm5vSm5maGpxSkt5WDNaNlljaDB5'
{- "code": 0,
- "message": "OK"
}Metoda transferList slouží k získání informace, jaké převody byly uskutečněny v rámci daného dne. Informace o bankovním převodu (poslaného v předchozí pracovní den) je dostupná v dopoledních hodinách dne následujícího.
Převody a výpisy se generují pouze pro zaplacené a převedené produkční platby. Pro všechny ostatní platby, včetně testovacích, se převody a výpisy negenerují.
| date required | string Example: 2025-04-25 Uveďte datum uskutečnění převodu. |
| test | boolean Example: test=false Pokud vyplníte 'true', metoda vrátí předem definovaný vzorový převod. |
| authorization required | string Autorizační hlavička je ve tvaru: 'Authorization: Basic [base64_encode(merchant:secret)]'. Merchant je identifikátor e-shopu v systému Comgate - naleznete v Klientském portálu v sekci Nastaveni obchodů - Propojeni obchodu. Secret je heslo. |
| transferId | integer Převody, které byly uskutečněny v rámci daného dne. |
| transferDate | string <date> Parametry date a transferDate jsou interpretovány v časovém pásmu Europe/Prague (CET/CEST v závislosti na datu). |
| accountCounterparty | string Číslo účtu protistrany. |
| accountOutgoing | string Odchozí číslo účtu. |
| variableSymbol | string Identifikátor platby (variabilní symbol). |
# You can also use wget curl -X GET https://payments.comgate.cz/v2.0/transferList/date/{date}.json \ -H 'Authorization: Basic MTIzNDU2Omd4NHE4T1YzVEp0Nm5vSm5maGpxSkt5WDNaNlljaDB5'
[- {
- "transferId": 1234567,
- "transferDate": "2023-01-25",
- "accountCounterparty": "0/0000",
- "accountOutgoing": "123456789/0000",
- "variableSymbol": "12345678"
}
]Metoda singleTransfer zobrazuje detailní informace ke konkrétnímu bankovnímu převodu.
Povinný parametr 'transferId' získá obchodník pomocí metody transferList.
Parametry date jsou interpretovány v časovém pásmu Europe/Prague (CET/CEST v závislosti na datu).
Převody a výpisy se generují pouze pro zaplacené a převedené produkční platby. Pro všechny ostatní platby, včetně testovacích, se převody a výpisy negenerují.
| transferId required | integer Example: 1234567 Povinný parametr, který získáte pomocí metody transferList. |
| test | boolean Example: test=false Vhodné pro testování – Pokud je hodnota true, vrátí se detaily k předem definovaným vzorovým převodům. |
| authorization required | string Autorizační hlavička je ve tvaru: 'Authorization: Basic [base64_encode(merchant:secret)]'. Merchant je identifikátor e-shopu v systému Comgate - naleznete v Klientském portálu v sekci Nastaveni obchodů - Propojeni obchodu. Secret je heslo. |
| typ | integer Parametr označuje typ převodu. |
| Merchant | string Identifikátor e-shopu v systému Comgate. |
| Datum založení | string Datum založení transakce. |
| Datum zaplacení | string Datum zaplacení transakce. |
| Datum převodu | string Datum vyplacení hromadného převodu transakcí. |
| Měsíc fakturace | integer Měsíc, ke kterému se platba vztahuje účetně. |
| ID Comgate | string Comgate ID platby, 12místný kód, unikátní identifikace platby. |
| Metoda | string Výsledná metoda platby. |
| Produkt | string Libovolný identifikátor produktu, který předává váš systém při založení platby pod parametrem 'name'. |
| Popis | string Krátký popis produktu (1–16 znaků), který předává váš systém při založení platby pod parametrem 'label'. |
| E-mail plátce | string E-mail plátce platby. |
| Variabilní symbol plátce | string Variabilní symbol přiřazený k dané platbě. |
| Variabilní symbol převodu | string Variabilní symbol hromadného převodu. |
| ID od klienta | string Párovací symbol, díky kterému identifikujete zboží a zákazníka, který si ho objednal (např. číslo objednávky, číslo zákazníka apod.). V rámci protokolu API se jedná o parametr RefId, který systém posílá při založení platby. |
| Měna | string Měna platby. Hodnota je ve formátu ISO 4217. |
| Potvrzená částka | string Částka realizované transakce (výše zákazníkovy objednávky). |
| Převedená částka | string Částka, která je e-shopu standardně zaslána na bankovní účet (ponížená o poplatek z transakce). |
| Poplatek celkem | string Celkový poplatek za platbu, který se řídí nastaveným ceníkem. Poplatek celkem = poplatek mezibankovní + poplatek asociace + poplatek zpracovatel. |
| Poplatek mezibankovní | string Poplatek, který dostává vydavatel platební karty. |
| Poplatek asociace | string Poplatek, který z transakce obdrží karetní asociace. |
| Poplatek zpracovatel | string Poplatek, který si účtuje zpracovatel transakce. |
| Typ karty | string Typ použité platební karty při platbě kartou. |
# You can also use wget curl -X GET https://payments.comgate.cz/v2.0/singleTransfer/transferId/{transferId}.json \ -H 'Authorization: Basic MTIzNDU2Omd4NHE4T1YzVEp0Nm5vSm5maGpxSkt5WDNaNlljaDB5'
[- {
- "typ": 1,
- "Merchant": "123456",
- "Datum založení": "2023-01-06 14:11:30",
- "Datum zaplacení": "2023-01-06 14:21:30",
- "Datum převodu": "2023-01-10",
- "Měsíc fakturace": null,
- "ID Comgate": "AAAA-BBBB-CCCC",
- "Metoda": "Card payment",
- "Produkt": null,
- "Popis": "description eshop payment",
- "E-mail plátce": "name.lastname@email.cz",
- "Variabilní symbol plátce": "123456789",
- "Variabilní symbol převodu": "123456789",
- "ID od klienta": "1234",
- "Měna": "EUR",
- "Potvrzená částka": "10,00",
- "Převedená částka": "10,00",
- "Poplatek celkem": "0,35",
- "Poplatek mezibankovní": "0,25",
- "Poplatek asociace": "0,25",
- "Poplatek zpracovatel": "-0,15",
- "Typ karty": "EU_UNREGULATED"
}
]Díky metodě csvSingleTransfer si lze stáhnout denní výpis ve formátu CSV.
Převody a výpisy se generují pouze pro zaplacené a převedené produkční platby. Pro všechny ostatní platby, včetně testovacích, se převody a výpisy negenerují.
| transferId required | integer Example: 1234567 Povinný parametr, který získáte pomocí metody transferList. |
| download | boolean Example: download=false Pokud není vyplněno, nebo je false, vrací data: název souboru a jeho obsah; pokud je true, vrací rovnou CSV soubor. |
| test | boolean Example: test=false Pokud je hodnota true, vrátí ukázkový CSV soubor. |
| authorization required | string Autorizační hlavička je ve tvaru: 'Authorization: Basic [base64_encode(merchant:secret)]'. Merchant je identifikátor e-shopu v systému Comgate - naleznete v Klientském portálu v sekci Nastaveni obchodů - Propojeni obchodu. Secret je heslo. |
| nazev | string Název staženého souboru CSV |
| csv | string Soubor CSV s kódováním Base64 |
# You can also use wget curl -X GET https://payments.comgate.cz/v2.0/csvSingleTransfer/transferId/{transferId}.json \ -H 'Authorization: Basic MTIzNDU2Omd4NHE4T1YzVEp0Nm5vSm5maGpxSkt5WDNaNlljaDB5'
{- "nazev": "vypis-YYYY-MM-DD.csv",
- "csv": "base64 encoded csv"
}Díky metodě aboSingleTransfer si lze stáhnout denní výpis ve formátu ABO.
Převody a výpisy se generují pouze pro zaplacené a převedené produkční platby. Pro všechny ostatní platby, včetně testovacích, se převody a výpisy negenerují.
| transferId required | integer Example: 1234567 Povinný parametr, který získáte pomocí metody transferList. |
| download | boolean Example: download=true Pokud není vyplněno, nebo je false, vrací data: název souboru a jeho obsah; pokud je true, vrací rovnou ABO soubor. |
| type | string Example: type=v1 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 Example: encoding=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 Example: test=false Pokud je hodnota true, vrátí ukázkový ABO soubor. |
| authorization required | string Autorizační hlavička je ve tvaru: 'Authorization: Basic [base64_encode(merchant:secret)]'. Merchant je identifikátor e-shopu v systému Comgate - naleznete v Klientském portálu v sekci Nastaveni obchodů - Propojeni obchodu. Secret je heslo. |
| nazev | string Název souboru. |
| abo | string Soubor abo/gpc v kódování base64. |
# You can also use wget curl -X GET https://payments.comgate.cz/v2.0/aboSingleTransfer/transferId/{transferId}.json \ -H 'Authorization: Basic MTIzNDU2Omd4NHE4T1YzVEp0Nm5vSm5maGpxSkt5WDNaNlljaDB5'
{- "nazev": "vypis-YYYY-MM-DD.gpc",
- "abo": "base64_encoded_abo_file"
}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.
Převody a výpisy se generují pouze pro zaplacené a převedené produkční platby. Pro všechny ostatní platby, včetně testovacích, se převody a výpisy negenerují.
| date required | string Example: 2025-04-25 Povinný pouze za jeden den. |
| test | boolean Example: test=false Pokud je hodnota true, vrátí ukázkový CSV soubor ve formátu ZIP. |
| authorization required | string Autorizační hlavička je ve tvaru: 'Authorization: Basic [base64_encode(merchant:secret)]'. Merchant je identifikátor e-shopu v systému Comgate - naleznete v Klientském portálu v sekci Nastaveni obchodů - Propojeni obchodu. Secret je heslo. |
# You can also use wget curl -X GET https://payments.comgate.cz/v2.0/csvDownload/date/{date} \ -H 'Authorization: Basic MTIzNDU2Omd4NHE4T1YzVEp0Nm5vSm5maGpxSkt5WDNaNlljaDB5'
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.
Převody a výpisy se generují pouze pro zaplacené a převedené produkční platby. Pro všechny ostatní platby, včetně testovacích, se převody a výpisy negenerují.
| date required | string Example: 2025-04-25 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 poplatkem souhrnným v jednom řádku. Pokud nebude parametr vyplněn, automaticky obdržíte typ 'v1'. |
| encoding | string Example: encoding=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 Example: test=false Pokud je hodnota true, vrátí ukázkový CSV soubor ve formátu ZIP. |
| authorization required | string Autorizační hlavička je ve tvaru: 'Authorization: Basic [base64_encode(merchant:secret)]'. Merchant je identifikátor e-shopu v systému Comgate - naleznete v Klientském portálu v sekci Nastaveni obchodů - Propojeni obchodu. Secret je heslo. |
# You can also use wget curl -X GET https://payments.comgate.cz/v2.0/aboDownload/date/{date} \ -H 'Authorization: Basic MTIzNDU2Omd4NHE4T1YzVEp0Nm5vSm5maGpxSkt5WDNaNlljaDB5'
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í.
| 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', 'ru', 'sl', 'sk', 'sv', 'uk', '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 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. |
| initRecurring | boolean Příznak pro 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’. |
| 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. |
| 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. |
| chargeUnregulatedCardFees | boolean Pomocí tohoto parametru zapnete nebo vypnete přenesení poplatků na plátce při platbě neregulovanou kartou a zároveň vypnete metodu Apple Pay a Google Pay (pokud není parametrem 'enableApplePayGooglePay' nastaveno jinak). Povolené hodnoty jsou 'true' nebo 'false'. |
| enableApplePayGooglePay | boolean Nastavte na 'false' pro vypnutí platební metody Apple Pay a Google Pay pro konkrétní platbu, i když jsou ve vašem nastavení účtu tyto metody povoleny. |
| authorization required | string Autorizační hlavička je ve tvaru: 'Authorization: Basic [base64_encode(merchant:secret)]'. Merchant je identifikátor e-shopu v systému Comgate - naleznete v Klientském portálu v sekci Nastaveni obchodů - Propojeni obchodu. Secret je heslo. |
required | Array of objects Dostupné metody | ||||||||||||||||||||||||
Array
| |||||||||||||||||||||||||
# You can also use wget curl -X GET https://payments.comgate.cz/v2.0/method.json \ -H 'Authorization: Basic MTIzNDU2Omd4NHE4T1YzVEp0Nm5vSm5maGpxSkt5WDNaNlljaDB5'
{- "methods": [
- {
- "id": "string",
- "group": "string",
- "groupLabel": "string",
- "name": "string",
- "name_short": "string",
- "description": "string",
- "logo": "string",
- "logo_120c": "string",
- "logo_240": "string",
- "logo_240c": "string",
- "logo_150s": "string",
- "logo_100s": "string"
}
]
}Stažení obsahu validačního souboru pro ověření domény v Apple Pay pro Comgate Checkout SDK. Systém automaticky určí správný soubor podle aktivní karetní metody obchodníka. Více informací v implementačním manuálu Checkout SDK.
| currency | string Měna podle které se rozhoduje validační soubor. Hodnota je ve formátu ISO 4217. |
| authorization required | string Autorizační hlavička je ve tvaru: 'Authorization: Basic [base64_encode(merchant:secret)]'. Merchant je identifikátor e-shopu v systému Comgate - naleznete v Klientském portálu v sekci Nastaveni obchodů - Propojeni obchodu. Secret je heslo. |
| fileContent | string |
# You can also use wget curl -X GET https://payments.comgate.cz/v2.0/appleDomainAssociation.json \ -H 'Authorization: Basic MTIzNDU2Omd4NHE4T1YzVEp0Nm5vSm5maGpxSkt5WDNaNlljaDB5'
{- "fileContent": "APPLE_DOMAIN_ASSOCIATION_FILE_CONTENT_PLACEHOLDER"
}Konfigurace
Endpoint slouží ke konfiguraci konkrétního propojení obchodu. Umožňuje nastavit vizuální podobu platební brány, například logo, barvy nebo pozadí, a zároveň definovat URL adresy pro přesměrování plátce po dokončení platby. Podrobnosti naleznete v průvodci konfigurací.
| authorization required | string Autorizační hlavička je ve tvaru: 'Authorization: Basic [base64_encode(merchant:secret)]'. Merchant je identifikátor e-shopu v systému Comgate - naleznete v Klientském portálu v sekci Nastaveni obchodů - Propojeni obchodu. Secret je heslo. |
Nastavení konfigurace
| gateway_logo | string Logo v hlavičce platební brány |
| gateway_background | string Obrázek v pozadí brány v kódování Base64 |
| gateway_color_page | string HEX kód barvy pozadí stránky platební brány |
| gateway_color_header | string HEX kód barvy hlavičky platební brány |
| gateway_signature | string Textový popis v patičce platební brány |
| url_paid | string Návratová Url adresa po zaplacení platby |
| url_cancelled | string Návratová Url adresa po zrušení platby |
| url_pending | string Návratová Url adresa pro nevyřízenou platbu |
| url_push | string Url pro předání výsledku platby |
| ip_addresses | string Povolené IP adresy |
| active | boolean or null Parametr slouží pro deaktivaci propojení obchodu |
| code | integer Návratový kód metody |
| message | string Návratová zpráva metody |
| merchant | string identifikátor e-shopu v systému Comgate |
| secret | string heslo pro komunikaci na pozadí |
| gateway_logo | string Logo v hlavičce platební brány |
| gateway_background | string Obrázek v pozadí brány v kódování Base64 |
| gateway_color_page | string HEX kód barvy pozadí stránky platební brány |
| gateway_color_header | string HEX kód barvy hlavičky platební brány |
| gateway_signature | string Textový popis v patičce platební brány |
| url_paid | string Návratová Url adresa po zaplacení platby |
| url_cancelled | string Návratová Url adresa po zrušení platby |
| url_pending | string Návratová Url adresa pro nevyřízenou platbu |
| url_push | string Url pro předání výsledku platby |
| ip_addresses | string Povolené IP adresy |
| active | boolean or null Parametr slouží pro deaktivaci propojení obchodu |
{- "gateway_logo": "data:image/png;base64,...",
- "gateway_background": "data:image/png;base64,...",
- "gateway_color_page": "#C2E7FF",
- "gateway_color_header": "#f2c7af",
- "gateway_signature": "string",
- "url_paid": "string",
- "url_cancelled": "string",
- "url_pending": "string",
- "url_push": "string",
- "ip_addresses": "{1.1.1.1/1,2.2.2.2/2}",
- "active": ""
}{- "code": 0,
- "message": "OK",
- "merchant": 123123,
- "secret": "secret",
- "gateway_logo": "data:image/png;base64,...",
- "gateway_background": "data:image/png;base64,...",
- "gateway_color_page": "#C2E7FF",
- "gateway_color_header": "#f2c7af",
- "gateway_signature": "string",
- "url_paid": "string",
- "url_cancelled": "string",
- "url_pending": "string",
- "url_push": "string",
- "ip_addresses": "{1.1.1.1/1,2.2.2.2/2}",
- "active": ""
}