TAG_api_title
Scroll down for code samples, example requests and responses. Select a programming language for code samples and language for the documentation itself from the tabs above or the mobile navigation menu.Posuňte se dolů, kde najdete ukázky kódu, příklady požadavků a odpovědí. Na kartách nahoře nebo v mobilní navigační nabídce vyberte programovací jazyk pro ukázky kódu a jazyk pro samotnou dokumentaci.Posuňte sa nižšie, kde nájdete ukážky kódu, príklady požiadaviek a odpovedí. Vyberte si programovací jazyk pre ukážky kódu a jazyk pre samotnú dokumentáciu z kariet vyššie alebo z mobilného navigačného menu.
SDK
SDK dostupný na https://github.com/comgate-payments/sdk-php
Open-source řešení: https://help.comgate.cz/docs/en/open-source-solution
Specifikace protokolu
Využívá HTTP POST. Propojení mezi e-shopem a platební branou Comgate je realizované pomocí přesměrování plátce z e-shopu na platební bránu. Po provedení platby je plátce přesměrován zpět do e-shopu. Zároveň na pozadí probíhá komunikace mezi serverem e-shopu 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 e-shopu, počáteční nastavení v klientském portálu nebo doporučený způsob testování integrace platební brány.
Pro snadnou implementaci platební brány můžete použít tento PHP SDK (instalace přes composer).
Průběh platby
Založení platby – volitelné
Krok založení platby 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. Postup je detailně popsán v odstavci Jednoduchá integrace - bez založení platby.
Pro klasický e-shop, kde nakupující platí za konkrétní zboží, je krok založení platby důležitý, jeho vynechání nedoporučujeme.
Platbu e-shop 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 pomocí cURL
curl -X POST -i --data "merchant=123456&price=10000&curr=CZK&label=Beatles%20-0%Help&refId=2010102600&method=ALL&prepareOnly=true&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y" https://payments.comgate.cz/v1.0/create
Příklad založení platby na pozadí – HTTP response:
HTTP/2 200 OK
content-type: application/x-www-form-urlencoded; charset=UTF-8
code=0&message=OK&transId=AB12-CD34-EF56&redirect=https%3A%2F%2Fpayments.comgate.cz%2Fclient%2Finstructions%2Findex%3Fid%3DAB12-CD34-EF56
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 platební bránu
Po založení platby na pozadí obdrží e-shop platební URL pro zobrazení platební brány. Platební brána může být zobrazena dvěma způsoby. První způsobem je přesměrování plátce na adresu, kterou obdržel e-shop v HTTP odpovědi. Přesměrování se obvykle provádí odesláním HTTP odpovědi 302:
HTTP odpověď 302
HTTP/2 302 Found
Location: https://payments.comgate.cz/client/instructions/index?id=AB12-CD34-EF56
Druhou možností je zobrazení platební brány přímo na stránce e-shopu pomocí iframu. Pro tuto variantu je potřeba vygenerovat platební URL standardním způsobem, ale místo přesměrování zákazníka na bránu se zobrazí na stránce e-shopu iframe s platební URL.
Jednoduchá integrace – bez založení platby
Platební brána umožňuje vynechání prvního kroku založení platby na pozadí. V tomto případě je Plátce přesměrován na platební bránu bez předchozího založení platby. Přesměrování může proběhnout buď z odesláním formuláře metodou POST nebo přímým linkem pomocí metody GET. Doporučujeme způsob s použitím formuláře.
Příklad jednoduché integrace – odeslání formuláře (POST)
<form method="POST" action="https://payments.comgate.cz/v1.0/create">
<input type="hidden" name="merchant" value="XXXX" /> <!-- identifikátor e-shopu v systému Comgate -->
<input type="hidden" name="price" value="100" /> <!-- 100 = 1,00 Kč -->
<input type="hidden" name="curr" value="CZK" />
<input type="hidden" name="label" value="Moje služba" />
<input type="hidden" name="refId" value="123456" />
<input type="hidden" name="method" value="ALL" />
<input type="hidden" name="country" value="CZ" />
<button type="submit">Zakoupit</button>
</form>
Příklad jednoduché integrace - přesměrování pomocí linku (GET)
<a href="https://payments.comgate.cz/v1.0/create?merchant=XXXX&price=100&curr=CZK&label=Moje%20slu%C5%BEba&refId=10980891&method=ALL&country=CZ" rel="nofollow">Zaplatit</a>
V parametrech hypertextového odkazu zachovejte parametr rel=”nofollow”.
Předání výsledku platby na pozadí
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ý. Předávání výsledku platby na pozadí je povinné.
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.
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 |
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“. |
Parametry odpovědí
Parametr | Typ | povinný | Popis |
---|---|---|---|
code | integer | A | Návratový kód metody a popis chyby: systém očekává HTTP kód 200, 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 pomocí cURL
curl -X POST -i --data "merchant=merchant_com&test=false&price=10000&curr=CZK&label=Beatles%20-%20Help&refId=2010102600&method=CARD&email=info%40customer.com&phone=%2B420123456789&transId=AB12-EF34-IJ56&secret=ZXhhbXBsZS5jb206QUJDeHl6&status=PAID" https://example.com/handler.php
Příklad předání výsledku platby na pozadí – HTTP response
HTTP/2 200 OK
content-type: application/x-www-form-urlencoded; charset=UTF-8
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.
E-shop 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é e-shop 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 e-shop 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 e-shop 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/2
Host: eshop.com
Platební brána v e-shopu (iframe)
Platební brána 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. Aby se platební brána zobrazila v iframu, je potřeba při založení platby použít parametr “embedded” = true. Platební URL je vygenerována standardním způsobem, ale místo přesměrování zákazníka na bránu se zobrazí na stránce e-shopu iframe s platební URL.
Pro zobrazení jsou dvě možnosti. Jednak je možné platební bránu zobrazit přímo v košíku nebo pomocí vyskakovacího okna nad vaší webovou stránkou. Implementace iframu vyžaduje znalost webových technologií. Iframe je možné použít pouze pro platbu kartou. U ostatních platebních metod dojde vždy k přesměrování plátce na novou stránku.
Pro správné zobrazení platební brány v iframu na webové stránce doporučujeme provést následující úpravu vašich webových stránek.
Nastavení zobrazení platební brány
HTML kód
<div id="comgate-container">
<iframe id='comgate-iframe' src ="[platební URL]" frameborder="0px"></iframe>
</div>
CSS styly
#comgate-container {
display: none;
position:absolute;
z-index: 9999;
left: 50%;
top: 30px;
overflow: auto;
margin-left: -250px;
}
#comgate-iframe {
width: 504px;
height: 679px;
}
@media (max-height: 700px) {
#comgate-iframe {
top: 0px;
}
}
Javascriptový kód
// funkce pro otevření iframu s bránou
function comgateOpen() {
let comgate_container = document.getElementById("comgate-container");
comgate_container.style.display = "block";
}
// funkce pro zavření iframu s bránou
function comgateClose() {
let comgate_container = document.getElementById("comgate-container");
comgate_container.style.display = "none";
}
Pro zobrazení iframu je třeba zavolat funkci comgateOpen(). Například navázáním na uživatelskou akci (kliknutí na tlačítko apod.). Funkce comgateClose() pak slouží pro případné skrytí iframu.
Příklad zavolání funkce pro zobrazení iframu kliknutím na tlačítko , Zaplatit":
HTML kód
<button id="comgate-open" onclick="comgateOpen()">Zaplatit</button>
Přesměrování zákazníka po dokončení platby
Po dokončení platby zákazníkem dochází k jeho přesměrování do e-shopu na URL, kterou jste nastavili v klientském portálu. Doporučujeme provést jednu z následujících úprav, která zajistí, že zákazník bude přesměrován přímo na návratovou URL a nezůstane tak uvnitř iframu.
První možností je přesměrovat vnější stránku na vámi určenou URL. Tím dojde k obnovení celé stránky.
Javascriptový kód pro vnitřní stránku
window.top.location = window.self.location
Druhou možností je ze stránky uvnitř iframu poslat zprávu vnější stránce a na vnější stránce tuto událost zpracovat. Nemusí tedy dojít k obnovení celé stránky.
Pozor, skutečný výsledek platby je třeba získat na pozadí standardním způsobem. Z bezpečnostních důvodů nelze spoléhat na výsledek předaný zprávou z iframu.
Javascriptový kód pro vnitřní stránku, který pošle vnější stránce zprávu s ID platby a stavem platby, např. pro zaplacenou platbu:
window.parent.postMessage('[id platby]|PAID', '*');
Javascriptový kód pro vnější stránku, který zpracuje příchozí zprávu z iframu:
// odchycení zprávy poslané z iframu pomocí postMessage
if (window.addEventListener) {
window.addEventListener('message', function (e) {
// přijde mi id a výsledek platby, oddělovač je “roura”
let message = e.data.split('|', 2);
let message_id = message[0];
let message_result = message[1];
let result = '';
if (message_result === 'PAID') {
// obsloužení stavu PAID
[...]
} else {
// obsloužení dalších stavů, atd ...
[...]
}
}, false);
}
Platební brána v iframu z pohledu plátce
Platební brána Comgate umožňuje uživatelům opakovat platbu, pokud se jim nepodařilo dokončit platbu napoprvé. Zobrazení platební brány v iframu uživateli je závislé na zvolené platební metodě a také, zda se výběr platebních metod nachází na straně e-shopu nebo na straně Comgate.
V případě, že je výběr platebních metod na straně e-shopu a platba je tak založena již s platební metodou, musí být pro zobrazení iframu zvolena metoda platby kartou. Pokud se uživateli nepodařilo platbu napoprvé dokončit, je mu pro další pokus opět zobrazena pouze metoda platby kartou. Tato verze je doporučována.
V případě, že e-shop nezakládá platbu s již vybranou platební metodou, je uživateli v iframu zobrazen výběr platebních metod. Zde je následně potřeba zvolit platbu kartou. Pokud se uživateli nepodařilo platbu dokončit, je mu pro další pokus opět zobrazen výběr platebních metod v iframu.
Pokud dojde v jakémkoliv kroku platebního procesu k vybrání jiné metody než platby kartou, dojde k přesměrování plátce na novou stránku. Uživatel se již zpět do iframu nevrátí.
Vzor pro zobrazení brány v e-shopu
Pro snadnou implementaci naší platební brány do vašeho e-shopu, můžete využít níže dostupné vzorové implementace.
HTML kód
<!doctype html>
<html lang="cs">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Comgate :: práce s iframem</title>
<style>
body,html {
background: #fff;
padding:0;
margin:0;
width: 100%;
height: 100%;
}
.page {
width: 100%;
background: #eee;
margin: 0 auto;
max-width: 800px;
}
.page .header h1 {
text-align: center;
margin: 0;
padding: 25px 15px;
font-size: 25px;
}
#comgate-iframe-box {
width: 450px; /* šířka je pomocí media automaticky nastavena na 100 % šířky obrazovky v případě malého displaye */
height: 700px; /* výšku je pro novou bránu možné dynamicky přizpůsobit Vašim potřebám */
margin: 0 auto;
}
#comgate-iframe-box .iframe {
width: 100%;
height: 100%;
}
@media (max-width: 450px) {
#comgate-iframe-box {
width: 100%;
}
}
</style>
</head>
<body>
<div class="page">
<div class="header">
<h1>Ukázka práce s iframem</h1>
</div>
<div id="comgate-iframe-box">
<!--
V konfiguraci iframu:
pro novou bránu použít scrolling="off"
pro starou bránu použít scrolling="on"
-->
<iframe
class="iframe"
src="https://payments.comgate.cz/client/instructions/index/id/XXXX-XXXX-XXXX" allow="payment" frameborder="0px" scrolling="off"></iframe>
</div>
</div>
</body>
</html>
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ředautorizace 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řazena 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í.
Metody platební brány
Platební tlačítka
Zrychlené bankovní převody (platební tlačítka) poskytujeme od všech významných bank v Česku, Polsku a na Slovensku. Seznam dostupných bank najdete v číselnících. V případě platebních tlačítek je možné využít funkcionalit, jako jsou refundace a storno platby. Platební tlačítko není možné zobrazit přímo v e-shopu (iframe). Plátce je vždy přesměrován do banky.
Platba kartou
Platební brána akceptuje platby kartou VISA, VISA Electron, Mastercard, Maestro. Platby jsou dostupné v měnách CZK, EUR, PLN, HUF, USD, GBP a RON, NOK a SEK. Je k dispozici ve 12 jazycích - v češtině, slovenštině, angličtině, němčině, francouzštině, polštině, maďarštině, chorvatštině, slovinštině, rumunštině, norštině a švédštině.
V rámci platby kartou je možné využít mnoho funkcionalit. Mezi ně patří refundace platby, storno nedokončené platby, opakované platby (například pro předplatné s pravidelným strháváním prostředků z karty plátce) nebo předautorizace. Platbu kartou lze také zobrazit přímo v e-shopu (iframe).
Apple Pay
Služba Apple Pay je součástí platební brány Comgate. Pro zobrazení služby zákazníkovi stačí mít povolenou metodu platby kartou CARD_CZ_CSOB_2.
V rámci služby není možné použít funkcionalitu opakované platby.Ostatní funkcionality jsou k dispozici.
Zobrazení služby Apple Pay
Zobrazení služby Apple Pay se odvíjí podle toho, zda se výběr platebních metod nachází v košíku e-shopu nebo e-shop využívá výběru metod od Comgate. Dále je potřeba rozlišit, zda má dojít k přesměrování plátce na karetní bránu nebo se Apple Pay zobrazí přímo v prostředí košíku e-shopu. Rozlišujeme tedy tři možnosti zobrazení Apple Pay:
1. Tlačítko Apple Pay v karetní bráně - V případě, že se výběr platebních metod nachází na straně Comgate, není pro zobrazení služby třeba žádných úprav. Stačí mít povolenou metodu platby kartou CARD_CZ_CSOB_2. Po výběru této metody ze strany plátce probíhá platba standardním procesem s přesměrováním na platební bránu. Služba se zobrazí automaticky na karetní bráně. Zde je zároveň plátci umožněno zadat číslo karty ručně. Pokud se na bránu dostane plátce ze zařízení či prohlížeče, které Apple Pay neumožňují, bude moci provést alespoň úhradu platební kartou.
2. Tlačítko Apple Pay v košíku e-shopu s přesměrování plátce na karetní bránu - Pokud je výběr platebních metod na straně e-shopu, platba se zakládá jako běžná platba, v požadavku je však třeba volat metodu APPLEPAY_REDIRECT. Následně dojde k přesměrování plátce na platební bránu pomocí získaného platebního odkazu. Tlačítko Apple Pay se poté zobrazí na karetní bráně automaticky. Proces platby z pohledu plátce je následně shodný s první variantou.
Doporučení, kdy zobrazovat Apple Pay v košíku e-shopu Služba Apple Pay je dostupná pouze uživatelům, kteří mají k dispozici webový prohlížeč Safari a vlastní zařízení od společnosti Apple, které disponuje Touch ID nebo Face ID. K těmto zařízením patří MacBook, iPhone, iPad a stolní Mac. Podmínkou je taky, že plátce má kartu vloženou v Apple Wallet. Z tohoto důvodu doporučujeme službu zobrazovat v objednávce pouze klientům, kteří platit s Apple Pay mohou. Návod najdete přímo na stránkách Apple pro vývojáře.
Doporučení, jak správně zobrazovat Apple Pay Správné použití log a názvů Apple Pay najdete v průvodci Marketingem od Apple Pay. Jak zobrazit tlačítko Apple Pay najdete na stránkách Buttons and Marks. Dále doporučujeme si pročíst průvodce k používání CSS stylů, dostupných v Safari.
3. Tlačítko Apple Pay součástí košíku e-shopu, bez přesměrování na karetní bránu
V současnosti implementace Apple Pay v rámci košíku e-shopu není k dispozici kvůli změnám na straně Apple Pay. Připravujeme pro vás novou verzi.
V této variantě integrace nedochází k přesměrování plátce na karetní bránu a platba je kompletně zpracována přímo v prostředí e-shopu.
Tato metoda však vyžaduje náročnější implementaci, než obě výše zmíněné varianty. Detailní informace k celému postupu integrace naleznete přímo v dokumentaci Apple pay v košíku e-shopu.
Případy, když Apple Pay se nezobrazí
Může se stát, že Apple Pay plátci zobrazen nebude, pokud Apple Pay vyhodnotí, že není možné platbu přes jejich rozhraní realizovat.
Apple Pay se nezobrazí, když:
- plátce je v libovolném prohlížeči který není Safari (to samý platí pro “in App” browser na iOS )
pokud je to Safari:
- plátce nemá v Apple Wallet vloženou kartu,
- zařízení nepodporuje Apple Pay (Může se také stát, že plátce na IPhone má starší verzi iOS na nepodporovaném zařízení a potřebuje ho aktualizovat),
- rozhraní ApplePay z nějakého jiného důvodu vyhodnotí, že platbu nelze provést (například pokud je brána zobrazena v iframe).
- nemáte povolenou metodu Apple Pay nebo CARD_CZ_CSOB_2 - jde o zvláštní případy, kdy máte jiného providera na platbu kartou nebo vaše e-shop platforma nepovoluje Apple Pay mimo svoje řešení,
- je to opakovaná platba (založená s parametrem initRecurring=true),
- je to verifikační platba (založená s parametrem verification=true), za takovou je považována i opakovaná iniciační platba.
- máte ve vašem e-shopu implementováno zobrazení platební brány Comgate v iframe (založená s parametrem “embedded”= true). V takovém případě není zobrazení povoleno ze strany Apple Pay. Analyzujeme řešení, při kterém by na Safari brána ze zobrazení iframe automaticky vyskočila.
Google Pay
Službu je možné použít pro platbu online na libovolném zařízení. U platby online je potřeba mít kartu uloženou na svém Google účtu nebo ji uložit v rámci prohlížeče Chrome v průběhu platby. Pro platbu přes mobilní zařízení je nutné si Google Pay nejprve stáhnout pomocí Google Store a přidat tam kartu. Není dostupné pouze na zařízeních Apple, pokud je dostupný Apple Pay (viz výše).
Zobrazení služby Google Pay
Zobrazení služby Google Pay se odvíjí podle toho, zda se výběr platebních metod nachází v košíku e-shopu, nebo e-shop využívá výběru metod od Comgate. Dále je potřeba rozlišit, zda má dojít k přesměrování plátce na karetní bránu, nebo se Google Pay zobrazí přímo v prostředí košíku e-shopu.
1. Tlačítko Google Pay v karetní bráně - V případě, že se výběr platebních metod nachází na straně Comgate, stačí mít povolenou metodu platby kartou CARD_CZ_CSOB_2. Po výběru této metody ze strany plátce probíhá platba standardním procesem s přesměrováním na platební bránu. Služba se zobrazí automaticky na karetní bráně. Zde je zároveň plátci umožněno zadat číslo karty ručně. Pokud zakládáte platbu s jinou metodou než CARD_CZ_CSOB_2 nebo GOOGLEPAY_REDIRECT, plátce po přesměrování na platební bránu musí vybrat “Platba kartou”, a pak bude moci zaplatit metodou Google Pay nebo kartou.
2. Tlačítko Google Pay v košíku e-shopu s přesměrování plátce na karetní bránu - Pokud je výběr platebních metod na straně e-shopu, platba se zakládá jako běžná platba, v požadavku je však třeba volat metodu GOOGLEPAY_REDIRECT. Následně dojde k přesměrování plátce na platební bránu pomocí získaného platebního odkazu. Tlačítko Google Pay se poté zobrazí na karetní bráně automaticky. Proces platby z pohledu plátce je stejný s první variantou.
Pokud obchodník nedělá kontrolu dostupnosti Google Pay na své straně, nemusí být tato varianta ve výsledku dostupná, i když si ji plátce vybral v košíku e-shopu a platba byla touto metodou založena.
Případy, když Google Pay se nezobrazí
Může se stát, že Google Pay plátci zobrazen nebude, pokud Google Pay vyhodnotí, že není možné platbu přes jejich rozhraní realizovat.
Google Pay se nezobrazí, když:
- plátce má nepodporovaný prohlížeč (Seznam browseru je zde v angličtině),
- nemáte povolenou metodu Google Pay nebo CARD_CZ_CSOB_2 - jde o zvláštní případy, když máte jiného providera na platbu kartou nebo e-shop platforma zakazuje Google Pay mimo jejich řešení,
- je to opakovaná platba (založená s parametrem initRecurring=true),
- je to verifikační platba (založená s parametrem verification =true),
- máte ve vašem e-shopu implementováno zobrazení platební brány Comgate v iframe(založená s parametrem “embedded” = true). V součastnosti analyzujeme možnost povolit používání Google Pay, i pokud máte bránu Comgate v iframe,
- rozhraní Google Pay z nějakého jiného důvodu vyhodnotí, že platbu nelze provést (více informací v dokumentaci Google v angličtině).
Odložená platba
Odložená platba umožňuje zákazníkům e-shopu odložit úhradu nákupu až o několik dnů. E-shop své peníze ale obdrží ve standardní době.
Pro zobrazení metody plátci (zákazníkovi e-shopu) je potřeba při založení platby volat metodu platby LATER_ALL. V případě, že se výběr platebních metod nachází na straně Comgate, plátci jsou zobrazeny všechny dostupné metody odložené platby. V případě, že má e-shop výběr platebních metod u sebe v košíku, doporučujeme jako název metody pro plátce uvést tento text: “Odložená platba”. Text popisku platební metody je “Nakupte hned, zaplaťte později.”
Tato metoda je dostupná pouze pro měnu CZK a občany České republiky.
Platba na třetiny
Platba na třetiny umožňuje zákazníkům e-shopu rozložit platbu za nákup na tři měsíční splátky. E-shop obdrží potvrzení o zaplacení ihned a ve standardní době mu poukážeme také hodnotu nákupu.
Pro zobrazení metody plátci (zákazníkovi e-shopu) je potřeba při založení platby volat metodu platby PART_ALL. V případě, že se výběr platebních metod nachází na straně Comgate, plátci je platba na splátky zobrazena vždy s hodnotou platby rovnou nebo vyšší 1500 CZK pro PART_TWISTO a 3000 CZK pro PART_SKIPPAY.
Tato metoda je dostupná pouze pro měnu CZK a občany České republiky.
SDK
SDK available at https://github.com/comgate-payments/sdk-php
Open-source solution: https://help.comgate.cz/docs/en/open-source-solution
Protocol specification
Uses HTTP POST. The connection between the e-shop and the Comgate payment gateway is realized by redirecting the payer from the e-shop to the payment gateway. After the payment is completed, the payer is redirected back to the e-shop. At the same time, communication between the e-shop server and the payment gateway server (server - server) takes place in the background. A detailed description of the communication protocol is available below on this page. Further related information is provided on the page describing the payment process from the user’s and e-shop point of view, initial settings in the Client Portal, recommended method of testing payment gateway integration or a detailed description of EET connections.
Sample implementation in PHP language can be downloaded here.
Payment process
Payment creation – optional
The step of creating payments is optional, but it is advisable to implement it in case you require the certainty of secure payment creation. It is possible to skip the implementation of this step if you do not need to identify individual payments in the system, but only require information that someone has paid you a certain amount. This is suitable, for example, when implementing donations or recharging funds to a customer’s virtual account, where you are only interested in who recharged what amount, but you do not need to differentiate individual recharges or limit recharges to a minimum amount. However, for a classic e-shop, where you pay for specific goods, it is inappropriate to skip this step.
The merchant uses HTTP requests to create payment transaction. Payment attributes including unique payment reference numbers are sent as POST parameters via HTTP protocol. Communication is only between the Merchant’s server and the payment gateway server. It is invisible to payer and the payer cannot change the payment parameters. The payment gateway server responds by sending a unique payment transaction identifier – transaction ID (Comgate payments system identifier) and URL to which to redirect the payer.
Example of payment creation - HTTP request:
curl -X POST -i --data "merchant=123456&price=10000&curr=CZK&label=Beatles%20-0%Help&refId=2010102600&method=ALL&prepareOnly=true&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y" https://payments.comgate.cz/v1.0/create
Example of payment creation - HTTP response:
HTTP/2 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
Communication between the customer’s system and the payment gateway is secured by password and IP whitelist (access is allowed only from IP addresses of the customer’s system). It is necessary to use the secure HTTPS protocol, which prevents the disclosure of the password if communications have been tapped. The password is transmitted as a POST parameter (not a GET parameter) so as not to be stored in the webserver communication log.
Redirection to the payment gateway
After creating a payment in the background, the e-shop will receive a payment URL to display the payment gateway. The payment gateway can be displayed in two ways. The first is by redirecting the payer to the address received by the e-shop in the HTTP response. Redirection is usually done by sending HTTP response 302:
HTTP response 302
HTTP/2 302 Found
Location: https://payments.comgate.cz/client/instructions/index?id=AB12-CD34-EF56
The second option is to display the payment gateway directly on the e-shop page using an iframe. For this variant, it is necessary to generate a payment URL in the standard manner, but instead of redirecting the customer to the gateway, iframe will be displayed on the e-shop page with the payment URL.
If the first step of creating a background payment is omitted, the payment is created only after the payer is redirected from the Client’s website to the payment gateway server or by sending a web form from the Client’s website to the payment gateway server. The payment parameters, including the unique payment reference number, are transmitted as GET or POST parameters of HTTP protocol.
Example of creating a payment by redirection (sending a web form) - HTTP request
curl -X POST -i --data "merchant=123456&price=10000&curr=CZK&label=Beatles%20-20Help&refId=2010102600&method=ALL" https://payments.comgate.cz/v1.0/create
Transfer of payment result in the background
Implementing this part will enable you automatically transmit information about the status of every payment translation directly to your server at the moment when the payment status is known. Transferring the payment result in the background is mandatory.
The payment result is transmitted to the customer via a HTTP query from the payment gateway server to the customer’s server. Identifiers and payment results are transmitted as POST parameters of HTTP protocol. This communication runs in the background.
The payer is redirected to the customer’s website and the payment identifiers are transferred as GET parameters of HTTP protocol. The sending of goods or services to the payer must be bound to the transfer of the payment result in the background, not to the resulting redirection of the payer to the customer’s website, because the information provided by redirection can easily be falsified by the payer.
Call parameters
parameter | type | mandatory | description |
---|---|---|---|
merchant | string | Yes | e-shop identifier in the Comgate system |
test | boolean | Yes | a value of “true” means that the payment was created as a test, a value of “false” means a production version. |
price | integer | Yes | price of the product in cents or pennies |
curr | string | Yes | currency code according to ISO 4217 |
label | string | Yes | short product description (1-16 characters) |
refId | string | Yes | payment reference (variable symbol, order number) in the e-shop system |
payerId | string | No | payer identifier in the e-shop system |
payerName | string | No | transfer of the name of the account belonging to the payer |
payerAcc | string | No | transfer of the payer’s account number |
method | string | No | payment method used, from the table of payment methods |
account | string | No | identifier of the e-shop bank account to which Comgate Payments will transfer the money |
string | Yes | payer’s contact e-mail | |
phone | string | No | payer’s contact telephone number |
name | string | No | product identifier - this item allows you to search the payment statistics of the Comgate payment system. |
transId | string | Yes | unique alphanumeric transaction identifier (code) (transactionId) |
secret | string | Yes | password for background communication |
status | string | Yes | current transaction status, values “PAID” - payment was successfully paid “CANCELED” - the payment was not completed correctly and is cancelled “AUTHORIZED” - the requested pre-authorization was successful |
fee | string | No | if the e-shop has set up automatic deduction of the payment fee, the transaction fee will be calculated in this field, otherwise, the field will take the value “unknown” |
eetData | JSON | No | structure with data after registration of the payment in EET |
Response parameters
parameter | type | mandatory | description |
---|---|---|---|
code | integer | Yes | Method return code and error description: the system expects a return code of 0 and a description of “OK” if the payment result has been received correctly. |
Example of transferring the payment result in the background - HTTP request
curl -X POST -i --data "merchant=merchant_com&test=false&price=10000&curr=CZK&label=Beatles%20-%20Help&refId=2010102600&method=CARD&email=info%40customer.com&phone=%2B420123456789&transId=AB12-EF34-IJ56&secret=ZXhhbXBsZS5jb206QUJDeHl6&status=PAID" https://example.com/handler.php
Example of transferring the payment result in the background - HTTP response
HTTP/2 200 OK
content-type: application/x-www-form-urlencoded; charset=UTF-8
Communication between the customer’s system and the payment gateway server is secured by a password and an IP whitelist. Access must be allowed only from the IP address of the payment gateway server. The ranges of IP addresses are defined in the Security section. It is mandatory to use the HTTPS protocol, which prevents the disclosure of the password if communications are tapped. The password is transmitted as a POST parameter (not a GET parameter) so as not to be stored in the webserver communication log.
The e-shop, on its part, ensures that the goods (service) provided within the paid transaction (identified by a unique transaction ID) will be issued to the payer only once (even if the result of the same payment is repeatedly transmitted to the customer’s server).
Redirection of the payer to the customer’s website
Based on the payment status, the payer is redirected to one of the three URLs that the e-shop chose when activating the service. Payment identifiers are transmitted as GET parameters of HTTP protocol. The customer system must be able to handle two basic situations:
- When redirecting the payer to the customer’s website, the payment result is not yet known. Payment is in PENDING status. This situation is completely normal and the e-shop must not present it to the payer as an error. The system is waiting either for the payment to be credited to the bank account or for confirmation from the payment provider. The e-shop will determine the final result of payment later either by submitting the payment result in the background, or by e-mail, or in the Client Portal.
- If the payment gateway determines the payment result immediately after the payment is made by the payer, then the payer is redirected to the respective URL (PAID or CANCELED). If the e-shop has implemented the transfer of the payment result in the background, then redirection to the customer’s website will take place after the successful transfer of the payment result in the background. The customer cannot send the goods or service to the payer only based on the URL used for redirection, as the payer could falsify the payment result by changing the URL in the web browser.
Example of redirecting the payer to the customer’s website - HTTP request
GET /result_ok.php?refId=2010102600&transId=AB12-EF34-IJ56 HTTP/2
Host: eshop.com
Payment gateway in the e-shop (iframe)
The payment gateway enables a display mode optimized for iframe. This functionality is suitable if you do not want to redirect the payer to the payment gateway, but display it within your system. In order for the payment gateway to be displayed in iframe, the embedded = true parameter must be used when creating the payment. The payment URL is generated in the standard manner, but instead of redirecting the customer to the gateway, an iframe with the payment URL will appear on the e-shop page. There are two options for display. First, it is possible to display the payment gateway directly in the cart or using a pop-up window over your website. Iframe implementation requires expertise in web technologies. Iframe can only be used for card payment. For other payment methods, the payer will always be redirected to a new page.
To properly display the payment gateway in an iframe on the website, we recommend that you make the following modifications to your website.
Payment gateway display settings
HTML code
<div id="comgate-container">
<iframe id='comgate-iframe' src ="[platební URL]" frameborder="0px"></iframe>
</div>
CSS style
#comgate-container {
display: none;
position:absolute;
z-index: 9999;
left: 50%;
top: 30px;
overflow: auto;
margin-left: -250px;
}
#comgate-iframe {
width: 504px;
height: 679px;
}
@media (max-height: 700px) {
#comgate-iframe {;
top: 0px;
}
}
JavaScript code
// funkce pro otevření iframu s bránou
function comgateOpen() {
var comgate_container = document.getElementById("comgate-container");
comgate_container.style.display = "block";
}
// funkce pro zavření iframu s bránou
function comgateClose() {
var comgate_container = document.getElementById("comgate-container");
comgate_container.style.display = "none";
}
To display the iframe, you need to call the comgateOpen () function. For example, by following up on a user action (clicking on a button, etc.). The comgateClose () function is then used to hide the iframe if necessary.
Example of calling the iframe display function by clicking on the “Pay” button:
HTML code
<button id="comgate-open" onclick="comgateOpen()">Zaplatit</button>
Redirection of customer after payment is completed
After the payment is completed by the customer, they are redirected to the e-shop to the URL that you set in the Client Portal. We recommend that you make one of the following adjustments to ensure that the customer is redirected directly to the return URL and does not remain inside the iframe.
The first option is to redirect the external page to the URL you specify. This will refresh the entire page.
JavaScript code for the inner page
window.top.location = window.self.location
The second option is to send a message from the page inside the iframe to the outside page and process the action on the outer page. Thus the entire page does not have to be refreshed
Please note that the actual payment result must be obtained in the background in the standard manner. For security reasons, it is not possible to rely on the result transmitted by the iframe message.
JavaScript code for the inner page, which sends a message to the outer page with the payment ID and payment status, e.g. for a paid payment:
window.parent.postMessage('[id platby]|PAID', '*');
JavaScript code for the outer page that processes the incoming message from iframe:
// catch the message sent by the iframe with postMessage
if (window.addEventListener ) {
window.addEventListener('message', function (e) {
// payment id and result is received with pipe '|' in between
let message = e.data.split('|', 2);
let message_id = message[0];
let message_result = message[1];
let result = '';
if (message_result === 'PAID') {
// handle PAID state
[...]
} else {
// handle other states etc. ...
[...]
}
}, false);
}
Payment gateway in iframe from the payer’s point of view
The Comgate payment gateway allows users to retry a payment if they failed to complete the payment the first time. How the payment gateway is displayed to the user in iframe depends on the selected payment method and also whether the selection of payment methods is on the e-shop side or on the Comgate side. If the selection of payment methods is on the e-shop side and the payment is already created with the payment method, the card payment method must be selected to display the iframe. If the user was unable to complete the payment the first time, only the card payment method is displayed again for the next attempt. This version is recommended.
If the e-shop does not create a payment with the selected payment method, the user is shown the selection of payment methods in the iframe. It is then necessary to choose card payment. If the user was unable to complete the payment, they are shown the selection of payment methods again in the iframe for the next attempt.
If a method other than card payment is selected at any step of the payment process, the payer will be redirected to a new page. The user will not return to the iframe.
Payment status
-
PENDING - the payment has been created, the final result of the payment is not yet known.
-
PAID - the payer has successfully completed the payment - it is possible to issue the goods, respectively provide the service.
-
CANCELED - the payment has not been made, the goods will not be issued, resp. the service will not be provided.
-
The payment can only be considered paid in PAID status. PENDING status is not final and may be followed by CANCELED stauts.
API protocol - Comgate payment gateway
Security
Communication between the Comgate payment system and the e-shop takes place in three ways.
- The server part of the e-shop solution connects as a client to the server part of the payment gateway and calls the methods for creating a payments, obtaining the payment status in the background, confirming pre-authorization, cancelling pre-authorization and obtaining a list of payment methods.
- The server part of the payment gateway connects as a client to the server part of the e-shop solution and calls the method for transmitting the payment result in the background.
- The payer’s (user’s) browser is redirected from the e-shop to the payment gateway and then from the payment gateway back to the e-shop.
The payment gateway only supports secure TLS / SSL protocol settings with the following cyphers enabled: https://github.com/cloudflare/sslconfig/blob/master/conf
In the case of server-server communication, communication is secured by a password (secret) and IP whitelist. These parameter settings can be defined in the Client Portal.
Creating a payment is preceded by the Cloudflare service. You can find a list of permitted Cloudflare IP addresses here: https://www.cloudflare.com/ips-v4
The range of IP addresses used by Comgate is defined as 89.185.236.55/32. This range is only used to transmit the payment result in the background.
Payment gateway methods
Payment buttons
We provide instant bank transfers (payment buttons) from all major banks in the Czech Republic, Poland and Slovakia. You can find a list of available banks in the code lists. In the case of payment buttons, it is possible to use functionalities such as refunds and cancellations.
The payment button cannot be displayed directly in the e-shop (iframe). The payer is always redirected to the bank.
Card payment
The payment gateway accepts payments using VISA, VISA Electron, Mastercard, Maestro. Payments are available in CZK, EUR, PLN, HUF, USD, GBP, RON, NOK and SEK. The gateway is available in 12 languages - Czech, Slovak, English, German, French, Polish, Hungarian, Croatian, Slovenian, Romanian, Norwegian and Swedish.
Many functionalities can be used for card payments. These include refunds, cancellations of unfinished payments, recurring payments (e.g. for subscriptions with regular debiting from the payer’s card) or pre-authorization. Card payment can also be viewed directly in the e-shop (iframe).
Apple Pay
Apple Pay is part of the Comgate payment gateway. To display the service to the customer, all you need to do is enable the CARD_CZ_CSOB_2 card payment method.
Within the service, it is not possible to use the recurring payment functionality because of the Apple Pay security principle and so-called card tokenization. Other functionalities are available.
Displaying of the Apple Pay service
Displaying of the Apple Pay service depends on whether the selection of payment methods is in the e-shop basket orwhether the e-shop uses payment method selection from Comgate. Furthermore, it is necessary to distinguish whether the payer should be redirected to the card gateway or whether Apple Pay will be displayed directly in the e-shop cart environment. Hence, we distinguish three options for displaying Apple Pay:
1. Apple Pay button in the card gateway - If the selection of payment methods is on the Comgate side, no adjustments are required to display the service. All you have to do is enable the CARD_CZ_CSOB_2 card payment method. After the payer selected the method, the payment takes place via the standard process with redirection to the payment gateway. The service is displayed automatically on the card gateway. Here, the payer is also allowed to enter the card number manually. If the payer reaches the gateway from a device or browser that does not allow Apple Pay, they will be able to make a card payment.
2. Apple Pay button in e-shop cart with payer redirection to the card gateway - If the selection of payment methods is on the e-shop side, the payment is established as a regular payment (more under creating payment), but the APPLEPAY_REDIRECT method must be called in the request. Subsequently, the payer will be redirected to the payment gateway using the obtained payment link. The Apple Pay button will then appear on the card gateway automatically. The payment process from the payer’s point of view is then identical to the first option.
Recommendations for when to display Apple Pay in the e-shop cart
Apple Pay is only available to users who have a Safari web browser and their own Apple device that has a Touch ID or Face ID. These devices include the iPhone, iPad, Apple Watch, and Mac. For this reason, we recommend that the service be displayed in the order only to clients who can pay with Apple Pay. Instructions can be found directly on Apple’s developer website.
Recommendations on how to display Apple Pay correctly
For the correct use of Apple Pay logs and names, see the Apple Pay Marketing Guide. To view the Apple Pay button, visit the Buttons and Marks website. We also recommend reading the guide to using the CSS styles available in Safari.
3. Apple Pay button included in the e-shop cart, without redirection to the card gateway - This section will be available soon.
Google Pay
The service can be used for online payments on any device. You need to have the card saved in your Google account or save it within the Chrome browser during the payment. To pay via mobile device, you must first download Google Pay using the Google Store and add the card there. Not available on Apple devices only if Apple Pay is available (see above).
Displaying Google Pay
The display of the Google Pay service depends on whether the selection of payment methods is in the e-shop basket or the e-shop uses a selection of methods from Comgate. It is also necessary to distinguish whether the payer should be redirected to the card gateway or whether Google Pay will appear directly in the e-shop basket.
1. Google Pay button in the card payment gateway - If the selection of payment methods is on the Comgate page, it is enough to have the CARD_CZ_CSOB_2 card payment method enabled. After the payer chooses this method, the payment takes place through a standard process with redirection to the payment gateway. The service will appear automatically on the card gateway. Here, the payer is also allowed to enter the card number manually. If you are making a payment with a method other than CARD_CZ_CSOB_2 or GOOGLEPAY_REDIRECT, the payer must select “Payment by card” after being redirected to the payment gateway, and then he will be able to pay with the Google Pay method or by card.
2. Google Pay button in the e-shop basket with redirection of the payer to the card gateway - If the selection of payment methods is on the e-shop side, the payment is established as a regular payment, but the GOOGLEPAY_REDIRECT method must be called in the request. Subsequently, the payer will be redirected to the payment gateway using the obtained payment link. The Google Pay button will then appear on the card gateway automatically. The payment process from the point of view of the payer is the same as the first variant.
If the merchant does not check the availability of Google Pay on their side, this option may not be available as a result, even if the payer chose it in the e-shop basket and the payment was established with it.
Cases when Google Pay does not appear
It may happen that Google Pay will not be displayed to the payer if Google Pay evaluates that it is not possible to make the payment through their interface.
Google Pay doesn’t appear when:
- the payer has an unsupported browser (the list of browsers is here in English),
- you do not have the Google Pay or CARD_CZ_CSOB_2 method enabled - these are special cases when you have another provider for card payment or the Eshop platform prohibits Google Pay outside of their solution,
- it is a recurring payment (established with the parameter initRecurring=true),
- it is a verification payment (established with the parameter verification =true),
- it is pre-authorization (established with preauth=true),
- you have implemented the display of the Comgate payment gateway in an iframe in your e-shop (set up with the parameter “embedded” = true). We are currently analyzing the possibility of enabling the use of Google Pay even if you have a Comgate gateway in i-frame,
- the Google Pay interface evaluates that the payment cannot be made for some other reason (more information in the Google documentation in English).
Postponed payment
Postponed payment allows e-shop customers to defer the payment of the purchase for up to several days. However, the e-shop will receive its money in the standard time.
To display the method to the payer (e-shop customer), it is necessary to call the payment method LATER_ALL when creating the payment. If the selection of payment methods is on the Comgate site, the payer is shown all available methods of postponed payment. If the e-shop has a selection of payment methods in the cart, we recommend that you enter the following text as the method name for the payer: “Postponed payment”. The text of the payment method label is “Buy now, pay later.”
This method is only available in CZK and for citizens of the Czech Republic.
Pay in three
Pay in three allows e-shop customers to split purchases into 3 payments. Customer will pay the first “Third” right on the checkout and other payments will be automatically withdrawn from the debit/credit card each month until the full order amount has been paid. The e-shop will receive confirmation of payment immediately and settlement will be done based on the standard rules.
To display the method to the payer (e-shop customer), it is necessary to call the PART_ALL payment method when creating the payment. If the selection of payment methods is on the Comgate side, the Pay in three is always shown to the payer with a payment value equal to or greater than 1500 CZK for PART_TWISTO and 3000 CZK for PART_SKIPPAY.
This method is only available for the currency CZK and citizens of the Czech Republic.
SDK
SDK je k dispozícii na adrese https://github.com/comgate-payments/sdk-php
Riešenie s otvoreným zdrojovým kódom: https://help.comgate.cz/docs/en/open-source-solution
Špecifikácie protokolu
Používa HTTP POST. Prepojenie medzi e-shopom a platobnou bránou Comgate je realizované pomocou presmerovania platiteľa z e-shopu na platobnú bránu. Po vykonaní platby je platca presmerovaný späť do e-shopu. Zároveň na pozadí prebieha komunikácia medzi serverom e-shopu a serverom platobnej brány (server - server). Detailný opis komunikačného protokolu nájdete nižšie na tejto stránke. Ďalšie súvisiace informácie nájdete na stránkach, ktoré opisujú proces platby z pohľadu užívateľa a e-shopu, počiatočné nastavenie v klientskom portáli, odporúčaný spôsob testovania integrácie platobnej brány alebo detailný opis napojenia na EET.
Použijte PHP Software development kit (SDK)
Pre snadnú implementáciu platobnej brány môžete použíť tento PHP SDK (inštalácia cez composer)
Priebeh platby
Založenie platby – voliteľné
Krok založenia platby je voliteľný, je však vhodné ho implementovať v prípade, keď požadujete istotu zabezpečeného založenia platby. Vynechanie implementácie tohto kroku je možné v prípade, kedy jednotlivé platby nepotrebujete v systéme identifikovať, ale stačí vám informácia, že vám niekto zaplatil určitú čiastku.
Je to vhodné napríklad pri implementácii darcovských príspevkov alebo dobíjaní prostriedkov na virtuálny účet zákazníka, kedy vás zaujíma len to, kto dobíja a akú sumu, ale nepotrebujete rozlišovať jednotlivé dobitie zákazníka alebo obmedziť dobitie na minimálnu čiastku atď. Pre klasický e-shop, kde platíte za konkrétny tovar, je však vynechanie tohto kroku nevhodné.
Platbu e-shopu zakladá HTTP požiadavkou na server platobnej brány. Parametre platby, vrátane unikátneho referenčného čísla platby, sú odovzdané ako POST parametre HTTP protokolu. Táto komunikácia prebieha medzi serverom Klienta a serverom platobnej brány. Platiteľ ju nevidí a nemôže meniť parametre platby. Server platobnej brány vráti Klientovi unikátny identifikátor transaction ID (identifikátor v Comgate platobnom systéme) a URL adresu, na ktorú má presmerovať Platiteľ.
Parametre volania
parameter | typ | povinný | opis |
---|---|---|---|
merchant | string | A | identifikátor e-shopu v systéme Comgate |
test | boolean | A | Hodnota „true“ znamená, že platba bola založená ako testovacia, hodnota „false“ znamená produkčnú verziu. |
price | integer | A | cena za výrobok v centoch alebo halieroch |
curr | string | A | kód meny podľa ISO 4217 |
label | string | A | krátky opis produktu (1 – 16 znakov) |
refId | string | A | referencia platby (variabilný symbol, číslo objednávky) v systéme e-shopu |
payerId | string | N | identifikátor Platiteľa v systéme e-shopu |
payerName | string | N | odovzdanie mena účtu patriaceho Platiteľovi |
payerAcc | string | N | odovzdanie čísla účtu Platiteľa |
method | string | N | použitá metóda platby, z tabuľky platobných metód |
account | string | N | identifikátor bankového účtu e-shopu, na ktorý Comgate Payments prevedie peniaze |
string | A | kontaktný email na Platiteľa | |
phone | string | N | kontaktný telefón na Platiteľa |
name | string | N | identifikátor produktu - podľa tejto položky je možné vyhľadávať v štatistikách platieb Comgate platobného systému. |
transId | string | A | unikátny alfanumerický identifikátor (kód) transakcie (transactionId) |
secret | string | A | heslo pre komunikáciu na pozadí |
status | string | A | status - aktuálny stav transakcie, hodnoty PAID - platba bola úspešne zaplatená CANCELLED - platba nebola dokončená korektne a je zrušená Authorized - vyžiadaná predautorizácia prebehla úspešne |
fee | string | N | Ak má e-shop nastavené automatické strhávanie poplatku za platbu, bude v tomto poli spočítaný poplatok za transakciu, inak bude pole nadobúdať hodnoty “unknown”. |
Parametre odpovedí
parameter | typ | povinný | opis |
---|---|---|---|
code | integer | A | Návratový kód metódy a opis chyby: systém očakáva HTTP kód 200 v prípade, že výsledok platby bol v poriadku prijatý. |
Príklad založenia platby na pozadí - HTTP request:
curl -X POST -i --data "merchant=123456&price=10000&curr=CZK&label=Beatles%20-0%Help&refId=2010102600&method=ALL&prepareOnly=true&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y" https://payments.comgate.cz/v1.0/create
Príklad založenia platby na pozadí - HTTP response:
HTTP/2 200 OK
content-type: application/x-www-form-urlencoded; charset=UTF-8
code=0&message=OK&transId=AB12-CD34-EF56&redirect=https%3A%2F%2Fpayments.comgate.cz%2Fclient%2Finstructions%2Findex%3Fid%3DAB12-CD34-EF56
Komunikácia medzi systémom Klienta a platobnou bránou je zabezpečená pomocou hesla a IP whitelistu (prístup je povolený len z IP adries systému Klienta). Nevyhnutné je použitie protokolu HTTPS, ktorý znemožňuje prezradenie hesla pri prípadnom odpočúvaní komunikácie. Heslo je odovzdávané ako POST parameter (nie GET parameter) preto, aby sa neukladalo v logu komunikácie webového servera.
Presmerovanie na platobnú bránu
Po založení platby na pozadí dostane e-shop platobné URL na zobrazenie platobnej brány. Platobná brána môže byť zobrazená dvoma spôsobmi. Prvým spôsobom je presmerovanie platiteľa na adresu, ktorú dostal e-shop v HTTP odpovedi. Presmerovanie sa zvyčajne vykonáva odoslaním HTTP odpovede 302:
HTTP odpoveď 302
HTTP/2 302 Found
Location: https://payments.comgate.cz/client/instructions/index?id=AB12-CD34-EF56
Druhou možnosťou je zobrazenie platobnej brány priamo na stránke e-shopu pomocou iframe. Pre tento variant je potrebné vygenerovať platobné URL štandardným spôsobom, ale namiesto presmerovania zákazníka na bránu sa zobrazí na stránke e-shopu iframe s platobnou URL.
V prípade vynechania prvého kroku založenia platby na pozadí je platba založená až pri presmerovaní Platiteľa z webu Klienta na server platobnej brány alebo odoslaní webového formulára z webu Klienta na server platobnej brány. Parametre platby, vrátane unikátneho referenčného čísla platby, sú odovzdané ako GET alebo POST parametre HTTP protokolu.
Príklad založenia platby presmerovaním (odoslaním webového formulára) - HTTP request
curl -X POST -i --data "merchant=123456&price=10000&curr=CZK&label=Beatles%20-20Help&refId=2010102600&method=ALL" https://payments.comgate.cz/v1.0/create
Odovzdanie výsledku platby na pozadí
Implementácia tejto časti vám zaistí automatické odovzdanie informácie o stave každej platobnej transakcie priamo na váš server v okamihu, keď je stav platby známy. Odovzdávanie výsledku platby na pozadí je povinné.
Výsledok platby je Klientovi odovzdaný HTTP požiadavkou zo servera platobnej brány na server Klienta. Identifikátory a výsledok platby sú odovzdané ako POST parametre HTTP protokolu. Táto komunikácia sa uskutočňuje na pozadí.
Platiteľ je presmerovaný na webové stránky Klienta a identifikátory platby sú odovzdané ako GET parametre HTTP protokolu. Odoslanie tovaru alebo služby Platiteľa musí byť viazané na odovzdanie výsledku platby na pozadí, nie na výsledné presmerovanie Platiteľa na webové stránky Klienta, pretože informácie zaslané presmerovaním môže Platiteľ ľahko podstrčiť.
Príklad odovzdania výsledku platby na pozadí - HTTP request
curl -X POST -i --data "merchant=merchant_com&test=false&price=10000&curr=CZK&label=Beatles%20-%20Help&refId=2010102600&method=CARD&email=info%40customer.com&phone=%2B420123456789&transId=AB12-EF34-IJ56&secret=ZXhhbXBsZS5jb206QUJDeHl6&status=PAID" https://example.com/handler.php
Príklad odovzdania výsledku platby na pozadí - HTTP response
HTTP/2 200 OK
content-type: application/x-www-form-urlencoded; charset=UTF-8
Komunikácia medzi systémom Klienta a serverom platobnej brány je zabezpečená pomocou hesla a IP whitelistu. Prístup musí byť povolený iba z IP adresy servera platobnej brány. Rozsahy IP adries sú definované v sekcii Zabezpečenie. Je povinné použiť protokol HTTPS, ktorý znemožňuje prezradenia hesla pri prípadnom odpočúvaní komunikácie. Heslo je odovzdávané ako POST parameter (nie GET parameter) preto, aby sa neukladalo v logu komunikácie webového servera.
E-shop na svojej strane zabezpečí, že tovar (služba) poskytnutý v rámci zaplatenej transakcie (identifikovanej pomocou unikátneho transaction ID) bude vydaný Platiteľom iba raz (aj pri opakovanom odovzdaní výsledku rovnakej platby na server Klienta).
Presmerovanie Platiteľa na web Klienta
Platiteľ je na základe stavu platby presmerovaný na jedno z troch URL, ktoré e-shop zvolil pri aktivácii služby. Identifikátory platby sú odovzdané ako GET parametre HTTP protokolu. Systém klienta musí byť schopný ošetriť dve základné situácie:
- Pri presmerovaní platiteľa na web klienta výsledok platby ešte nie je známy. Platba je v stave PENDING. Táto situácia je úplne bežná a e-shop ju nesmie platiteľovi prezentovať ako chybu. Systém čaká buď na pripísanie platby na bankový účet alebo na potvrdenie od poskytovateľa platby. Konečný výsledok platby sa e-shop dozvie neskôr buď odovzdaním výsledku platby na pozadí alebo e-mailom alebo na klientskom portáli.
- Ak sa platobná brána dozvie výsledok platby okamžite po uskutočnení platby platiteľom, potom je platiteľ smerovaný na príslušné URL (PAID alebo CANCELLED). Ak e-shop implementoval odovzdávanie výsledku platby na pozadí, potom sa presmerovanie na web Klienta vykoná až po úspešnom odovzdaní výsledku platby na pozadí. Platiteľovi nemožno odoslať tovar alebo službu, ktorú objednal, iba na základe URL použitej na presmerovanie, pretože platiteľ by mohol výsledok platby podstrčiť zmenou URL vo webovom prehliadači.
Príklad presmerovania Platiteľa na web Klienta - HTTP request
GET /result_ok.php?refId=2010102600&transId=AB12-EF34-IJ56 HTTP/2
Host: eshop.com
Platobná brána v e-shope (iframe)
Platobná brána umožňuje zobrazenie optimalizované pre iframe. Táto funkcia je vhodná v prípade, že nechcete platiteľa presmerovávať na platobnú bránu, ale zobraziť ju v rámci svojho systému. Aby sa platobná brána zobrazila v iframe, je potrebné pri založení platby použiť parameter „embedded“ = true. Platobné URL je vygenerované štandardným spôsobom, ale namiesto presmerovania zákazníka na bránu sa zobrazí na stránke e-shopu iframe s platobnou URL.
Na zobrazenie sú dve možnosti. Jednak je možné platobnú bránu zobraziť priamo v košíku alebo pomocou vyskakovacieho okna nad vašou webovou stránkou. Implementácia iframu vyžaduje znalosť webových technológií. Iframe je možné použiť len pre platbu kartou. Pri ostatných platobných metód dôjde vždy k presmerovanie platiteľa na novú stránku.
Pre správne zobrazenie platobnej brány v iframe na webovej stránke odporúčame vykonať nasledujúcu úpravu vašich webových stránok.
Nastavenie zobrazenia platobnej brány
HTML kód
<div id="comgate-container">
<iframe id='comgate-iframe' src ="[platební URL]" frameborder="0px"></iframe>
</div>
CSS štýly
#comgate-container {
display: none;
position:absolute;
z-index: 9999;
left: 50%;
top: 30px;
overflow: auto;
margin-left: -250px;
}
#comgate-iframe {
width: 504px;
height: 679px;
}
@media (max-height: 700px) {
#comgate-iframe {;
top: 0px;
}
}
Javascriptový kód
// funkce pro otevření iframu s bránou
function comgateOpen() {
var comgate_container = document.getElementById("comgate-container");
comgate_container.style.display = "block";
}
// funkce pro zavření iframu s bránou
function comgateClose() {
var comgate_container = document.getElementById("comgate-container");
comgate_container.style.display = "none";
}
Na zobrazenie iframe je potrebné vyvolať funkciu comgateOpen (). Napríklad nadviazaním na akciu užívateľa (kliknutie na tlačidlo a pod.). Funkcia comgateClose () potom slúži na prípadné skrytie iframe.
Príklad vyvolania funkcie na zobrazenie iframe kliknutím na tlačidlo „Zaplatiť“:
HTML kód
<button id="comgate-open" onclick="comgateOpen()">Zaplatit</button>
Presmerovanie zákazníka po dokončení platby
Po dokončení platby zákazníkom dochádza k jeho presmerovaniu do e-shopu na URL, ktorú ste nastavili na klientskom portáli. Odporúčame vykonať jednu z nasledujúcich úprav, ktorá zaistí, že zákazník bude presmerovaný priamo na návratovú URL a nezostane tak vnútri iframe.
Prvou možnosťou je presmerovať vonkajšiu stránku na vami určenú URL. Tým dôjde k obnoveniu celej stránky.
Javascriptový kód pre vnútornú stránku
window.top.location = window.self.location
Druhou možnosťou je zo stránky vnútri iframe poslať správu vonkajšej stránke a na vonkajšej strane túto udalosť spracovať. Nemusí teda dôjsť k obnoveniu celej stránky.
Pozor, skutočný výsledok platby je potrebné získať na pozadí štandardným spôsobom. Z bezpečnostných dôvodov nie je možné spoliehať na výsledok odovzdaný správou z iframe.
Javascriptový kód pre vnútornú stránku, ktorý pošle vonkajšej stránke správu s ID platby a stavom platby, napr. pre zaplatenú platbu:
window.parent.postMessage('[id platby]|PAID', '*');
Javascriptový kód pre vonkajšiu stránku, ktorý spracuje prichádzajúcu správu z iframe:
// odchycení zprávy poslané z iframu pomocí postMessage
if (window.addEventListener ) {
window.addEventListener('message', function (e) {
// přijde mi id a výsledek platby, oddělovač je “roura”
let message = e.data.split('|', 2);
let message_id = message[0];
let message_result = message[1];
let result = '';
if (message_result === 'PAID') {
// obsloužení stavu PAID
[...]
} else {
// obsloužení dalších stavů, atd ...
[...]
}
}, false);
}
Platobná brána v iframe z pohľadu platcu
Platobná brána Comgate umožňuje užívateľom opakovať platbu, ak sa im nepodarilo dokončiť platbu na prvýkrát. Zobrazenie platobnej brány v iframe užívateľovi je závislé od zvolenej platobnej metódy a tiež, či sa výber platobných metód nachádza na strane e-shopu alebo na strane Comgate.
V prípade, že je výber platobných metód na strane e-shopu a platba je tak založená už s platobnou metódou, musí byť na zobrazenie iframe zvolená metóda platby kartou. Ak sa užívateľovi nepodarilo platbu na prvýkrát dokončiť, pre ďalší pokus sa mu opäť zobrazí iba metóda platby kartou. Táto verzia je odporúčaná.
V prípade, že e-shop nezakladá platbu s už vybranou platobnou metódou, užívateľovi sa v iframe zobrazí výber platobných metód. Tu je následne potrebné zvoliť platbu kartou. Ak sa užívateľovi nepodarilo platbu dokončiť, pre ďalší pokus sa mu opäť zobrazí výber platobných metód v iframe.
Pokiaľ dôjde v akomkoľvek kroku platobného procesu k vybratiu inej metódy než platby kartou, dôjde k presmerovaniu platiteľa na novú stránku. Užívateľ sa už späť do iframe nevráti.
Stavy platieb
- PENDING – platba bola založená, finálny výsledok platby zatiaľ nie je známy.
- PAID – platiteľ úspešne dokončil platbu - je možné vydať tovar, resp. sprístupniť službu.
- CANCELLED – platba nebola zaplatená, tovar nebude vydaný, resp. služba nebude poskytnutá.
Platbu možno považovať za zaplatenú iba v stave PAID. Stav PENDING nie je koncový a môže po ňom nasledovať stav CANCELLED.
API protokol - platobná brána Comgate
Zabezpečenie
Komunikácia medzi Comgate platobným systémom a e-shopom sa uskutočňuje troma spôsobmi.
- Serverová časť e-shopového riešenia sa ako klient pripojí k serverovej časti platobnej brány a vyvolá metódy na založenie platby, získanie stavu platby na pozadí, potvrdenie predautorizácie, zrušenie predautorizácie a získanie zoznamu platobných metód.
- Serverová časť platobnej brány sa ako klient pripojí k serverovej časti e-shopového riešenia a vyvolá metódu na odovzdanie výsledku platby na pozadí.
- Prehliadač platiteľa (používateľa) je presmerovaný z e-shopu na platobnú bránu a následne z platobnej brány späť do e-shopu.
Vo všetkých troch prípadoch je nevyhnutné použitie šifrovaného protokolu HTTPS. Platobná brána podporuje iba bezpečné nastavenie TLS / SSL protokolu s nasledujúcimi povolenými šiframi: https://github.com/cloudflare/sslconfig/blob/master/conf
V prípade komunikácie server - server je komunikácia zabezpečená pomocou hesla (Secret) a nastavenia IP whitelistu. Nastavenie týchto parametrov je možné vykonať v prostredí klientskeho portálu.
Zakladanie platieb je predradené službe CloudFlare. Zoznam povolených IP adries CloudFlare nájdete tu: https://www.cloudflare.com/ips-v4
Rozsah IP adries používaný systémom Comgate je definovaný ako 89.185.236.55/32. Tento rozsah sa používa iba na odovzdanie výsledku platby na pozadí.
Metódy platobnej brány
Platobné tlačidlá
Zrýchlené bankové prevody (platobné tlačidlá) poskytujeme od všetkých významných bánk v Česku, Poľsku a na Slovensku. Zoznam dostupných bánk nájdete v číselníkoch. V prípade platobných tlačidiel je možné využiť funkcie, ako sú refundácia a storno platby.
Platobné tlačidlo nie je možné zobraziť priamo v e-shope (iframe). Platiteľ je vždy presmerovaný do banky.
Platba kartou
Platobná brána akceptuje platby kartou VISA, VISA Electron, Mastercard, Maestro. Platby sú dostupné v menách EUR, CZK, PLN, HUF, USD, GBP a RON, NOK a SEK. Je k dispozícii v 14 jazykoch - v slovenčine, češtine, angličtine, nemčine, francúzštine, poľštine, maďarčine, chorvátčine, slovinčine, rumunčine, nórčine a švédčine.
V rámci platby kartou je možné využiť mnoho funkcií. Medzi ne patrí refundácia platby, storno nedokončenej platby, opakované platby (napríklad pre predplatné s pravidelným strhávaním prostriedkov z karty platiteľa) alebo predautorizácia. Platbu kartou možno tiež zobraziť priamo v e-shope (iframe).
Apple Pay
Služba Apple Pay je súčasťou platobnej brány Comgate. Na zobrazenie služby zákazníkovi stačí mať povolenú metódu platby kartou CARD_CZ_CSOB_2.
V rámci služby nie je možné použiť funkciu Opakované platby kvôli bezpečnostnému princípu Apple Pay a tzv. kartovej tokenizácii. Ostatné funkcie sú k dispozícii.
Zobrazenie služby Apple Pay
Zobrazenie služby Apple Pay sa odvíja podľa toho, či sa výber platobných metód nachádza v košíku e-shopu alebo e-shop využíva výber metód od Comgate. Ďalej je potrebné rozlíšiť, či má dôjsť k presmerovaniu platiteľa na kartovú bránu alebo sa Apple Pay zobrazí priamo v prostredí košíka e-shopu. Rozlišujeme teda tri možnosti zobrazenia Apple Pay:
1. tlačidlo Apple Pay v kartovej bráne - V prípade, že sa výber platobných metód nachádza na strane Comgate, nie sú na zobrazenie služby potrebné žiadne úpravy. Stačí mať povolenú metódu platby kartou CARD_CZ_CSOB_2. Po výbere tejto metódy zo strany platiteľa sa uskutočňuje platba štandardným procesom s presmerovaním na platobnú bránu. Služba sa zobrazí automaticky na kartovej bráne. Tu je zároveň platcovi umožnené zadať číslo karty ručne. Ak sa na bránu dostane platiteľ zo zariadenia či prehliadača, ktoré Apple Pay neumožňujú, bude môcť vykonať aspoň úhradu platobnou kartou.
2. tlačidlo Apple Pay v košíku e-shopu s presmerovaním platiteľa na kartovú bránu - Ak je výber platobných metód na strane e-shopu, platba sa zakladá ako bežná platba, v špecifikácii však treba vyvolať metódu APPLEPAY_REDIRECT. Následne dôjde k presmerovaniu platiteľa na platobnú bránu pomocou získaného platobného odkazu. Tlačidlo Apple Pay sa potom zobrazí na kartové bráne automaticky. Proces platby z pohľadu platcu je následne zhodný s prvou variantom.
Odporúčanie, kedy zobrazovať Apple Pay v košíku e-shopu Služba Apple Pay je dostupná iba užívateľom, ktorí majú k dispozícii webový prehliadač Safari a vlastné zariadenie od spoločnosti Apple, ktoré disponuje Touch ID alebo Face ID. K týmto zariadeniam patria iPhone, iPad, Apple Watch a počítač Mac. Z tohto dôvodu odporúčame službu zobrazovať v objednávke iba klientom, ktorí platiť s Apple Pay môžu. Návod nájdete priamo na stránkach Apple pre vývojárov.
Odporúčanie, ako správne zobrazovať Apple Pay Správne použitie log a názvov Apple Pay nájdete v sprievodcovi Marketingem od Apple Pay. Ako zobraziť tlačidlo Apple Pay, nájdete na stránkach Buttons and Marks. Ďalej odporúčame si prečítať sprievodcu k používaniu CSS štýlov, dostupných v Safari.
3. tlačidlo Apple Pay súčasťou košíka e-shopu, bez presmerovania na kartovú bránu - Túto časť pre vás pripravujeme.
Google Pay
Službu je možné použiť pre platbu online na ľubovoľnom zariadení. Pri platbe online je potrebné mať kartu uloženú na svojom Google účte alebo ju uložiť v rámci prehliadača Chrome v priebehu platby. Pre platbu cez mobilné zariadenie je nutné si Google Pay najskôr stiahnuť pomocou Google Store a pridať tam kartu. Nie je dostupné iba na zariadeniach Apple, ak je dostupný Apple Pay (pozri vyššie).
Zobrazenie služby Google Pay
Zobrazenie služby Google Pay sa odvíja podľa toho, či sa výber platobných metód nachádza v košíku e-shopu alebo e-shop využíva výber metód od Comgate. Ďalej je potrebné rozlíšiť, či má dôjsť k presmerovaniu platiteľa na kartovú bránu alebo sa Google Pay zobrazí priamo v prostredí košíka e-shopu.
1. Tlačidlo Google Pay v kartovej bráne - V prípade, že sa výber platobných metód nachádza na strane Comgate stačí mať povolenú metódu platby kartou CARD_CZ_CSOB_2. Po výbere tejto metódy zo strany platiteľa prebieha platba štandardným procesom s presmerovaním na platobnú bránu. Služba sa zobrazí automaticky na kartovej bráne. Tu je zároveň platiteľovi umožnené zadať číslo karty ručne. Pokiaľ zakladáte platbu s inou metódou ako CARD_CZ_CSOB_2 alebo GOOGLEPAY_REDIRECT, platca po presmerovaní na platobnú bránu musí vybrať “Platba kartou” a potom bude môcť zaplatiť metódou Google Pay alebo kartou.
2. Tlačidlo Google Pay v košíku e-shopu s presmerovaním platiteľa na kartovú bránu - Pokiaľ je výber platobných metód na strane e-shopu, platba sa zakladá ako bežná platba, v požiadavke je však potrebné volať metódu GOOGLEPAY_REDIRECT. Následne dôjde k presmerovaniu platiteľa na platobnú bránu pomocou získaného platobného odkazu. Tlačidlo Google Pay sa potom zobrazí na kartovej bráne automaticky. Proces platby z pohľadu platiteľa je rovnaký s prvým variantom.
Pokiaľ obchodník nerobí kontrolu dostupnosti Google Pay na svojej strane, nemusí byť tento variant vo výsledku dostupný, aj keď si ho platiteľ vybral v košíku eshopu a platba mu s ním bola založená.
Prípady, keď Google Pay sa nezobrazí
Môže sa stať, že Google Pay platiteľovi zobrazený nebude, pokiaľ Google Pay vyhodnotí, že nie je možné platbu cez ich rozhranie realizovať.
Google Pay sa nezobrazí, keď:
- platiteľ má nepodporovaný prehliadač (Zoznam browsera je tu v angličtine) ,
- nemáte povolenú metódu Google Pay alebo CARD_CZ_CSOB_2 - ide o zvláštnych prípadoch, keď máte iného providera na platbu kartou alebo Eshop platforma zakazuje Google Pay mimo ich riešenia,
- je to opakovaná platba (založená s parametrom initRecurring=true),
- je to verifikačná platba (založená s parametrom verification = true),
- je to predautorizácia (založená s parametrom preauth=true),
- máte vo vašom e-shope implementované zobrazenie platobnej brány Comgate v iframe (založená s parametrom “embedded” = true). V súčasnosti analyzujeme možnosť povoliť používanie Google Pay aj pokiaľ máte bránu Comgate v i-frame,
- rozhranie Google Pay z nejakého iného dôvodu vyhodnotí, že platbu nie je možné vykonať (viac informácií v dokumentácii Google v angličtine).
Odložená platba
Odložená platba umožňuje zákazníkom e-shopu odložiť úhradu nákupu až o niekoľko dní. E-shop svoje peniaze ale dostane v štandardnom čase.
Na zobrazenie metódy platiteľovi (zákazníkovi e-shopu) je potrebné pri založení platby vyvolať metódu platby LATER_ALL. V prípade, že sa výber platobných metód nachádza na strane Comgate, pre platiteľa sú zobrazené všetky dostupné metódy odloženej platby. V prípade, že má e-shop výber platobných metód pri sebe v košíku, odporúčame ako názov metódy pre platiteľa uviesť tento text: „Odložená platba“. Text opisu platobnej metódy je „Nakúpte hneď, zaplaťte neskôr“.
Táto metóda je dostupná len pre menu CZK a občanov Českej republiky.
TAG_api_payment_methods
create
Code samples
# You can also use wget
curl -X POST https://payments.comgate.cz/v1.0/create \
--data "&merchant=123456&test=true&price=1000&curr=CZK&label=Product 123&refId=order445566&method=ALL&email=platce@email.com&prepareOnly=false&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y" \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Accept: application/x-www-form-urlencoded'
<?php
require 'vendor/autoload.php';
$headers = array(
'Content-Type' => 'application/x-www-form-urlencoded',
'Accept' => 'application/x-www-form-urlencoded',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_params = [
"merchant" => "123456",
"test" => "true",
"price" => "1000",
"curr" => "CZK",
"label" => "Product 123",
"refId" => "order445566",
"method" => "ALL",
"email" => "platce@email.com",
"prepareOnly" => "false",
"secret" => "gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y",
];
try {
$response = $client->request('POST','https://payments.comgate.cz/v1.0/create', array(
'headers' => $headers,
'form_data' => $request_params,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
String params = "&merchant=123456&test=true&price=1000&curr=CZK&label=Product 123&refId=order445566&method=ALL&email=platce@email.com&prepareOnly=false&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y";
byte[] postData = params.getBytes();
URL obj = new URL("https://payments.comgate.cz/v1.0/create");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setDoOutput(true);
con.setRequestMethod("POST");
con.setRequestProperty("Content-Type", "application/x-www-form-urlencoded");
con.setRequestProperty("Content-Length", Integer.toString(postData.length));
OutputStream os = con.getOutputStream();
os.write(postData);
os.flush();
os.close();
BufferedReader in = new BufferedReader(new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
import requests
headers = {
'Content-Type': 'application/x-www-form-urlencoded',
'Accept': 'application/x-www-form-urlencoded'
}
r = requests.post('https://payments.comgate.cz/v1.0/create', params={
"merchant": "123456",
"test": "true",
"price": "1000",
"curr": "CZK",
"label": "Product 123",
"refId": "order445566",
"method": "ALL",
"email": "platce@email.com",
"prepareOnly": "false",
"secret": "gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y",
}, headers = headers)
print(r.text)
POST /v1.0/create
Access is protected by IP address validation and the integrity of transmitted data is ensured using the HTTPS protocol. The step of creating payments is optional, but it is advisable to implement it in case you require the certainty of secure payment creation. It is possible to skip the implementation of this step if you do not need to identify individual payments in the system, but only require information that someone has paid you a certain amount. This is suitable, for example, when implementing donations or recharging funds to a customer’s virtual account, where you are only interested in who recharged what amount, but you do not need to differentiate individual recharges or limit recharges to a minimum amount. However, for a classic e-shop, where you pay for specific goods, it is inappropriate to skip this step. The merchant uses HTTP requests to create payment transaction. Payment attributes including unique payment reference numbers are sent as POST parameters via HTTP protocol. Communication is only between the Merchant’s server and the payment gateway server. It is invisible to payer and the payer cannot change the payment parameters. The payment gateway server responds by sending a unique payment transaction identifier – transaction ID (Comgate payments system identifier) and URL to which to redirect the payer
The payment gateway server responds only if the payment is created in a background. All parameters are urlencoded, as in the case of an HTTP request. If the payment is created through redirection (the prepareOnly parameter is ‘false’), then the payment gateway server directly redirects the Payer to the appropriate URL or displays an error message.
Choice of payment method
We recommend to display selection of payment methods to Payer during the purchase process and, based on his choice, create the payment with the method parameter on one specific value (eg payment by card or payment by bank transfer, etc.). Then, the page of the specific payment provider (bank) will be displayed directly.
If the method parameter is not filled in with one specific value, the offer of payment methods will be displayed on the payment gateway. The offer of payment methods can be specified by a simple expression, which is entered in the method parameter. The expression is always evaluated on the basis of the methods that the e-shop has enabled.
Allowed method identifier delimiters are ‘+’ for method addition and ‘-’ for method subtraction from / to selection.
Example:
The payment gateway allows the Payer to have one specific payment method pre-selected when selecting a payment method in the Comgate gateway environment. In this case Payer only needs to be redirected to the payment gateway using the obtained payment link with the added parameter ‘method’ with the selected method.
The payment link can therefore look like this:https://payments.comgate.cz/client/instructions/index?id=ABCDEFGHIJ&method=CARD_CZ_CS
After getting at the payment gateway, the Payer will already have the CARD_CZ_CS method checked, but the selection of the method will remain on the Payer.
Pre-authorization
The payment gateway allows to enter, confirm and cancel pre-authorizations of card payments. The payment is created in the standard way, it is only necessary to specify the parameter preauth = true. After Payer enters data at the payment gateway, the corresponding amount is reserved on his payment card. Depending on the result of this operation, it goes either to the special AUTHORIZED state or, in the case of rejection, to the CANCELED state. This result is reported in the background according to the usual procedure described above.
In order for the money to be actually withdrawn, the e-shop calls the function to confirm the pre-authorization. If the money is to be released (eg it is not possible to meet the conditions of the purchase contract), the e-shop calls the function to cancel the pre-authorization.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 v e-shopu je možné 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é.
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.
Prístup je chránený validáciou IP adresy a integrita odovzdávaných dát je zabezpečená použitím HTTPS protokolu.
Server platobnej brány zodpovedá len v prípade, že je platba zakladaná na pozadí. Všetky parametre sú ‘urlencoded’, rovnako ako v prípade HTTP requestu. Ak je platba založená presmerovaním (parameter ‘prepareOnly’ je ‘false’), potom server platobnej brány rovno presmeruje Platiteľ na príslušnú URL alebo zobrazí chybové hlásenie.
Výber platobnej metódy
Odporúčame v rámci nákupného procesu v e-shope zobraziť platcovi výber platobných metód a na základe jeho výberu založiť platbu s vyplnením parametra ‘method’ na jednu konkrétnu hodnotu (napr. platba kartou alebo platba prevodom z ČS apod). Potom dôjde k priamemu zobrazeniu stránky poskytovateľa konkrétnej platby (banka).
V prípade, že parameter ‘method’ nie je vyplnený jednou konkrétnou hodnotou, dôjde k zobrazeniu ponuky platobných metód na platobnej bráne. Ponuka platobných metód môže byť špecifikovaná jednoduchým výrazom, ktorý sa zadáva do parametra ‘method’. Výraz sa vždy vyhodnocuje na základe metód, ktoré má e-shop povolené.
Povolené oddeľovače identifikátorov metód sú ‘+’ pre pripočítanie metódy a ‘–’ pre odpočítacie metódy z/do výberu.
Príklad:
BANK_ALL + CARD_CZ_CS - BANK_CZ_KB = všetky bankové metódy vrátane platby kartou bez bankového tlačidla Komerční banky.
BANK_CZ_CS_P + BANK_CZ_KB + BANK_CZ_RB = iba bankové tlačidla pri Českej sporiteľni, Komerčnej banke a Reiffeisen Bank (iba tieto 3 na rozdiel od BANK_ALL, ktorý by vybral všetky povolené bankové metódy e-shopu).
Platobná brána umožňuje, aby Platiteľ mal pri výbere platobnej metódy v prostredí brány Comgate predvybranú jednu konkrétnu platobnú metódu. Stačí, aby bol platiteľ presmerovaný na platobnú bránu pomocou získaného platobného odkazu s pridaným parametrom ‘method’ s vybranou metódou.
Platobný odkaz teda môže vyzerať nasledovne:https://payments.comgate.cz/client/instructions/index?id=ABCDEFGHIJ&method=CARD_CZ_CS
Po príchode na bránu bude mať Platiteľ už zapnutú metódu CARD_CZ_CS, výber metódy ale ďalej zostane na ňom. Táto funkcia má zmysel iba pre platby založené s metódou ALL, BANK_ALL alebo s vlastným výberom metódy.
Predautorizácia
Platobná brána umožňuje zadávať, potvrdzovať a rušiť predautorizácie platieb kartou. Založenie platby sa uskutočňuje štandardne, len je potrebné uviesť parameter ‘preauth = true’. Potom platca prejde rovnakým procesom ako v prípade normálnej platby. Potom, čo zadá svoje údaje na platobnej bráne, je na jeho platobnej karte rezervovaná príslušná suma. Podľa výsledku tejto operácie prechádza buď do zvláštneho stavu Authorized, alebo v prípade zamietnutia do stavu CANCELLED. Tento stav je ohlásený na pozadí obvyklým postupom opísaným vyššie.
Aby boli peniaze skutočne strhnuté, vyvolá e-shop funkciu na potvrdenie predautorizácie. Ak sa peniaze majú uvoľniť (napr. nie je možné naplniť podmienky kúpnej zmluvy), vyvolá funkciu na zrušenie predautorizácie.
Body parameter
merchant: "123456"
test: true
country: string
price: "1000"
curr: CZK
label: Product 123
refId: order445566
method: ALL
account: string
email: platce@email.com
name: string
lang: string
prepareOnly: false
secret: gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y
preauth: true
initRecurring: true
verification: true
embedded: true
applePayPayload: string
expirationTime: string
dynamicExpiration: true
Sample OK response
HTTP/2 200 OK
Content-Type: application/x-www-form-urlencoded
code=0&message=OK&transId=AB12-CD34-EF56&redirect=https%3A%2F%2Fpayments.comgate.cz%2Fclient%2Finstructions%2Findex%3Fid%3DAB12-CD34-EF56
Parameters
Name | Type | Required | Description |
---|---|---|---|
merchant | string | true | E-shop identifier in the ComGate system - you can find it in the Client Portal in the section e-shop settings - e-shop connectionidentifikátor e-shopu v systému Comgate - naleznete v Klientském portálu v sekci Nastaveni obchodů - Propojeni obchodu.Identifikátor e-shopu v systéme Comgate - nájdete v Klientskom portáli v sekcii Nastavenie obchodov - Prepojenie obchodu. |
test | boolean | true | A value of ‘true’ means that the payment will be created as a test, a value of ‘false’ means a production version. If the parameter is missing, the payment is created as production.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í.Hodnota ‘true’ znamená, že platba bude založená ako testovacia, hodnota ‘false’ znamená produkčnú verziu. Ak parameter chýba, založí sa platba ako produkčná. |
country | string | false | Possible values: ALL, AT, BE, CY, CZ, DE, EE, EL, ES, FI, FR, GB, HR, HU, IE, IT, LT, LU, LV, MT, NL, NO, PL, PT, RO, SL, SK, SV, US. If the parameter is missing, ‘CZ’ is used automatically. The parameter is used to limit the selection of payment methods at the payment gateway. It is necessary to select the correct combination of ‘country’ and ‘curr’ parameters for the given region. For example, to display Czech buttons and pay by card in CZK, choose the combination country = CZ and curr = CZK. For Slovak bank buttons and card payments in EUR, select country = SK and curr = EUR. For Polish bank buttons and card payment in PLN, select country = PL and curr = PLN. For other foreign currencies, you can use the country = ALL parameter or another country code that the payment gateway accepts.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, SL, SK, SV, 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á. Možné hodnoty: ALL, AT, BE, CY, CZ, DE, EE, EL, ES, FI, FR, GB, HR, HU, IE, IT, LT, LU, LV, MT, NL, NO, PL, PT , RO, SL, SK, SV, US. Ak parameter chýba, použije sa automaticky ‘CZ’. Parameter slúži na obmedzenie výberu platobných metód na platobnej bráne. Je potrebné aby bola zvolená správna kombinácia parametrov ‘country’ a ‘curry’ (mena) pre daný región. Napríklad na zobrazenie českých tlačidiel a platby kartou v mene CZK zvoľte kombináciu country = CZ a curry = CZK. Pri slovenských bankových tlačidlách a platbe kartou v EUR zvoľte country = SK a curry = EUR. Pre poľské bankové tlačidlá a platbu kartou v PLN zvoľte country = PL a curry = PLN. Pre ostatné cudzie meny môžete použiť parameter country = ALL alebo ďalší kód krajiny, ktorý platobná brána prijíma. |
price | integer(int32) | true | Price for a product in cents or pennies. Must be in minimum of 1 CZK; 0,1 EUR; 1 PLN; 100 HUF; 1 USD; 1 GBP; 5 RON; 1 HRK; 0,5 NOK; 0,5 SEK. Maximum is not limited.Cena za produkt v centech nebo haléřích. Neplatí pro měnu HUF, kde může být uvedena pouze celá částka. 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. neomezeno.Cena za výrobok v centoch alebo halieroch. Musí byť min. 1 CZK; 0,1 EUR; 1 PLN; 100 HUF; 1 USD; 1 GBP; 5 RON; 0,5 NOK; 0,5 SEK. Max. neobmedzené. |
curr | string | true | Currency code according to ISO 4217. Available currencies: CZK, EUR, PLN, HUF, USD, GBP, RON, HRK, NOK, SEK.Kód měny dle ISO 4217. K dispozici jsou měny: CZK, EUR, PLN, HUF, USD, GBP, RON, NOK, SEK.Kód meny podľa ISO 4217. K dispozícii sú meny: EUR, CZK, PLN, HUF, USD, GBP, RON, NOK, SEK. |
label | string | true | Short description of the product (1-16 characters) - this item enable to filter payments in the Client Portal.Krátký popis produktu (1-16 znaků) – dle této položky je možné filtrovat platby v Klientském portálu.Krátky opis produktu (1-16 znakov) - podľa tejto položky je možné filtrovať platby v Klientskom portáli. |
refId | string | true | Parameter suitable for entering a variable symbol or order number on the Client’s side (it does not have to be unique, ie it is possible to create more payments with the same refId). In the Client Portal and daily csv. the parameter is marked as Client ID.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.Parameter vhodný na zadanie variabilného symbolu alebo čísla objednávky na strane Klienta (nemusí byť unikátne, tzn., že možno založiť viac platieb s rovnakým refid). V Klientskom portáli a denným csv. je parameter označený ako ID Klienta. |
method | string | true | Selected payment methods: ALL, BANK_ALL-BANK_CZ_KB, CARD_ALL, APPLEPAY_REDIRECT, GOOGLEPAY_REDIRECT, BANK_CZ_FB+BANK_CZ_UC, …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).Metóda platby z tabuľky platobných metód, hodnota ‘ALL’ v prípade, že si má metódu vybrať platiteľa alebo jednoduchý výraz s výberom metód (opísané nižšie). |
account | string | false | Identifier of the Client’s bank account to which ComGate Payments will transfer money. If you do not fill in the parameter, the default Client account will be used. You can find a list of the Client’s accounts at https://portal.comgate.cz/.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/.Identifikátor bankového účtu Klienta, na ktorý Comgate Payments prevedie peniaze. Ak parameter nevyplníte, použije sa predvolený účet Klienta. Zoznam účtov Klienta nájdete na https://portal.comgate.cz/. |
string | true | Contact email on the Payer (for the purposes of a possible complaint)Kontaktní email na Plátce (pro účely případné reklamace)Kontaktný e-mail na Platiteľa (na účely prípadnej reklamácie) | |
name | string | false | Product identifier - this item is located in the client’s daily csv under the name Product.Identifikátor produktu – tato položka se nachází v denním csv. Klienta pod názvem Produkt.Identifikátor produktu - táto položka sa nachádza v dennom csv. Klienta pod názvom Produkt. |
lang | string | false | Language code (ISO 639-1) in which the Payer will be shown instructions for completing the payment, default allowed values (‘cs’, ‘sk’, ‘en’, ‘pl’, ‘fr’, ‘ro’, ‘de’ , ‘hu’, ‘si’, ‘hr’), if the parameter is missing, ‘cs’ will be used, in case of request for another language, contact platby-podpora@comgate.cz.Kód jazyka (ISO 639-1), ve kterém budou Plátci zobrazeny instrukce pro dokončení platby, standardně povolené hodnoty (‘cs’, ‘sk’, ‘en’, ‘es’, ‘it’, ‘pl’, ‘fr’, ‘ro’, ‘de’, ‘hu’, ‘si’, ‘hr’, ‘no’, ‘sv’), pokud parametr chybí, použije se ‘cs’, v případě požadavku na další jazyk, kontaktujte podpora@comgate.cz.Kód jazyka (ISO 639-1), v ktorom budú Platiteľovi zobrazené inštrukcie na dokončenie platby, štandardne povolené hodnoty (‘sk’, ‘sk’, ‘en’, ‘es’, ‘it’ ‘pl’, ‘fr’, ‘ro’, ‘de’, ‘hu’, ‘si’, ‘hr’), ak parameter chýba, použije sa ‘cs’ v prípade požiadavky na ďalší jazyk, kontaktujte podpora@comgate.cz. |
prepareOnly | boolean | true | In the case of creating payment in the background fill in ‘true’. When creating a payment by redirection, fill in either ‘false’ or do not use the parameter. You can find which payment method is setted up as allowed in the Client Portal in the Integration section - connection of e-shop.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.V prípade zakladania platby na pozadí vyplňte ‘true’. Pri zakladaní platby presmerovaním vyplňte buď ‘false’ alebo parameter nepoužívajte. Aký povolený spôsob založenia platby máte nastavený, zistíte v Klientskom portáli v sekcii Integrácia - Prepojenie obchodu. |
secret | string | true | If you create a background payment, fill in the password for background communication. When creating a payment by redirection, leave the parameter blank or do not use it.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.V prípade zakladania platby na pozadí vyplňte heslo pre komunikáciu na pozadí. Pri zakladaní platby presmerovaním parameter ponechajte prázdny alebo ho nepoužívajte. |
preauth | boolean | false | In the case of a request to pre-authorize credit card payments set to ‘true’. In the case of a normal payment, fill in ‘false’ or do not use the parameter. Only for card payments.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.V prípade požiadavky na predautorizáciu platby kartou nastavte na ‘true’. V prípade normálnej platby vyplňte ‘false’ alebo parameter nepoužívajte. Len na platby kartou. |
initRecurring | boolean | false | Parameter for creating an initial transaction for recurring payments. Only for Clients who have the service enabled.Příznak pro založení iniciační transakce pro opakované platby. Pouze pro Klienty, kteří mají službu povolenou.Príznak pre založenie iniciačnej transakcie pre opakované platby. Len pre Klientov, ktorí majú službu povolenú. |
verification | boolean | false | Verification payment parameter, in case of a request to create a verification payment (value ‘true’) it is not necessary to send the initRecurring parameter.Parametr ověřovací platby, v případě požadavku na založení ověřovací platby (hodnota ‘true’) není nutné posílat parametr ‘initRecurring’.Parameter overovacej platby, v prípade požiadavky na založenie overovacej platby (hodnota ‘true’) nie je nutné posielať parameter ‘initRecurring’. |
embedded | boolean | false | If you use the standard redirection of the payer to the payment gateway, do not fill in the parameter or enter the value ‘false’. The parameter is used only if you have implemented the display of the ComGate payment gateway in the iframe in your e-shop. A value of ‘true’ ensures that the gateway is displayed correctly in the iframe. This can only be used for card payments. You can find more detailed information in the Payment Gateway section in the e-shop (iframe)Pokud používáte standardní přesměrování plátce na platební bránu, parametr nevyplňujte nebo zadejte hodnotu ‘false’. Parametr se používá pouze v případě, že máte ve vašem e-shopu implementováno zobrazení platební brány Comgate v iframe. Hodnota ‘true’ zajistí korektní zobrazení brány v iframe. Toto lze použít pouze pro platby kartou. Podrobnější informace najdete v sekci zde.Ak používate štandardné presmerovanie platiteľa na platobnú bránu, parameter nevyplňujte alebo zadajte hodnotu ‘false’. Parameter sa používa len v prípade, že máte vo vašom e-shope implementované zobrazenie platobnej brány Comgate v iframe. Hodnota ‘true’ zaistí korektné zobrazenie brány v iframe. Toto možno použiť len na platby kartou. |
applePayPayload | string | false | If you want to set up an ApplePay payment and process it directly, you must fill in this parameter together with method=APPLEPAY_ESHOP.Zakódovovaná data platby do base64.Zakódovovaná data platby do base64. |
expirationTime | string | false | If you want to change the expiration date of an individual payment, you can do so by entering this parameter. The allowed value is between 30 minutes and 7 days. The default value is according to the settings in the Client Portal. The value is in the format: ^[1-9][0-9]*(m|h|d)$. For example,: 30m, 3h, 250m, 1d, 5d.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.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 | false | Enable or disable dynamic expiration. The default state is according to the settings in the Client Portal.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.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. |
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | Creates a new paymentVytvoří novou platbuVytvorí novú platbu | Inline |
Response Schema
Status Code 200
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
code | integer | true | none | Method return code and error (value of message) description: 0 - OK 1100 - unknown error 1102 - specified language is not supported 1103 - method incorrectly specified 1104 - unable to load payment 1107 - payment price not supported 1200 - database error 1301 - unknown e-shop 1303 - missing link or language 1304 - invalid category 1305 - product description missing 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 Návratový kód metódy a opis chyby: 0 OK 1100 neznáma chyba 1102 zadaný jazyk nie je podporovaný 1103 nesprávne zadaná metóda 1104 nemožno načítať platbu 1107 cena platby nie je podporovaná 1200 databázová chyba 1301 neznámy e-shop 1303 prepojenie alebo jazyk chýba 1304 neplatná kategória 1305 chýba opis produktu 1306 vyberte správnu metódu 1308 vybraný spôsob platby nie je povolený 1309 nesprávna čiastka 1310 neznáma mena 1311 neplatný identifikátor bankového účtu Klienta 1316 e-shop nemá povolené opakované platby 1317 neplatná metóda - nepodporuje opakované platby 1319 nemožno založiť platbu, problém na strane banky 1399 neočakávaný výsledok z databázy 1400 chybná otázka 1500 neočakávaná chyba |
message | string | true | none | none |
transId | string | false | none | Unique alphanumeric identifier (code) of the transaction, which will be displayed to the Payer at various stages of payment.Unikátní alfanumerický identifikátor (kód) transakce, který bude zobrazen Plátci v různých fázích platby.Unikátny alfanumerický identifikátor (kód) transakcie, ktorý bude zobrazený Platiteľmi v rôznych fázach platby. |
redirect | string | false | none | URL of the page where the Payer is to be redirected to make the payment.URL stránky, kam má být Plátce přesměrován pro realizaci platby.URL stránka, kam má byť Platiteľ presmerovaný na realizáciu platby. |
cancel
Code samples
# 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'
<?php
require 'vendor/autoload.php';
$headers = array(
'Content-Type' => 'application/x-www-form-urlencoded',
'Accept' => 'application/x-www-form-urlencoded',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_params = [
"merchant" => "123456",
"transId" => "AB12-CD34-EF56",
"secret" => "gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y",
];
try {
$response = $client->request('POST','https://payments.comgate.cz/v1.0/cancel', array(
'headers' => $headers,
'form_data' => $request_params,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
String params = "&merchant=123456&transId=AB12-CD34-EF56&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y";
byte[] postData = params.getBytes();
URL obj = new URL("https://payments.comgate.cz/v1.0/cancel");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setDoOutput(true);
con.setRequestMethod("POST");
con.setRequestProperty("Content-Type", "application/x-www-form-urlencoded");
con.setRequestProperty("Content-Length", Integer.toString(postData.length));
OutputStream os = con.getOutputStream();
os.write(postData);
os.flush();
os.close();
BufferedReader in = new BufferedReader(new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
import requests
headers = {
'Content-Type': 'application/x-www-form-urlencoded',
'Accept': 'application/x-www-form-urlencoded'
}
r = requests.post('https://payments.comgate.cz/v1.0/cancel', params={
"merchant": "123456",
"transId": "AB12-CD34-EF56",
"secret": "gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y",
}, headers = headers)
print(r.text)
POST /v1.0/cancel
Storno of payment
If the order in the e-shop has been canceled and the transaction is not to be completed by the payer, it is possible to use the storno of payment. Unlike a refund, the payment must be in the pending state.
Due to the speed of payment, the payment may already be paid, in which case an error will be displayed and the refund method must be used.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.Storno platby
V prípade, že bola objednávka v e-shope stornovaná a transakcia nemá byť platcom dokončená, je možné využiť storno platby. Na rozdiel od refundácie musí byť platba v stave očakávaná (pending).
Vzhľadom na rýchlosť zaplatenia platieb môže byť platba už v stave zaplatená, v takom prípade sa zobrazí chyba a je nutné využiť metódu refundácie.
Body parameter
merchant: "123456"
transId: AB12-CD34-EF56
secret: gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y
Sample OK response
HTTP/2 200 OK
Content-Type: application/x-www-form-urlencoded
code=0&message=OK
Parameters
Name | Type | Required | Description |
---|---|---|---|
merchant | string | true | e-shop identifier in the ComGate systemidentifikátor e-shopu v systému Comgateidentifikátor e-shopu v systéme Comgate |
transId | string | true | unique alphanumeric identifier (code) of the transaction (transactionId)unikátní alfanumerický identifikátor (kód) transakce (transactionId)unikátny alfanumerický identifikátor (kód) transakcie (transactionId) |
secret | string | true | password for background communicationheslo pro komunikaci na pozadíheslo pre komunikáciu na pozadí |
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | Cancellation statusStav zrušeníStav zrušenia | Inline |
Response Schema
Status Code 200
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
code | integer | true | none | method return code and error description: 0 OK 1400 the payment cannot be changed to CANCELLED status (payment not found, payment is not in PENDING status, unauthorized access)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)návratový kód metódy a opis chyby: 0 OK 1400 nie je možné prepnúť platbu do cancel stavu (platba nenájdená, platba nie je v stave pending, neoprávnený prístup) |
message | string | true | none | none |
recurring
Code samples
# You can also use wget
curl -X POST https://payments.comgate.cz/v1.0/recurring \
--data "&merchant=123456&price=10000&curr=CZK&label=string&refId=2010102600&email=platce@email.com&prepareOnly=true&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y&initRecurringId=AB12-CD34-EF56" \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Accept: application/x-www-form-urlencoded'
<?php
require 'vendor/autoload.php';
$headers = array(
'Content-Type' => 'application/x-www-form-urlencoded',
'Accept' => 'application/x-www-form-urlencoded',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_params = [
"merchant" => "123456",
"price" => "10000",
"curr" => "CZK",
"label" => "string",
"refId" => "2010102600",
"email" => "platce@email.com",
"prepareOnly" => "true",
"secret" => "gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y",
"initRecurringId" => "AB12-CD34-EF56",
];
try {
$response = $client->request('POST','https://payments.comgate.cz/v1.0/recurring', array(
'headers' => $headers,
'form_data' => $request_params,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
String params = "&merchant=123456&price=10000&curr=CZK&label=string&refId=2010102600&email=platce@email.com&prepareOnly=true&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y&initRecurringId=AB12-CD34-EF56";
byte[] postData = params.getBytes();
URL obj = new URL("https://payments.comgate.cz/v1.0/recurring");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setDoOutput(true);
con.setRequestMethod("POST");
con.setRequestProperty("Content-Type", "application/x-www-form-urlencoded");
con.setRequestProperty("Content-Length", Integer.toString(postData.length));
OutputStream os = con.getOutputStream();
os.write(postData);
os.flush();
os.close();
BufferedReader in = new BufferedReader(new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
import requests
headers = {
'Content-Type': 'application/x-www-form-urlencoded',
'Accept': 'application/x-www-form-urlencoded'
}
r = requests.post('https://payments.comgate.cz/v1.0/recurring', params={
"merchant": "123456",
"price": "10000",
"curr": "CZK",
"label": "string",
"refId": "2010102600",
"email": "platce@email.com",
"prepareOnly": "true",
"secret": "gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y",
"initRecurringId": "AB12-CD34-EF56",
}, headers = headers)
print(r.text)
POST /v1.0/recurring
Recurring payments, remembering card details
The payment gateway allows you to enter recurring payments, that is, one-click payments. The first (initial) payment takes place through a standard process with redirection to the payment gateway, subsequent payments already take place completely in the background. The system thus allows the payer to pay within a few seconds without having to fill in information about the payment card.
This functionality is available on request. In the case of recurring payments at the beginning, we create an initial payment, which is created as a regular payment, only the request contains an additional parameter initRecurring - method create. Subsequent recurring payments are already created using the recurring method and are linked to the Comgate ID of the initiating transaction. This ID must be tied to a specific Payer in the Client’s system.
After creating a recurring payment, the Payer is not redirected to the payment gateway, because the whole process takes place in the background, the Client is only given the status of the payment, and he then displays this status to the Payer.
Subsequent recurring payments
Creating a second and subsequent recurring payment to the payment gateway is only possible in the case of accepting cards for e-shops that have the service enabled.The first (initial) payment is made in the standard way (see Creating a payment). The process of creating a second and each subsequent payment takes place completely in the background, these payments are tied to the initiator via the Comgate ID of the initiation payment. This ID must be in the request in the initRecurringId parameter. The payer is shown the payment status in the e-shop system as a result.
All parameters are urlencoded, as in the case of an HTTP request to create a standard payment. The answer contains the code parameter, according to which the e-shop determines what result the payer will display. Code = 0 means success, the payment was created, any other code means an error and therefore no payment was created.
Recurring payments
Recurring payments with a predefined amount and period (eg monthly, weekly, etc.) can be made using the Recurring Payments service, which is described in the previous paragraphsOpakované 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, 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.Opakované platby, zapamätanie kartových údajov
Platobná brána umožňuje zadávanie opakovaných platieb, t.j. platieb na jedno kliknutie. Prvá (iniciačná) platba sa uskutočňuje štandardným procesom s presmerovaním na platobnú bránu, nasledujúce platby sa už uskutočňujú kompletne na pozadí. Systém tak umožňuje platcovi zaplatiť v priebehu niekoľkých sekúnd bez nutnosti vypĺňať informácie o platobnej karte.
Táto funkcia je dostupná na vyžiadanie. V prípade opakovaných platieb na začiatku zakladáme iniciačnú platbu, ktorá sa zakladá ako bežná platba, len sa v požiadavke nachádza navyše parameter ‘initRecurring’ - metóda create. Následné opakované platby sú už zakladané metódou recurring a sú viazané na Comgate ID iniciačnej transakcie. Toto ID musí byť v systéme Klienta viazané na konkrétneho Platiteľa.
Po založení opakovanej platby nedochádza k presmerovaniu platcu na platobnú bránu, pretože celý proces sa uskutočňuje na pozadí, Klientovi je len odovzdaný stav založenia platby a ten následne zobrazí tento stav platcovi.
Nasledujúce opakované platby
Založenie druhej a nasledujúcej opakované platby do platobnej brány je možné len pri akceptácii kariet pre e-shopy, ktoré majú službu povolenú. Prvá (iniciačná) platba sa uskutočňuje štandardnou cestou (pozri Založenie platby). Proces založenia druhej a každej ďalšej platby sa uskutočňuje kompletne na pozadí, tieto platby sú viazané na iniciačné cez Comgate ID iniciačné platby. Toto ID sa musí nachádzať v požiadavke v parametri ‘initRecurringId’. Platiteľovi je v systéme e-shopu ako výsledok zobrazený stav platby.
Všetky parametre sú urlencoded, rovnako ako v prípade HTTP requestu na založenie štandardnej platby. V odpovedi sa nachádza parameter ‘code’, podľa ktorého e-shop určí, aký výsledok zobrazí platcovi. Code = 0 znamená úspech, platba bola založená, akýkoľvek iný kód znamená chybu a teda nezaloženie platby.
Rekurentné platby (recurring)
Rekurentné platby, tzn. opakované platby s vopred zadefinovanou sumou a periódou (napr. mesačné, týždenné apod.) je možné realizovať pomocou služby Opakované platby, ktorá je opísaná v predchádzajúcich odsekoch.
Body parameter
merchant: "123456"
country: string
test: true
price: "10000"
curr: CZK
label: string
refId: "2010102600"
account: string
email: platce@email.com
name: string
prepareOnly: true
secret: gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y
initRecurringId: AB12-CD34-EF56
Sample OK response
HTTP/2 200 OK
Content-Type: application/x-www-form-urlencoded
code=0&message=OK
Parameters
Name | Type | Required | Description |
---|---|---|---|
merchant | string | true | e-shop identifier in the Comgate systemidentifikátor e-shopu v systému Comgateidentifikátor e-shopu v systéme Comgate |
country | string | false | country code (‘CZ’, ‘SK’, ‘PL’, ‘ALL’), if the parameter is missing, ‘CZ’ is usedkód země (‘CZ’, ‘SK’, ‘PL’, ‘ALL’), pokud parametr chybí, použije se ‘CZ’kód krajiny (‘CZ’, ‘SK’, ‘PL’, ‘ALL’), ak parameter chýba, použije sa ‘CZ’ |
test | boolean | false | A value of ‘true’ means that the payment will be created as a test, a value of ‘false’ means a production version. If the parameter is missing, the payment is created as production.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í.Hodnota ‘true’ znamená, že platba bude založená ako testovacia, hodnota ‘false’ znamená, že platba bude založená ako produkčná verzia. Ak parameter chýba, založí sa platba ako produkčná. |
price | string | true | Price of the product in cents or pennies. Must be min. 10 CZK (incl.), Max. unlimited.Cena za produkt v centech nebo haléřích. Musí být min. 10 CZK (včetně), max. neomezeno.Cena za výrobok v centoch alebo halieroch. Musí byť min. 10 CZK (vrátane), max. neobmedzene. |
curr | string | true | Currency code according to ISO 4217, standard ‘CZK’.kód měny dle ISO 4217, standardně ‘CZK’kód meny podľa ISO 4217, štandardne ‘CZK’ |
label | string | true | short product description (1-16 characters)krátký popis produktu (1-16 znaků)krátky opis produktu (1 – 16 znakov) |
refId | string | true | Payment reference in the e-shop system (it does not have to be unique, i.e. it is possible to create multiple payments with the same refId).Reference platby v systému e-shopu (nemusí být unikátní, tzn., že lze založit více plateb se stejným refId).Referencia platby v systéme e-shopu (nemusí byť unikátna, tzn., že možno založiť viac platieb s rovnakým refid). |
account | string | false | The identifier of the e-shop bank account to which Comgate will transfer the money. If you do not complete the parameter, the default e-shop account will be used. You can find a list of e-shop accounts at https://portal.comgate.cz/.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/.Identifikátor bankového účtu e-shopu, na ktorý Comgate prevedie peniaze. Ak parameter nevyplníte, použije sa predvolený účet e-shopu. Zoznam účtov e-shopu nájdete na https://portal.comgate.cz/ |
string | true | payer’s contact e-mail (for the purposes of possible complaints)kontaktní email na Plátce (pro účely případné reklamace)kontaktný email na Platiteľa (na účely prípadnej reklamácie) | |
name | string | false | Product identifier - this item allows you to navigate to the payment statistics of the Comgate payment system.Identifikátor produktu - dle této položky je potom možné se zorientovat ve statistikách plateb Comgate platebního systému.Identifikátor produktu - podľa tejto položky je potom možné sa zorientovať v štatistikách platieb Comgate platobného systému. |
prepareOnly | string | true | The parameter must be set to ‘true’. Recurring payments cannot be created by redirection.Parametr musí nabývat hodnoty „true“. Opakované platby nelze zakládat přesměrováním.Parameter musí nadobúdať hodnoty „true“. Opakované platby nemožno zakladať presmerovaním. |
secret | string | true | password for background communicationheslo pro komunikaci na pozadíheslo pre komunikáciu na pozadí |
initRecurringId | string | true | Comgate ID of the initial paymentComgate ID iniciační platbyComgate ID iniciačnej platby |
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | Status | Inline |
Response Schema
Status Code 200
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
code | integer | true | none | method return code and error description: 0 OK 1100 unknown error 1102 specified language is not supported 1103 method incorrectly specified 1104 unable to load payment 1200 database error 1301 unknown e-shop 1303 missing link or language 1304 invalid category 1305 product description missing 1308 selected payment method is not allowed 1309 incorrect amount 1310 unknown currency 1311 invalid e-shop bank account identifier 1316 e-shop does not allow recurring payments 1317 invalid method - does not support recurring payments 1318 initial payment not found 1319 can not create a payment, problem with the bank 1399 unexpected result from database 1400 wrong query 1500 unexpected errorná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á chybaNávratový kód metódy a opis chyby: 0 OK 1100 neznáma chyba 1102 zadaný jazyk nie je podporovaný 1103 nesprávne zadaná metóda 1104 nemožno načítať platbu 1200 databázová chyba 1301 neznámy e-shop 1303 prepojenie alebo jazyk chýba 1304 neplatná kategória 1305 chýba opis produktu 1308 vybraný spôsob platby nie je povolený 1309 nesprávna čiastka 1310 neznáma mena 1311 neplatný identifikátor bankového účtu e-shopu 1316 e-shop nemá povolené opakované platby 1317 neplatná metóda - nepodporuje opakované platby 1318 iniciačná platba nebola nájdená 1319 nemožno založiť platbu, problém na strane banky 1399 neočakávaný výsledok z databázy 1400 chybná otázka 1500 neočakávaná chyba |
message | string | true | none | none |
transId | string | false | none | a unique alphanumeric transaction identifier (code) that will be displayed to the payer at various stages of paymentunikátní alfanumerický identifikátor (kód) transakce, který bude zobrazen Plátci v různých fázích platbyunikátny alfanumerický identifikátor (kód) transakcie, ktorý bude zobrazený Platiteľmi v rôznych fázach platby |
refund
Code samples
# 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" \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Accept: application/x-www-form-urlencoded'
<?php
require 'vendor/autoload.php';
$headers = array(
'Content-Type' => 'application/x-www-form-urlencoded',
'Accept' => 'application/x-www-form-urlencoded',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_params = [
"merchant" => "123456",
"transId" => "AB12-CD34-EF56",
"secret" => "gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y",
"amount" => "10000",
];
try {
$response = $client->request('POST','https://payments.comgate.cz/v1.0/refund', array(
'headers' => $headers,
'form_data' => $request_params,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
String params = "&merchant=123456&transId=AB12-CD34-EF56&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y&amount=10000";
byte[] postData = params.getBytes();
URL obj = new URL("https://payments.comgate.cz/v1.0/refund");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setDoOutput(true);
con.setRequestMethod("POST");
con.setRequestProperty("Content-Type", "application/x-www-form-urlencoded");
con.setRequestProperty("Content-Length", Integer.toString(postData.length));
OutputStream os = con.getOutputStream();
os.write(postData);
os.flush();
os.close();
BufferedReader in = new BufferedReader(new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
import requests
headers = {
'Content-Type': 'application/x-www-form-urlencoded',
'Accept': 'application/x-www-form-urlencoded'
}
r = requests.post('https://payments.comgate.cz/v1.0/refund', params={
"merchant": "123456",
"transId": "AB12-CD34-EF56",
"secret": "gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y",
"amount": "10000",
}, headers = headers)
print(r.text)
POST /v1.0/refund
Payment refund
The refund method is intended for payments already created and paid. Payment status must be paid. It is possible to make both a partial (refunded amount is lower than the payment amount) and a full refund (the refund amount is equal to the payment amount). The amount will be transferred back to the payer’s account.
If the payment has not been completed and is in a pending state, it is possible to use the payment storno method.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.Refundácia platby
Metóda pre refundáciu je určená pre už založené a preplatené platby. Stav platby musí byť zaplatená (paid). Je možné vykonať ako čiastočnú (refundovaná suma je nižšia ako suma platby), tak plnú refundáciu (suma refundácie je rovnaká ako suma platby). Daná čiastka bude prevedená späť na účet platiteľa.
Ak platba nebola dokončená a je v stave pending, je možné využiť metódu storno platby.
Body parameter
merchant: "123456"
transId: AB12-CD34-EF56
secret: gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y
amount: "10000"
curr: CZK
test: true
refId: string
Sample OK response
HTTP/2 200 OK
Content-Type: application/x-www-form-urlencoded
code=0&message=OK
Parameters
Name | Type | Required | Description |
---|---|---|---|
merchant | string | true | e-shop identifier in the Comgate systemidentifikátor e-shopu v systému Comgateidentifikátor e-shopu v systéme Comgate |
transId | string | true | unique alphanumeric transaction identifier (code) (transactionId)unikátní alfanumerický identifikátor (kód) transakce (transactionId)unikátny alfanumerický identifikátor (kód) transakcie (transactionId) |
secret | string | true | password for background communicationheslo pro komunikaci na pozadíheslo pre komunikáciu na pozadí |
amount | string | true | refund amount - can be the full or partial amount of the transactiončástka refundace – může být v plné nebo částečné výši transakcečiastka refundácie - môže byť v plnej alebo čiastočnej výške transakcie |
curr | string | false | refund currency, if not filled in, ‘CZK’ will be usedměna refundace, pokud není vyplněno, použije se ‘CZK’mena refundácie, ak nie je vyplnená, použije sa ‘CZK’ |
test | string | false | A value of ‘true’ means that the refund will be created as a test. Refunds and payments will be verified in the standard manner, only the original payment will not be refunded. If ‘false’ is completed or the parameter is empty, an official refund is created. Test transactions can only be refunded by a test refund.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í.Hodnota ‘true’ znamená, že refundácia bude založená ako testovacia. Refundácia a platba bude preverená štandardnou cestou, len nedôjde k refundácii pôvodnej platby. Ak je vyplnené ‘false’ alebo je parameter prázdny, je založená ostrá refundácia. Testovacie transakcie môžu byť refundované iba testovacími refundáciami. |
refId | string | false | parameter suitable for entering the refund identification number on the customer’s side (it does not have to be unique, i.e. it is possible to create multiple refunds with the same refId); in the Client Portal under refund section and the daily csv for the refund, the parameter is marked as the Client ID. If this parameter is not attached to the refund, the original refId of the created payment will be displayed for the payment.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.Parameter vhodný na zadanie identifikačného čísla refundácie na strane Klienta (nemusí byť unikátna, tzn., že možno založiť viac refundácií s rovnakým refid); v Klientskom portáli v sekcii refundácií a denných csv pri refundácii je parameter označený ako ID Klienta. V prípade, že tento parameter na refundáciu nie je pripojený, k platbe sa zobrazí pôvodná refid založenej platby. |
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | Status | Inline |
Response Schema
Status Code 200
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
code | integer | true | none | method return code and error description: 0 OK 1100 unknown error 1200 database error 1400 wrong query 1401 refunded payment is in CANCELLED status 1402 refund amount higher than allowed 1500 unexpected errornávratový kód metódy a opis chyby: 0 OK 1100 neznáma chyba 1200 databázová chyba 1400 chybná otázka 1401 refundovaná platba je v stave CANCELLED 1402 čiastka prevyšuje povolenú výšku 1500 neočakávaná chybanávratový kód metódy a opis chyby: 0 OK 1100 neznáma chyba 1200 databázová chyba 1400 chybná otázka 1401 refundovaná platba je v stave CANCELLED 1402 čiastka prevyšuje povolenú výšku 1500 neočakávaná chyba |
message | string | true | none | none |
capturePreauth
Code samples
# 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'
<?php
require 'vendor/autoload.php';
$headers = array(
'Content-Type' => 'application/x-www-form-urlencoded',
'Accept' => 'application/x-www-form-urlencoded',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_params = [
"merchant" => "123456",
"transId" => "AB12-CD34-EF56",
"secret" => "gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y",
];
try {
$response = $client->request('POST','https://payments.comgate.cz/v1.0/capturePreauth', array(
'headers' => $headers,
'form_data' => $request_params,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
String params = "&merchant=123456&transId=AB12-CD34-EF56&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y";
byte[] postData = params.getBytes();
URL obj = new URL("https://payments.comgate.cz/v1.0/capturePreauth");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setDoOutput(true);
con.setRequestMethod("POST");
con.setRequestProperty("Content-Type", "application/x-www-form-urlencoded");
con.setRequestProperty("Content-Length", Integer.toString(postData.length));
OutputStream os = con.getOutputStream();
os.write(postData);
os.flush();
os.close();
BufferedReader in = new BufferedReader(new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
import requests
headers = {
'Content-Type': 'application/x-www-form-urlencoded',
'Accept': 'application/x-www-form-urlencoded'
}
r = requests.post('https://payments.comgate.cz/v1.0/capturePreauth', params={
"merchant": "123456",
"transId": "AB12-CD34-EF56",
"secret": "gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y",
}, headers = headers)
print(r.text)
POST /v1.0/capturePreauth
If the e-shop has created a payment with a request to pre-authorize the card payment (using the parameter preauth = true), calling this function will request the debiting of the money that was blocked through pre-authorization. It is possible to perform both the partial debiting of the transaction (the pre-authorized amount is lower than the payment amount) and full debiting (the debited amount is equal to the payment amount). Calls can only be used for payments for which AUTHORIZED status has been reported.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.V prípade, že e-shop založil platbu s požiadavkou na predautorizáciu platby kartou (s využitím parametra ‘preauth = true’), vyvolaním tejto funkcie vyžiada strhnutie peňazí, ktoré boli v rámci predautorizácie zablokované. Je možné vykonať ako čiastočné strhnutie transakcie (predautorizovaná suma je nižšia ako suma platby), tak plné strhnutie (suma strhnutia je rovnaká ako suma platby). Volanie možno použiť len na platby, pri ktorých bol ohlásený stav Authorized.
Body parameter
merchant: "123456"
transId: AB12-CD34-EF56
secret: gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y
amount: string
Sample OK response
HTTP/2 200 OK
Content-Type: application/x-www-form-urlencoded
code=0&message=OK
Parameters
Name | Type | Required | Description |
---|---|---|---|
merchant | string | true | e-shop identifier in the ComGate systemidentifikátor e-shopu v systému Comgateidentifikátor e-shopu v systéme Comgate |
transId | string | true | unique alphanumeric identifier (code) of the transaction (transactionId)unikátní alfanumerický identifikátor (kód) transakce (transactionId)unikátny alfanumerický identifikátor (kód) transakcie (transactionId) |
secret | string | true | password for background communicationheslo pro komunikaci na pozadíheslo pre komunikáciu na pozadí |
amount | string | false | the amount of pre-authorization to be debitd from the card - it can be in the full or partial amount of the transactiončástka předautorizace, která má být z karty stržena - může být v plné nebo částečné výši transakcečiastka predautorizácie, ktorá má byť z karty strhnutá - môže byť v plnej alebo čiastočnej výške transakcie |
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | Pre-auth statusPředautorizační stavPredautorizačný stav | Inline |
Response Schema
Status Code 200
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
code | integer | true | none | method return code and error description: 0 OK 1100 unknown error 1104 unable to load payment 1200database error 1301 unknown e-shop 1303 missing link or language 1399 unexpected result from database 1400 wrong query 1500 unexpected errorná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á chybanávratový kód metódy a opis chyby: 0 OK 1100 neznáma chyba 1104 nemožno načítať platbu 1200 databázová chyba 1301 neznámy e-shop 1303 prepojenie alebo jazyk chýba 1399 neočakávaný výsledok z databázy 1400 chybná otázka 1500 neočakávaná chyba |
message | string | true | none | none |
cancelPreauth
Code samples
# 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'
<?php
require 'vendor/autoload.php';
$headers = array(
'Content-Type' => 'application/x-www-form-urlencoded',
'Accept' => 'application/x-www-form-urlencoded',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_params = [
"merchant" => "123456",
"transId" => "AB12-CD34-EF56",
"secret" => "gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y",
];
try {
$response = $client->request('POST','https://payments.comgate.cz/v1.0/cancelPreauth', array(
'headers' => $headers,
'form_data' => $request_params,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
String params = "&merchant=123456&transId=AB12-CD34-EF56&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y";
byte[] postData = params.getBytes();
URL obj = new URL("https://payments.comgate.cz/v1.0/cancelPreauth");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setDoOutput(true);
con.setRequestMethod("POST");
con.setRequestProperty("Content-Type", "application/x-www-form-urlencoded");
con.setRequestProperty("Content-Length", Integer.toString(postData.length));
OutputStream os = con.getOutputStream();
os.write(postData);
os.flush();
os.close();
BufferedReader in = new BufferedReader(new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
import requests
headers = {
'Content-Type': 'application/x-www-form-urlencoded',
'Accept': 'application/x-www-form-urlencoded'
}
r = requests.post('https://payments.comgate.cz/v1.0/cancelPreauth', params={
"merchant": "123456",
"transId": "AB12-CD34-EF56",
"secret": "gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y",
}, headers = headers)
print(r.text)
POST /v1.0/cancelPreauth
If the e-shop has created a payment with a request to pre-authorize the card payment (using the parameter preauth = true), by calling this function the e-shop indicates that it does not want to collect the money that was blocked during pre-authorization and the money can be released to the card again. Calls can only be used for payments for which AUTHORIZED status has been reported.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.V prípade, že e-shop založil platbu s požiadavkou na predautorizáciu platby kartou (s využitím parametra ‘preauth = true’), vyvolaním tejto funkcie dáva najavo, že peniaze, ktoré boli v rámci predautorizácie zablokované, nechce inkasovať a peniaze sa na karte môžu opäť uvoľniť. Volanie možno použiť len na platby, pri ktorých bol ohlásený stav Authorized.
Body parameter
merchant: "123456"
transId: AB12-CD34-EF56
secret: gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y
Sample OK response
HTTP/2 200 OK
Content-Type: application/x-www-form-urlencoded
code=0&message=OK
Parameters
Name | Type | Required | Description |
---|---|---|---|
merchant | string | true | e-shop identifier in the ComGate systemidentifikátor e-shopu v systému Comgateidentifikátor e-shopu v systéme Comgate |
transId | string | true | unique alphanumeric identifier (code) of the transaction (transactionId)unikátní alfanumerický identifikátor (kód) transakce (transactionId)unikátny alfanumerický identifikátor (kód) transakcie (transactionId) |
secret | string | true | password for background communicationheslo pro komunikaci na pozadíheslo pre komunikáciu na pozadí |
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | Pre-auth cancellation statusStav před zrušením autorizaceStav pred zrušením autorizácie | Inline |
Response Schema
Status Code 200
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
code | integer | true | none | method return code and error description: 0 OK 1100 unknow error 1104unable to load payment 1200 database error 1301 unknown e-shop 1303 missing link or language 1399 unexpected result from database 1400 wrong query 1500 unexpected errorná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á chybanávratový kód metódy a opis chyby: 0 OK 1100 neznáma chyba 1104 nemožno načítať platbu 1200 databázová chyba 1301 neznámy e-shop 1303 prepojenie alebo jazyk chýba 1399 neočakávaný výsledok z databázy 1400 chybná otázka 1500 neočakávaná chyba |
message | string | true | none | none |
methods
Code samples
# You can also use wget
curl -X POST https://payments.comgate.cz/v1.0/methods \
--data "&merchant=123456&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y" \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Accept: application/json'
<?php
require 'vendor/autoload.php';
$headers = array(
'Content-Type' => 'application/x-www-form-urlencoded',
'Accept' => 'application/json',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_params = [
"merchant" => "123456",
"secret" => "gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y",
];
try {
$response = $client->request('POST','https://payments.comgate.cz/v1.0/methods', array(
'headers' => $headers,
'form_data' => $request_params,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
String params = "&merchant=123456&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y";
byte[] postData = params.getBytes();
URL obj = new URL("https://payments.comgate.cz/v1.0/methods");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setDoOutput(true);
con.setRequestMethod("POST");
con.setRequestProperty("Content-Type", "application/x-www-form-urlencoded");
con.setRequestProperty("Content-Length", Integer.toString(postData.length));
OutputStream os = con.getOutputStream();
os.write(postData);
os.flush();
os.close();
BufferedReader in = new BufferedReader(new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
import requests
headers = {
'Content-Type': 'application/x-www-form-urlencoded',
'Accept': 'application/json'
}
r = requests.post('https://payments.comgate.cz/v1.0/methods', params={
"merchant": "123456",
"secret": "gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y",
}, headers = headers)
print(r.text)
POST /v1.0/methods
Obtaining allowed methods
Method for obtaining the settings that the e-shop has enabled in the Comgate Payments Payment System. This method can be used to obtain a list of available payment methods for making payments.
The response contains XML or JSON, depending on the selected parameter. Both formats have the same level of immersion.Získání povolený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.
V odpovědi se nachází XML nebo JSON, podle zvoleného parametru. Oba formáty mají stejnou úroveň zanoření.Získanie povolených metód
Metóda na získanie nastavenia, ktoré má e-shop povolené v Comgate Payments Platobnom Systéme. Touto metódou možno získať zoznam dostupných platobných metód na realizáciu platieb.
V odpovedi sa nachádza XML alebo JSON, podľa zvoleného parametra. Obidva formáty majú rovnakú úroveň zanorenia.
Body parameter
merchant: "123456"
secret: gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y
type: json
lang: string
curr: string
country: string
Sample OK response
HTTP/2 200 OK
Content-Type: application/json
{"methods":[{"id":"BANK_CZ_CS_P","name":"Česká spořitelna - PLATBA 24","description":"On-line platba pro majitele účtu u České spořitelny.","logo":"https://payments.comgate.cz/assets/images/logos/BANK_CZ_CS_P.png"}]}
Parameters
Name | Type | Required | Description |
---|---|---|---|
merchant | string | true | e-shop identifier in the ComGate systemidentifikátor e-shopu v systému Comgateidentifikátor e-shopu v systéme Comgate |
secret | string | true | password for background communicationheslo pro komunikaci na pozadíheslo pre komunikáciu na pozadí |
type | string | false | Format of returned data (‘xml’ or ‘json’). If not filled in, ‘xml’ will be used.Formát vrácených dat (‘xml’ nebo ‘json’). Pokud nebude vyplněno, použije se ‘xml’.Formát vrátených dát (‘xml’ alebo ‘json’). Pokiaľ nebude vyplnené, použije sa ‘xml’. |
lang | string | false | Select the language in which the method descriptions will be. Allowed values are ‘cs’, ‘en’, ‘pl’. If not filled in, ‘cs’ will be used.Výběr, v jakém jazyce budou popisy metod. Povolené hodnoty jsou ‘cs’, ‘en’, ‘pl’. Pokud nebude vyplněno, použije se ‘cs’.Výber, v akom jazyku budú opisy metód. Povolené hodnoty sú ‘cs’, ‘en’, ‘pl’. Pokiaľ nebude vyplnené, použije sa ‘cs’. |
curr | string | false | Filling in the parameter to the values CZK or EUR will return methods that support the specified currency.Vyplněním parametru na hodnoty CZK nebo EUR dojde k vrácení metod, které podporují zadanou měnu.Vyplnením parametra na hodnoty CZK alebo EUR dôjde k vráteniu metód, ktoré podporujú zadanú menu. |
country | string | false | Country code (‘CZ’, ‘SK’), the parameter is used to limit the selection of payment methods for the specified country.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’, ‘SV’, ‘US’), parametr slouží k omezení výběru platebních metod pro zadanou zemi.Kód krajiny (‘CZ’, ‘SK’), parameter slúži na obmedzenie výberu možných spôsobov pre zadanú krajinu. |
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | HTTP 200, List of payment methodsHTTP 200, Seznam platebních metodHTTP 200, Zoznam platobných metód | Inline |
400 | Bad Request | HTTP 200, Error occuredHTTP 200, došlo k chyběHTTP 200, vyskytla sa chyba | Inline |
Response Schema
Status Code 200
structure of the returned JSONstruktura vráceného JSONštruktúra vráteného JSON
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
methods | [object] | true | none | Available methodsDostupné metodyDostupné metódy |
» id | string | false | none | available payment methoddostupná metoda platbydostupná metóda platby |
» name | string | false | none | name of the method in the selected languagenázev metody, ve zvoleném jazycenázev metody, ve zvoleném jazycenázov metódy, vo zvolenom jazyku |
» description | string | false | none | name of the method in the selected languagedelší popis metody, ve zvoleném jazycedlhší opis metódy, vo zvolenom jazyku |
» logo | string | false | none | HTTP link to method logoHTTP link na logo metodyHTTP link na logo metódy |
Status Code 400
returns HTTP 200 (OK)!!
structure of the returned JSONvrátí HTTP 200 (OK)!!
struktura vráceného JSONuvráti HTTP 200 (OK)!!
štruktúra vráteného JSON
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
error | [object] | true | none | ErrorChybaChyba |
» code | string | false | none | none |
» message | string | false | none | method return code and error description: 0 OK 1100 unknown error 1200 database error 1400 wrong query 1500 unexpected errorná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á chybanávratový kód metódy a opis chyby: 0 OK 1100 neznáma chyba 1200 databázová chyba 1300 e-shop nemá žiadnu metódu 1400 chybná otázka 1500 neočakávaná chyba |
» extraMessage | string | false | none | specification of the error messageupřesnění chybového hlášeníupresnenie chybového hlásenia |
status
Code samples
# 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'
<?php
require 'vendor/autoload.php';
$headers = array(
'Content-Type' => 'application/x-www-form-urlencoded',
'Accept' => 'application/x-www-form-urlencoded',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_params = [
"merchant" => "123456",
"transId" => "AB12-CD34-EF56",
"secret" => "gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y",
];
try {
$response = $client->request('POST','https://payments.comgate.cz/v1.0/status', array(
'headers' => $headers,
'form_data' => $request_params,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
String params = "&merchant=123456&transId=AB12-CD34-EF56&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y";
byte[] postData = params.getBytes();
URL obj = new URL("https://payments.comgate.cz/v1.0/status");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setDoOutput(true);
con.setRequestMethod("POST");
con.setRequestProperty("Content-Type", "application/x-www-form-urlencoded");
con.setRequestProperty("Content-Length", Integer.toString(postData.length));
OutputStream os = con.getOutputStream();
os.write(postData);
os.flush();
os.close();
BufferedReader in = new BufferedReader(new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
import requests
headers = {
'Content-Type': 'application/x-www-form-urlencoded',
'Accept': 'application/x-www-form-urlencoded'
}
r = requests.post('https://payments.comgate.cz/v1.0/status', params={
"merchant": "123456",
"transId": "AB12-CD34-EF56",
"secret": "gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y",
}, headers = headers)
print(r.text)
POST /v1.0/status
Getting payment status in the background
Analogous function for transmitting the result of payment in the background, only initiated by the Store. However, it does not replace the transfer of the status of the payment in the background, its implementation is still mandatory.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á.Získanie stavu platby na pozadí
Analogická funkcia pre odovzdanie výsledku platby na pozadí, iba iniciovaná Obchodom. Nenahrádza však odovzdanie stavu platby na pozadí, jej implementácia je stále povinná.
Body parameter
merchant: "123456"
transId: AB12-CD34-EF56
secret: gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y
Sample OK response
HTTP/2 200 OK
Content-Type: application/x-www-form-urlencoded
code=0&message=OK&merchant=123456&price=10000&curr=CZK&label=Beatles%20-%20Help&refId=2010102600&method=ALL&email=platce%40email.com&transId=AB12-CD34-EF56&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y&status=PAID
Parameters
Name | Type | Required | Description |
---|---|---|---|
merchant | string | true | e-shop identifier in the ComGate systemidentifikátor e-shopu v systému Comgateidentifikátor e-shopu v systéme Comgate |
transId | string | true | unique alphanumeric identifier (code) of the transaction (transactionId)unikátní alfanumerický identifikátor (kód) transakce (transactionId)unikátny alfanumerický identifikátor (kód) transakcie (transactionId) |
secret | string | true | password for background communicationheslo pro komunikaci na pozadíheslo pre komunikáciu na pozadí |
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | Obtained payment statusZískaný stav platbyZískaný stav platby | Inline |
Response Schema
Status Code 200
Payment statusStav platbyStav platby
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
code | string | true | none | Method return codeNávratový kód metodyNávratový kód metódy |
message | string | true | none | method return code and error description: 0 OK 1100 unknown error 1200 database error 1400 wrong query 1500 unexpected error in the case of code = 0, the following parameters are in the responsepopis 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:návratový kód metódy a opis chyby: 0 OK 1100 neznáma chyba 1200 databázová chyba 1400 chybná otázka 1500 neočakávaná chyba v prípade code = 0 sú v odpovedi nasledujúce parametre: |
merchant | string | true | none | e-shop identifier in the Comgate systemidentifikátor e-shopu v systému Comgateidentifikátor e-shopu v systéme Comgate |
test | string | true | none | A value of ‘true’ means that the payment was created as a test, a value of ‘false’ means a production version.Hodnota ‘true’ znamená, že platba byla založena jako testovací, hodnota ‘false’ znamená produkční verzi.Hodnota ‘true’ znamená, že platba bola založená ako testovacia, hodnota ‘false’ znamená produkčnú verziu. |
price | string | true | none | price of the product in cents or penniescena za produkt v centech nebo haléříchcena za výrobok v centoch alebo halieroch |
curr | string | true | none | currency code according to ISO 4217kód měny dle ISO 4217kód meny podľa ISO 4217 |
label | string | true | none | short product description (1-16 characters)krátký popis produktu (1-16 znaků)krátky opis produktu (1 – 16 znakov) |
refId | string | true | none | payment references in the e-shop systemreference platby v systému e-shopureferencia platby v systéme e-shopu |
payerId | string | false | none | payer identifier in the e-shop systemidentifikátor Plátce v systému e-shopuidentifikátor Platiteľa v systéme e-shopu |
method | string | false | none | payment method used, from the table of payment methodspoužitá metoda platby, z tabulky platebních metodpoužitá metóda platby, z tabuľky platobných metód |
account | string | false | none | identifier of the e-shop bank account to which Comgate Payments will transfer the moneyidentifikátor bankovního účtu e-shopu, na který Comgate Payments převede penízeidentifikátor bankového účtu e-shopu, na ktorý Comgate Payments prevedie peniaze |
string | true | none | payer’s contact e-mailkontaktní email na Plátcekontaktný email na Platiteľa | |
name | string | false | none | product identifier - this item allows you to navigate to the payment statistics of the Comgate payment system identifikátor produktu - dle této položky je potom možné se zorientovat ve statistikách plateb Comgate platebního systému.Identifikátor produktu - podľa tejto položky je potom možné sa zorientovať v štatistikách platieb Comgate platobného systému. |
transId | string | true | none | unique alphanumeric transaction identifier (code) (transactionId)unikátní alfanumerický identifikátor (kód) transakce (transactionId)unikátny alfanumerický identifikátor (kód) transakcie (transactionId) |
secret | string | true | none | password for background communicationheslo pro komunikaci na pozadíheslo pre komunikáciu na pozadí |
status | string | true | none | current transaction status, values ‘PENDING’ - the payment is created, the final result is not known ‘PAID’ - payment was successfully paid ‘CANCELLED’ - the payment was not completed correctly and is cancelled ‘AUTHORIZED’ - the requested pre-authorization was successfulaktuá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ěaktuálny stav transakcie, hodnoty PENDING - platba je založená, finálny výsledok nie je známy PAID - platba bola úspešne zaplatená CANCELLED - platba nebola dokončená korektne a je zrušená Authorized - vyžiadaná predautorizácia prebehla úspešne |
payerName | string | false | none | transmission of the name of the account belonging to the payerpředání jména účtu patřící Plátciodovzdanie mena účtu patriacemu Platiteľovi |
payerAcc | string | false | none | transmission of the payer’s account numberpředání čísla účtu Plátceodovzdanie čísla účtu Platiteľa |
fee | string | false | none | if the e-shop has set up automatic deduction of the payment fee, the transaction fee will be calculated in this field, otherwise, the field will take the value ‘unknown’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’ak má e-shop nastavené automatické strhávanie poplatku za platbu, bude v tomto poli spočítaný poplatok za transakciu, inak bude pole nadobúdať hodnotu ‘unknown’ |
TAG_api_for_downloading_files
transferList
Code samples
# 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/json'
<?php
require 'vendor/autoload.php';
$headers = array(
'Content-Type' => 'application/x-www-form-urlencoded',
'Accept' => 'application/json',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_params = [
"merchant" => "123456",
"secret" => "gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y",
"date" => "2023-03-22",
];
try {
$response = $client->request('POST','https://payments.comgate.cz/v1.0/transferList', array(
'headers' => $headers,
'form_data' => $request_params,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
String params = "&merchant=123456&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y&date=2023-03-22";
byte[] postData = params.getBytes();
URL obj = new URL("https://payments.comgate.cz/v1.0/transferList");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setDoOutput(true);
con.setRequestMethod("POST");
con.setRequestProperty("Content-Type", "application/x-www-form-urlencoded");
con.setRequestProperty("Content-Length", Integer.toString(postData.length));
OutputStream os = con.getOutputStream();
os.write(postData);
os.flush();
os.close();
BufferedReader in = new BufferedReader(new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
import requests
headers = {
'Content-Type': 'application/x-www-form-urlencoded',
'Accept': 'application/json'
}
r = requests.post('https://payments.comgate.cz/v1.0/transferList', params={
"merchant": "123456",
"secret": "gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y",
"date": "2023-03-22",
}, headers = headers)
print(r.text)
POST /v1.0/transferList
The transferList method is used to obtain information about which transfers were made within a given day.Metoda transferList slouží k získání informace, jaké převody byly uskutečněny v rámci daného dne.Metóda transferList slúži na získanie informácie, aké prevody boli uskutočnené v rámci daného dňa.
Body parameter
merchant: "123456"
secret: gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y
date: 2023-03-22
test: false
Sample OK response
HTTP/2 200 OK
Content-Type: application/json
[{"transferId":1234567,"transferDate":"2023-01-25","accountCounterparty":"0/0000","accountOutgoing":"123456789/0000","variableSymbol":"12345678"}]
Parameters
Name | Type | Required | Description |
---|---|---|---|
merchant | string | true | e-shop identifier in the Comgate systemidentifikátor e-shopu v systému Comgateidentifikátor e-shopu v systéme Comgate |
secret | string | true | password for background communicationheslo pro komunikaci na pozadíheslo pre komunikáciu na pozadí |
date | string | true | indicate the transfer dateuveďte datum uskutečnění převoduuveďte dátum uskutočnenia prevodu |
test | boolean | false | if the value is ‘true’, the method returns predefined sample transferpokud vyplníte true, metoda vrátí předem definovaný vzorový převodak vyplníte true, metóda vráti vopred definovaný vzorový prevod |
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | Successful operationÚspěšná operaceÚspešná operácia | Inline |
Response Schema
Status Code 200
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
transferId | integer | false | none | none |
transferDate | string(date) | false | none | none |
accountCounterparty | string | false | none | none |
accountOutgoing | string | false | none | none |
variableSymbol | string | false | none | none |
singleTransfer
Code samples
# 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/json'
<?php
require 'vendor/autoload.php';
$headers = array(
'Content-Type' => 'application/x-www-form-urlencoded',
'Accept' => 'application/json',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_params = [
"merchant" => "123456",
"secret" => "gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y",
"transferId" => "1234567",
];
try {
$response = $client->request('POST','https://payments.comgate.cz/v1.0/singleTransfer', array(
'headers' => $headers,
'form_data' => $request_params,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
String params = "&merchant=123456&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y&transferId=1234567";
byte[] postData = params.getBytes();
URL obj = new URL("https://payments.comgate.cz/v1.0/singleTransfer");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setDoOutput(true);
con.setRequestMethod("POST");
con.setRequestProperty("Content-Type", "application/x-www-form-urlencoded");
con.setRequestProperty("Content-Length", Integer.toString(postData.length));
OutputStream os = con.getOutputStream();
os.write(postData);
os.flush();
os.close();
BufferedReader in = new BufferedReader(new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
import requests
headers = {
'Content-Type': 'application/x-www-form-urlencoded',
'Accept': 'application/json'
}
r = requests.post('https://payments.comgate.cz/v1.0/singleTransfer', params={
"merchant": "123456",
"secret": "gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y",
"transferId": "1234567",
}, headers = headers)
print(r.text)
POST /v1.0/singleTransfer
The singleTransfer method displays detailed information for a specific bank transfer.
The mandatory transferId parameter merchant obtained by using ttransferList method.Metoda singleTransfer zobrazuje detailní informace ke konkrétnímu bankovnímu převodu.
Povinný parametr ‘transferId’ získá obchodník pomocí metody transferList.Metóda singleTransfer zobrazuje detailné informácie ku konkrétnemu bankovému prevodu. Povinný parameter ‘transferId’ získa obchodník pomocou metódy transferList.
Body parameter
merchant: "123456"
secret: gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y
transferId: "1234567"
test: false
Sample OK response
HTTP/2 200 OK
Content-Type: application/json
[{"transferId":1234567,"transferDate":"2023-01-25","accountCounterparty":"0/0000","accountOutgoing":"123456789/0000","variableSymbol":"12345678"}]
Parameters
Name | Type | Required | Description |
---|---|---|---|
merchant | string | true | e-shop identifier in the Comgate systemidentifikátor e-shopu v systému Comgateidentifikátor e-shopu v systéme Comgate |
secret | string | true | password for background communicationheslo pro komunikaci na pozadíheslo pre komunikáciu na pozadí |
transferId | string | true | mandatory parameter obtained using the transferList methoduveďte převody, které byly uskutečněny v rámci daného dne. Seznam získáte pomocí Metoda transferList.uveďte prevody, ktoré boli uskutočnené v rámci daného dňa. Zoznam získate pomocou metódy transferList. |
test | boolean | false | suitable for testing - returns details to predefined sample transfersvhodné pro testování - Pokud je honota true, vrátí se detaily k předem definovaným vzorovým převodůmvhodné na testovanie - Ak je hodnota true, vrátia sa detaily k vopred definovaným vzorovým prevodom |
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | Successful operationÚspěšná operaceÚspešná operácia | Inline |
Response Schema
Status Code 200
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
transferId | integer | false | none | none |
transferDate | string(date) | false | none | none |
accountCounterparty | string | false | none | none |
accountOutgoing | string | false | none | none |
variableSymbol | string | false | none | none |
csvSingleTransfer
Code samples
# You can also use wget
curl -X POST https://payments.comgate.cz/v1.0/csvSingleTransfer \
--data "&merchant=123456&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y&transferId=5217530" \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Accept: application/json'
<?php
require 'vendor/autoload.php';
$headers = array(
'Content-Type' => 'application/x-www-form-urlencoded',
'Accept' => 'application/json',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_params = [
"merchant" => "123456",
"secret" => "gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y",
"transferId" => "5217530",
];
try {
$response = $client->request('POST','https://payments.comgate.cz/v1.0/csvSingleTransfer', array(
'headers' => $headers,
'form_data' => $request_params,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
String params = "&merchant=123456&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y&transferId=5217530";
byte[] postData = params.getBytes();
URL obj = new URL("https://payments.comgate.cz/v1.0/csvSingleTransfer");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setDoOutput(true);
con.setRequestMethod("POST");
con.setRequestProperty("Content-Type", "application/x-www-form-urlencoded");
con.setRequestProperty("Content-Length", Integer.toString(postData.length));
OutputStream os = con.getOutputStream();
os.write(postData);
os.flush();
os.close();
BufferedReader in = new BufferedReader(new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
import requests
headers = {
'Content-Type': 'application/x-www-form-urlencoded',
'Accept': 'application/json'
}
r = requests.post('https://payments.comgate.cz/v1.0/csvSingleTransfer', params={
"merchant": "123456",
"secret": "gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y",
"transferId": "5217530",
}, headers = headers)
print(r.text)
POST /v1.0/csvSingleTransfer
Thanks to the csvSingleTransfer method, you can download the daily statement in CSV format for a specific bank transfer.Díky metodě csvSingleTransfer si lze stáhnout denní výpis ve formátu CSV.Vďaka metóde csvSingleTransfer si možno stiahnuť denný výpis vo formáte CSV.
Body parameter
merchant: "123456"
secret: gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y
transferId: "5217530"
download: "false"
test: false
Sample OK response
HTTP/2 200 OK
Content-Type: application/json
{"nazev":"vypis-YYYY-MM-DD.csv","csv":"base64 encoded csv"}
Parameters
Name | Type | Required | Description |
---|---|---|---|
merchant | string | true | e-shop identifier in the Comgate systemidentifikátor e-shopu v systému Comgateidentifikátor e-shopu v systéme Comgate |
secret | string | true | password for background communicationheslo pro komunikaci na pozadíheslo pre komunikáciu na pozadí |
transferId | string | true | details for a specific bank transferuveďte převody, které byly uskutečněny v rámci daného dne. Seznam získáte pomocí Metoda transferList.Uveďte prevody, ktoré boli uskutočnené v rámci daného dňa. Zoznam získate pomocou metódy transferList. |
download | string | false | If not filled in or false, it returns data: file name and its contents; if true, it returns the CSV file directly.Pokud není vyplněno, nebo je false, tak vrací data : název souboru a jeho obsah; pokud je true, tak vrací rovnou CSV soubor.Ak nie je vyplnené alebo je false, tak vracia dáta: názov súboru a jeho obsah; ak je true, tak vracia rovno CSV súbor. |
test | boolean | false | returns a sample CSV file for testing purposesPokud je hodnota true, vrátí ukázkový CSV soubor.Ak je hodnota true, vráti ukážkový CSV súbor. |
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | Successful operationÚspěšná operaceÚspešná operácia | Inline |
Response Schema
Status Code 200
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
nazev | string | false | none | File name for the downloaded CSV fileNázev staženého souboru CSVNázov stiahnutého súboru CSV |
csv | string | false | none | Base64-encoded CSV fileSoubor CSV s kódováním Base64Súbor CSV s kódovaním Base64 |
aboSingleTransfer
Code samples
# You can also use wget
curl -X POST https://payments.comgate.cz/v1.0/aboSingleTransfer \
--data "&merchant=123456&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y&transferId=transfer_id" \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Accept: application/json'
<?php
require 'vendor/autoload.php';
$headers = array(
'Content-Type' => 'application/x-www-form-urlencoded',
'Accept' => 'application/json',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_params = [
"merchant" => "123456",
"secret" => "gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y",
"transferId" => "transfer_id",
];
try {
$response = $client->request('POST','https://payments.comgate.cz/v1.0/aboSingleTransfer', array(
'headers' => $headers,
'form_data' => $request_params,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
String params = "&merchant=123456&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y&transferId=transfer_id";
byte[] postData = params.getBytes();
URL obj = new URL("https://payments.comgate.cz/v1.0/aboSingleTransfer");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setDoOutput(true);
con.setRequestMethod("POST");
con.setRequestProperty("Content-Type", "application/x-www-form-urlencoded");
con.setRequestProperty("Content-Length", Integer.toString(postData.length));
OutputStream os = con.getOutputStream();
os.write(postData);
os.flush();
os.close();
BufferedReader in = new BufferedReader(new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
import requests
headers = {
'Content-Type': 'application/x-www-form-urlencoded',
'Accept': 'application/json'
}
r = requests.post('https://payments.comgate.cz/v1.0/aboSingleTransfer', params={
"merchant": "123456",
"secret": "gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y",
"transferId": "transfer_id",
}, headers = headers)
print(r.text)
POST /v1.0/aboSingleTransfer
Thanks to the aboSingleTransfer method, you can download a daily statement in ABO format.Díky metodě aboSingleTransfer si lze stáhnout denní výpis ve formátu ABO.Vďaka metóde aboSingleTransfer si možno stiahnuť denný výpis vo formáte ABO.
Body parameter
merchant: "123456"
secret: gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y
transferId: transfer_id
download: "true"
type: v1
encoding: false
test: false
Sample OK response
HTTP/2 200 OK
Content-Type: application/json
{"nazev":"vypis-YYYY-MM-DD.gpc","abo":"base64_encoded_abo_file"}
Parameters
Name | Type | Required | Description |
---|---|---|---|
merchant | string | true | e-shop identifier in the Comgate systemidentifikátor e-shopu v systému Comgateidentifikátor e-shopu v systéme Comgate |
secret | string | true | password for background communicationheslo pro komunikaci na pozadíheslo pre komunikáciu na pozadí |
transferId | string | true | details for a specific bank transferuveďte převody, které byly uskutečněny v rámci daného dne. Seznam získáte pomocí Metoda transferList.uveďte prevody, ktoré boli uskutočnené v rámci daného dňa. Zoznam získate pomocou metódy transferList. |
download | string | false | If not filled in or false, it returns data: file name and its contents; if true, it returns the ABO file directly.Pokud není vyplněno, nebo je false, tak vrací data : název souboru a jeho obsah; pokud je true, tak vrací rovnou ABO soubor.Ak nie je vyplnené alebo je false, tak vracia dáta: názov súboru a jeho obsah; ak je true, tak vracia rovno ABO súbor. |
type | string | false | the ‘type’ parameter can take the values ‘v1’ and ‘v2’. Under ‘v1’ you get the ABO version with the fees listed separately for each payment, under ‘v2’ you get the ABO with the total fee in one line. If the parameter is not filled in, you will automatically receive the 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’. Parameter ‘type’ môže nadobúdať hodnoty ‘v1’ a ‘‘v2’. Pod ‘v1’’ získate ABO verziu s poplatkami uvedenými zvlášť ku každej platbe, pod ‘v2’ potom ABO so súhrnným poplatkom v jednom riadku. Pokiaľ nebude parameter vyplnený, automaticky obdržíte typ ‘v1’. |
encoding | string | false | The character encoding can be utf8 or win1250. If the value is not filled in, the parameter value defaults to 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.Kódovanie znakov môže byť utf8 alebo win1250. Ak hodnota nie je vyplnená, predvolená hodnota parametra je utf8. |
test | boolean | false | Returns a sample ABO file for testing purposes.Pokud je hodnota true, vrátí ukázkový ABO soubor.Ak je hodnota true, vráti ukážkový ABO súbor. |
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | Successful operationÚspěšná operaceÚspešná operácia | Inline |
Response Schema
Status Code 200
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
nazev | string | false | none | file namenázev souborunázov súboru |
abo | string | false | none | base64 encoded abo/gpc filesoubor abo/gpc v kódování base64base64 kódovaný súbor abo/gpc |
csvDownload
Code samples
# 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/zip'
<?php
require 'vendor/autoload.php';
$headers = array(
'Content-Type' => 'application/x-www-form-urlencoded',
'Accept' => 'application/zip',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_params = [
"merchant" => "123456",
"secret" => "gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y",
"date" => "YYYY-MM-DD",
];
try {
$response = $client->request('POST','https://payments.comgate.cz/v1.0/csvDownload', array(
'headers' => $headers,
'form_data' => $request_params,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
String params = "&merchant=123456&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y&date=YYYY-MM-DD";
byte[] postData = params.getBytes();
URL obj = new URL("https://payments.comgate.cz/v1.0/csvDownload");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setDoOutput(true);
con.setRequestMethod("POST");
con.setRequestProperty("Content-Type", "application/x-www-form-urlencoded");
con.setRequestProperty("Content-Length", Integer.toString(postData.length));
OutputStream os = con.getOutputStream();
os.write(postData);
os.flush();
os.close();
BufferedReader in = new BufferedReader(new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
import requests
headers = {
'Content-Type': 'application/x-www-form-urlencoded',
'Accept': 'application/zip'
}
r = requests.post('https://payments.comgate.cz/v1.0/csvDownload', params={
"merchant": "123456",
"secret": "gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y",
"date": "YYYY-MM-DD",
}, headers = headers)
print(r.text)
POST /v1.0/csvDownload
Direct download of CSV files for a specific day using the csvDowload method. The downloaded ZIP file will contain one or more CSV files if there are multiple transactions within a day. It can be used, for example, for calls using wget.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.Priame preberanie CSV súborov pre konkrétny deň metódou csvDowload. Stiahnutý súbor vo formáte ZIP bude obsahovať jeden alebo viac súborov CSV, ak je viac prevodov v rámci dňa. Možno využiť napr. na volanie pomocou wget.
Body parameter
merchant: "123456"
secret: gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y
date: YYYY-MM-DD
test: false
Sample OK response
HTTP/2 200 OK
Content-Type: application/zip
ZIP file containing a CSV of all transfers made on the date specified in the request
Parameters
Name | Type | Required | Description |
---|---|---|---|
merchant | string | true | e-shop identifier in the Comgate systemidentifikátor e-shopu v systému Comgateidentifikátor e-shopu v systéme Comgate |
secret | string | true | password for background communicationheslo pro komunikaci na pozadíheslo pre komunikáciu na pozadí |
date | string | true | mandatory for one day onlypovinný pouze za jeden denpovinný len za jeden deň |
test | boolean | false | For testing purposes, it returns a sample CSV file in ZIP format.Pokud je hodnota true, vrátí ukázkový CSV soubor ve formátu ZIP.Ak je hodnota true, vráti ukážkový CSV súbor vo formáte ZIP. |
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | Successful operationÚspěšná operaceÚspešná operácia | string |
aboDownload
Code samples
# 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/zip'
<?php
require 'vendor/autoload.php';
$headers = array(
'Content-Type' => 'application/x-www-form-urlencoded',
'Accept' => 'application/zip',
);
$client = new \GuzzleHttp\Client();
// Define array of request body.
$request_params = [
"merchant" => "123456",
"secret" => "gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y",
"date" => "YYYY-MM-DD",
];
try {
$response = $client->request('POST','https://payments.comgate.cz/v1.0/aboDownload', array(
'headers' => $headers,
'form_data' => $request_params,
)
);
print_r($response->getBody()->getContents());
}
catch (\GuzzleHttp\Exception\BadResponseException $e) {
// handle exception or api errors.
print_r($e->getMessage());
}
// ...
String params = "&merchant=123456&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y&date=YYYY-MM-DD";
byte[] postData = params.getBytes();
URL obj = new URL("https://payments.comgate.cz/v1.0/aboDownload");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setDoOutput(true);
con.setRequestMethod("POST");
con.setRequestProperty("Content-Type", "application/x-www-form-urlencoded");
con.setRequestProperty("Content-Length", Integer.toString(postData.length));
OutputStream os = con.getOutputStream();
os.write(postData);
os.flush();
os.close();
BufferedReader in = new BufferedReader(new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
import requests
headers = {
'Content-Type': 'application/x-www-form-urlencoded',
'Accept': 'application/zip'
}
r = requests.post('https://payments.comgate.cz/v1.0/aboDownload', params={
"merchant": "123456",
"secret": "gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y",
"date": "YYYY-MM-DD",
}, headers = headers)
print(r.text)
POST /v1.0/aboDownload
Direct download of ABO files for a specific day using the aboDowload method. The downloaded ZIP file will contain one or more ABO files.It can be used, for example, for calls using wget.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.Priame preberanie ABO súborov pre konkrétny deň metódou aboDowload. Stiahnutý súbor vo formáte ZIP bude obsahovať jeden alebo viac súborov ABO.
Možno využiť napr. na volanie pomocou wget.
Body parameter
merchant: "123456"
secret: gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y
date: YYYY-MM-DD
type: string
encoding: string
test: false
Sample OK response
HTTP/2 200 OK
Content-Type: application/zip
ZIP file contaning ABO for all transfers made on the date specified in the request
Parameters
Name | Type | Required | Description |
---|---|---|---|
merchant | string | true | e-shop identifier in the Comgate systemidentifikátor e-shopu v systému Comgateidentifikátor e-shopu v systéme Comgate |
secret | string | true | password for background communicationheslo pro komunikaci na pozadíheslo pre komunikáciu na pozadí |
date | string | true | mandatory for one day onlypovinný pouze za jeden denpovinný len za jeden deň |
type | string | false | the ‘type’ parameter can take the values ‘v1’ and ‘v2’. Under ‘v1’ you get the ABO version with the fees listed separately for each payment, under ‘v2’ you get the ABO with the total fee in one line. If the parameter is not filled in, you will automatically receive the 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 poplatek souhrným v jednom řádku. Pokud nebude parametr vyplněn, automaticky obdržíte typ ‘v1’.Parameter ‘type’ môže nadobúdať hodnoty ‘v1’ a ‘‘v2’. Pod ‘v1’’ získate ABO verziu s poplatkami uvedenými zvlášť ku každej platbe, pod ‘v2’ potom ABO so súhrnným poplatkom v jednom riadku. Pokiaľ nebude parameter vyplnený, automaticky obdržíte typ ‘v1’. |
encoding | string | false | The character encoding can be utf8 or win1250. If the value is not filled in, the parameter value defaults to 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.Kódovanie znakov môže byť utf8 alebo win1250. Ak hodnota nie je vyplnená, predvolená hodnota parametra je utf8. |
test | boolean | false | For testing purposes, it returns a sample CSV file in ZIP format.Pokud je hodnota true, vrátí ukázkový CSV soubor ve formátu ZIP.Ak je hodnota true, vráti ukážkový CSV súbor vo formáte ZIP. |
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | Successful operationÚspěšná operaceÚspešná operácia | string |