MENU Navigation

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
email string A kontaktní email na Plátce
phone string N kontaktní telefon na Plátce
name string N identifikátor produktu – dle této položky je možné vyhledávat ve statistikách plateb Comgate platebního systému.
transId string A unikátní alfanumerický identifikátor (kód) transakce (transactionId)
secret string A heslo pro komunikaci na pozadí
status string A aktuální stav transakce, hodnoty
„PAID“ – platba byla úspěšně zaplacena
„CANCELLED“ – platba nebyla dokončena korektně a je zrušena
„AUTHORIZED” – vyžádaná předautorizace proběhla úspěšně
fee string N Pokud má e-shop nastavené automatické strhávání poplatku za platbu, bude v tomto poli spočítaný poplatek za transakci, jinak bude pole nabývat hodnoty „unknown“.

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ří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

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.

HTML kód

<div id="comgate-container">
<!-- Atribut allow=payment je pro zobrazení brány v iframe nezbytný -->
<iframe id='comgate-iframe' allow="payment" 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";

// bude odstraněno z DOM - již nepůjde zobrazit znovu pomocí comgateOpen
// let comgate_iframe = document.getElementById("comgate-iframe");
// comgate_iframe.remove();
}

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”:

<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í (pouze v čase do 1 hodiny od založení) k jeho automatickému přesměrování do e-shopu na URL, která byla nastavena v klientském portálu (do 5 minut od založení platby je vyřízeno více než 97 % plateb).

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.

1. Přesměrování vnější stránky na vámi určenou URL

Tímto dojde k obnovení celé stránky a zákazník neuvázne v iframu otevřeném na stránce. Dnes se již ale nejedná o doporučovaný způsob.

Javascriptový kód pro vnitřní stránku

window.top.location = window.self.location

2. Zaslání vlastní zprávy z iframu na svou vnější stránku

Poté co zákazníka přesměrujeme do eshopu, je v iframe duplicitně zobrazena stránka vášeho e-shopu. Z této stránky uvnitř iframu si můžete poslat jednoduchou javascriptovou zprávu své vnější stránce a v té ji zpracovat. Nemusí tedy dojít k obnovení celé stránky.

UPOZORNĚNÍ

Skutečný výsledek platby, který nedorazil pomocí push notifikace je vždy třeba ověřit standardním způsobem na našem API. Z bezpečnostních důvodů nelze spoléhat na výsledek předaný zprávou z iframe nebo v URL při přesměrování (informace může být snadno podvržena).

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:

// ID platby získáte z URL adresy, na kterou je zákazník přesměrován po dokončení platby
// výchozí parametry URL: id=${id}&refId=${refId} (lze si přidat vlastní parametr s pevnou hodnotou očekávaného stavu)
// více informací viz propojení obchodu v klientském portálu
window.parent.postMessage({ id: 'id-platby', status: 'PAID' /* refId, ... */ }, '*');

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) {
// validace, že message obsahuje data
if (!e || !(e !== null && e !== void 0 && e.data)) return;
const { id, status /* refId, ... */ } = e.data;
if (['PAID', 'AUTHORIZED'].includes(status)) {
// obsloužení stavu PAID / AUTHORIZED
console.log(id)
} else {
// obsloužení dalších stavů, atd ...
}
}, false);
}

3. Poslouchání zpráv zasílaných přímo bránou Comgate

Po dokončení platby zákazníkem (PAID, AUTHORIZED, CANCELLED) se platební brána pokusí předat informaci o stavu platby na server obchodníka (push). Následně, bezprostředně před tím, než zákazníka přesměruje zpět do e-shopu, odešle rodiči iframu (vašemu e-shopu) javascriptovou zprávu o stavu platby.

UPOZORNĚNÍ

Není garantováno, že je tato javascriptová zpráva odeslána až poté, co dojde k úspěšnému předání stavu platby na pozadí (push). Typicky může k předčasnému odeslání této zprávy docházet po uplynutí 1 hodiny od založení platby.

Poté co vaše stránka přijme zprávu od naší brány v iframe, měl by být iframe skryt. Pokud si nepřejete, aby docházelo k duplicitnímu načtení vaší stránky přímo v iframe, je potřeba iframe ze stránky (DOMu) odebrat (k tomu není možné použít css styly display: none, visible: hidden nebo další). Všechny infromace o stavu plateb by měly být ověřovány přes Váš server. Ten by si měl v případě, že ještě nedorazila push notifikace o stavu platby tuto skutečnost ověřit přímo na našem API.

UPOZORNĚNÍ

Skutečný výsledek platby, který nedorazil pomocí push notifikace je vždy třeba ověřit standardním způsobem na našem API. Z bezpečnostních důvodů nelze spoléhat na výsledek předaný zprávou z iframe nebo v URL při přesměrování (informace může být snadno podvržena).

Javascriptový kód pro vaši stránku, který zpracuje příchozí zprávu z iframu od brány Comgate:

// odchycení zprávy poslané z iframu pomocí postMessage
if (window.addEventListener) {
window.addEventListener('message', function (e) {
// validace, že message obsahuje data
if (!e || !(e !== null && e !== void 0 && e.data)) return;

// načtení dat z message
const { scope, action, value } = e.data;

// vyhodnocení, že je message od Comgate a je určena eshopu
// současně kontrola, že se jedná o informaci o stavu platby
// a hodnota je platná
if (scope === 'comgate-to-eshop' && action === 'status' && value) {
// id = XXXX-XXXX-XXXX
// isTest = true/false (testovací platba)
// refId = ID objednávky od klienta
// status = stav platby
const { id, isTest, refId, status } = value;
if (['PAID', 'AUTHORIZED'].includes(status)) {
// obsloužení stavu PAID/AUTHORIZED - zaplaceno/předautorizováno
} else if (status === 'CANCELLED') {
// obsloužení stavu CANCELLED - nezaplaceno
} else {
// obsloužení dalších stavů, atd (velmi krajní případ) ...
// PENDING, UNKNOWN
}
}
}, false);
}

Platební brána v iframu z pohledu plátce

Platební brána Comgate umožňuje uživatelům opakovat platbu, pokud se jim ji nepodařilo dokončit napoprvé. Pro další pokus je zobrazen výběr všech platebních metod.

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 a tzv. vyskočení z iframe. 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&nbsp;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"
Pozor: URL adresa (src) založené platby se může měnit.
Vždy použijte adresu, kterou vám vrátí API, a nijak do ní nezasahujte.
Atribut allow=payment je pro zobrazení brány v iframe nezbytný
-->

<iframe
class="iframe"
src="https://pay2.comgate.cz/init?id=XXXX-XXXX-XXXX"
allow="payment"
frameborder="0px"
scrolling="off">

</iframe>
</div>
</div>
</body>
</html>

Platební brána v aplikaci

Integrace platební brány do mobilní, či desktopové aplikace (dále již jen jako aplikace) je velmi podobná jako integrace do webového rozhraní. I v tomto případě je využíváno standardní API protokol. Jediným rozdílem je, že na webu je možné si zvolit buď redirect na platební bránu, nebo zobrazení brány v iframe, zatímco v aplikaci je potřeba platbu vždy otevřít v komponentě určené pro zobrazení webové stránky, typicky WebView.

XML kód

<?xml version="1.0" encoding="utf-8"?>

<androidx.constraintlayout.widget.ConstraintLayout
xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:tools="http://schemas.android.com/tools"
android:layout_width="match_parent"
android:layout_height="match_parent" tools:context=".MainActivity">


// <TextView...>

<WebView
android:id="@+id/comgatePaymentFrame"
android:layout_width="406dp" android:layout_height="760dp"
tools:ignore="MissingConstraints"
tools:layout_editor_absoluteX="2dp"
tools:layout_editor_absoluteY="59dp" />


// <Button...>

</androidx.constraintlayout.widget.ConstraintLayout>

Pro Android, .Net a Xamarin je dostupná komponenta WebView, zatímco Apple používá ve svém Swiftu WKWebView. Rozhraní WebView by mělo být zobrazeno na co největší části obrazovky tak, aby měla platební brána dostatek prostoru pro zobrazení a maximalizovala tak uživatelský komfort.

Průběh zpracování platby:

  1. Aplikace kontaktuje svůj backend (server), který požádá o založení platby
  2. Server provede HTTP request na Comgate API (/v.1.0/create) a založí platbu. Comgate na tuto žádost vrátí odpověď obsahující informace o platbě ve formátu query:
    • code - návratový kód odpovědi
    • message - stav vytvoření platby
    • transId - Comgate ID transakce
    • redirect - url pro zobrazení ve WebView
  3. Server aplikace na požadavek v bodě 1 odpoví a vrátí parametry platby získané od Comgate.
  4. Aplikace parametry platby rozparsuje (jak parsovat query string v Kotlinu a Javě), vytvoří přes co největší část displeje WebView komponentu a v ní načte URL platební brány (parametr redirect).
  5. Plátci se zobrazí možnost platby
  6. Během toho, co se plátce pokouší zaplatit, je nutné spustit status watcher. Ten se snaží co nejrychleji synchronizovat stav platby ze svého serverového backendu do aplikace. Dostupné metody:
    • Polling - krátké opakované requesty na server (cca každé 3 sekundy)
    • Long Polling - server drží requesty otevřené dokud nejsou data dostupná nebo nedojde k timeout. Pokud ještě není znám status, request se opakuje.
    • WebSockets - poskytují full-duplex komunikační kanál, kdy je server schopen aplikaci v reálném čase poslat informaci o stavu platby.
    • další…
  7. Server Comgate zasílá bezprostředně po změně stavu platby push notifikace na definou URL backendu aplikace.
  8. Plátce zaplatí objednávku
  9. Brána zobrazená ve WebView zjistí, že došlo k zaplacení a přesměruje plátce na URL definovanou v propojení obchodu.
  10. Skrytí a odstranění WebView
  11. Aplikace kontaktuje backend pro ověření stavu platby.
  12. Aplikace plátci zobrazí obrazovku o stavu platby.

Nastavení návratových URL

V klientském portálu je pro každé propojení obchodu potřeba definovat 4 speciální URL adresy, jedná se o:

  1. url zaplacený - zaplacené platby
  2. url zrušený - zrušené a expirované platby
  3. url nevyřízený - stále probíhající platby
  4. url pro předání výsledku platby - URL pro předání stavu platby (push notifikace)

Na 1. - 3. adresu je plátce směrován přímo z platební brány. Adresy mohou být stejné, mohou se lišit v parametrech pro stav platby. Plátce je také možné přesměrovat na nějakou prázdnou URL serverového API. V tomto případě je nutné zajistit automatické zjištění tohoto přesměrování a skrytí WebView.

4. adresa je určena pro server–server komunikaci. Ve chvíli, kdy je stav platby známý (zaplacená nebo zrušená/expirovaná), comgate neprodleně na tuto adresu předá o této skutečnosti informaci. Tu je nutné ověřit doprovodným requestem zpět na Comgate API pro stav platby.

Jak správně poznat okamžik, kdy je potřeba skrýt WebView

U WebView je možné detekovat konkrétní URL a na té automaticky provést další akce související se stavem platby.

Java kód

WebViewClient webViewClient = new WebViewClient() {

@Override
public void onPageFinished(WebView view, String url) {
super.onPageFinished(view, url);
if(url.equals("your link...")){
finish();
}
}
};

Zajímavé odkazy:

Zjednodušená implementace:

Jak zobrazit platbu ve WebView pro Android studio v Kotlinu:

package com.comgate.webviewtest

import androidx.appcompat.app.AppCompatActivity
import android.os.Bundle
import android.view.View
import android.webkit.WebView
import java.net.URLDecoder
import java.nio.charset.StandardCharsets

class MainActivity : AppCompatActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_main)

// TODO create payment
// ask mobile app cloud backend to create payment at Comgate API

// cloud return structured payment data
val cloudResponseFromComgate = "code=0&message=OK&transId=XXXX-XXXX-XXXX&redirect=https%3A%2F%2Fpay1.comgate.cz%2Finit%3Fid%3DXXXX-XXXX-XXXX";

// parse response
val paymentData = this.parseQuery(cloudResponseFromComgate);
val comgateMessage = paymentData["message"];
val paymentUrl = paymentData["redirect"];
val transId = paymentData["transId"];

if(comgateMessage == "OK" && paymentUrl?.isEmpty() == false && transId?.isEmpty() == false) {
val paymentView: WebView = findViewById(R.id.comgatePaymentFrame);
paymentView.visibility = View.VISIBLE;

// URL can change over time, so always use the URL that the Comgate API returns
paymentView.loadUrl(paymentUrl);

// Run status watcher
runStatusWatcher(transId);
} else {
// TODO: payment error
}
}

private fun runStatusWatcher(transId: String) {
// TODO: create payment status watcher
// ask mobile app cloud backend to payment status, you can use:
// - Polling: repeated request every 3 seconds
// - Long polling: server holds the request open until new data is available
// - WebSockets: provides a full-duplex communication channel
// - others
}

/**
* Parse query string to Map (Key->Value)
*/

private fun parseQuery(input: String): Map<String, String> {
val result = mutableMapOf<String, String>()
input.split("&").forEach { pair ->
val (key, value) = pair.split("=").map {
URLDecoder.decode(it.trim(), StandardCharsets.UTF_8.toString())
}
result[key] = value
}
return result
}
}

Stavy plateb

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

Stavy plateb

Zabezpečení

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

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, GBP, USD, PLN, HUF RON, NOK a SEK. Je k dispozici ve 14 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ě, španělštině, italš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 a Google Pay

Služby Apple Pay i Google Pay jsou součástí platební brány Comgate. Pro zobrazení služeb zákazníkovi stačí mít povolenou metodu platby kartou CARD_CZ_COMGATE nebo CARD_CZ_CSOB_2.

V rámci služby není možné použít funkcionalitu opakované a verifikační platby. Ostatní funkcionality jsou k dispozici.

Zobrazení služeb

Zobrazení služb Apple Pay i 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 Apple Pay či Google Pay zobrazí přímo v prostředí košíku e-shopu.

Rozlišujeme tedy tři možnosti zobrazení:

1. Tlačítko v karetní bráně - V případě, že se výběr platebních metod nachází na straně Comgate, není pro zobrazení služeb třeba žádných úprav. Stačí mít povolenou metodu platby kartou CARD_CZ_COMGATE nebo CARD_CZ_CSOB_2. Po výběru jedné z těchto metod ze strany plátce probíhá platba standardním procesem s přesměrováním na platební bránu, kde se služby zobrazí automaticky. Zde je zároveň plátci umožněno ručně zadat číslo karty. Pokud se na bránu dostane plátce ze zařízení či prohlížeče, které některou ze služeb nepodporují, bude plátce moci provést alespoň úhradu platební kartou.

2. Tlačítko 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 či GOOGLEPAY_REDIRECT. Následně dojde k přesměrování plátce na platební bránu pomocí získaného platebního odkazu. Tlačítka Apple Pay i Google Pay se poté zobrazí na karetní bráně automaticky. Proces platby z pohledu plátce je následně shodný s první variantou. Doporučujeme dodržovat naše zásady pro zobrazení tlačítek Google Pay a Apple Pay, které jsou dostupné níže.

3. Tlačítko součástí košíku e-shopu, bez přesměrování na karetní bránu 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. Implementace tohoto chování je náročnější, než obě výše zmíněné varianty. K tomuto účelu musíte použít námi připravenou JavaScriptovou knihovnu Checkout SDK. Detailní informace k postupu integrace naleznete v části dokumentace věnované Checkout SDK.

Pokud obchodník nedělá kontrolu dostupnosti Apple Pay a Google Pay na své straně, nemusí být tato metoda ve výsledku dostupná, i když si ji plátce vybral v košíku e-shopu. Plátci je následně nabídnuta standardní platba kartou s opisem údajů.

Zásady zobrazení tlačítek

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

Nejsnadněji, jak tuto skutečnost ověřit lze pomocí:

if (window.ApplePaySession) {
// Apple Pay JS API je dostupné => jsme na podporovaném zařízení

window.ApplePaySession.canMakePayments()
.then((result) => {
// zařízení je schopné provádět platby pomocí Apple Pay
})
}

Dále je potřeba dodržet nekolik náležitostí vyžadovaných společností Apple:

Google Pay v košíku e-shopu

Pro Google Pay je potřeba dodržet náležitosti vyžadované společností Google:

Případy, kdy se Apple Pay nezobrazí

Může se stát, že Apple Pay plátci zobrazeno nebude, pokud Apple Pay knihovna vyhodnotí, že není možné platbu na daném zařízení realizovat.

Apple Pay se nezobrazí, když:

pokud je plátce v podporovaném prohlížeči Safari, tak se Apple Pay nezobrazí, když:

Případy, kdy se Google Pay nezobrazí

Může se stát, že Google Pay plátci zobrazeno nebude, pokud Google Pay knihovna vyhodnotí, že není možné platbu na daném zařízení realizovat.

Google Pay se nezobrazí, když:

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

Utilizes HTTP POST. The connection between the e-shop and the Comgate payment gateway is implemented through redirecting the payer from the e-shop to the payment gateway. After making a payment, the payer is redirected back to the e-shop. Meanwhile, communication between the e-shop server and the payment gateway server (server-to-server) is ongoing in the background. A detailed description of the communication protocol can be found further down this page. More related information can be found on pages that describe the payment process from the user and e-shop perspective, initial setup in the client portal, or the recommended method of testing the payment gateway integration.

For easy implementation of the payment gateway, you can use this PHP SDK (installation via composer).

Payment Process

Payment Setup – Optional

The payment setup step is optional, but it’s advisable to implement it when you require assurance of secure payment initiation. Omitting the implementation of this step is possible when you don’t need to identify individual payments in the system, but just need information that someone has paid you a certain amount. This is suitable for example when implementing donation contributions or topping up customer virtual account funds, when you only care about who topped up and how much, but don’t need to distinguish individual top-ups or limit them to a minimum amount etc. The procedure is detailed in the Simple Integration - Without Payment Setup section.

For a traditional e-shop, where the buyer pays for specific goods, the payment setup step is important, and its omission is not recommended.

The e-shop initiates the payment with an HTTP request to the payment gateway server. Payment parameters, including a unique payment reference number, are passed as POST parameters of the HTTP protocol. This communication takes place between the client’s server and the payment gateway server. The payer does not see this and cannot change the payment parameters. The payment gateway server returns to the client a unique transaction ID (identifier in the Comgate payment system) and a URL to which the payer should be redirected.

Example of Background Payment Setup – HTTP request using 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

Example of Background Payment Setup – 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

The communication between the client’s system and the payment gateway is secured using a password and IP whitelist (access is allowed only from the client’s system IP addresses). It is essential to use the HTTPS protocol, which prevents the revelation of the password in case the communication is intercepted. The password is passed as a POST parameter (not a GET parameter) so that it does not get stored in the web server’s communication log.

Redirect to the Payment Gateway

After setting up the payment in the background, the e-shop receives a payment URL to display the payment gateway. The payment gateway can be displayed in two ways. The first method is by redirecting the payer to the address received by the e-shop in the HTTP response. The redirect is usually performed by sending an HTTP 302 response:

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 option, you need to generate a payment URL in the standard way, but instead of redirecting the customer to the gateway, an iframe with the payment URL is displayed on the e-shop page.

Simple Integration – Without Payment Initiation

The payment gateway allows for skipping the first step of initiating payment in the background. In this case, the Payer is redirected to the payment gateway without prior payment initiation. The redirection can be done either by submitting a form using the POST method or a direct link using the GET method. We recommend the method of using a form.

Example of Simple Integration – Form Submission (POST)

<form method="POST" action="https://payments.comgate.cz/v1.0/create">

<input type="hidden" name="merchant" value="XXXX" /> <!-- Identifier of the e-shop in the Comgate system -->

<input type="hidden" name="price" value="100" /> <!-- 100 = 1.00 CZK -->

<input type="hidden" name="curr" value="CZK" />

<input type="hidden" name="label" value="My service" />

<input type="hidden" name="refId" value="123456" />

<input type="hidden" name="method" value="ALL" />

<input type="hidden" name="country" value="CZ" />

<button type="submit">Purchase</button>

</form>

Example of Simple Integration - Redirection Using Link (GET)

<a href="https://payments.comgate.cz/v1.0/create?merchant=XXXX&price=100&curr=CZK&label=My%20service&refId=10980891&method=ALL&country=CZ" rel="nofollow">Pay</a>

In the hyperlink parameters, keep the rel="nofollow" parameter.

Back-end Payment Result Transfer

Implementing this part will ensure you automatic transmission of the status of each payment transaction directly to your server at the moment the payment status is known. Back-end payment result transfer is mandatory.

The payment result is transmitted to the Client via an HTTP request from the payment gateway server to the Client’s server. Identifiers and the payment result are passed as POST parameters of the HTTP protocol. This communication runs in the background.

The Payer is redirected to the Client’s website and the payment identifiers are passed as GET parameters of the HTTP protocol. Sending the goods or services to the Payer must be tied to the back-end payment result transfer, not to the final redirection of the Payer to the Client’s website, because the Payer can easily falsify information passed by redirection.

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
email 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 Required Description
code integer Y Return code of the method and error description:
The system expects HTTP code 200, if the payment result has been properly received.

Example of payment result transmission in the background – HTTP request using 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

Example of payment result transmission in the background – HTTP response

HTTP/2 200 OK
content-type: application/x-www-form-urlencoded; charset=UTF-8

Communication between the Client’s system and the payment gateway server is secured using a password and IP whitelist. Access must be allowed only from the IP address of the payment gateway server. IP address ranges are defined in the Security section. It is mandatory to use the HTTPS protocol, which prevents the password from being revealed if the communication is possibly intercepted. The password is passed as a POST parameter (not a GET parameter) so it is not stored in the communication log of the web server.

The e-shop on its side ensures that the goods (service) provided as part of the paid transaction (identified by a unique transaction ID) will be issued to the Payer only once (even when the result of the same payment is repeatedly transmitted to the Client’s server).

Redirecting the Payer to the Client’s website

Based on the payment status, the payer is redirected to one of three URLs that the e-shop selected when activating the service. Payment identifiers are passed as GET parameters of the HTTP protocol. The client’s system must be able to handle two basic situations:

Example of redirecting the Payer to the client’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 allows display optimized for iframe. This functionality is suitable in case you do not want to redirect the payer to the payment gateway, but display it within your system. To display the payment gateway in an iframe, you need to use the "embedded" = true parameter when creating the payment. The payment URL is generated in the standard way, but instead of redirecting the customer to the gateway, an iframe with the payment URL is displayed on the e-shop page.

There are two display options. Either you can display the payment gateway directly in the cart or using a pop-up window over your website. Implementing an iframe requires knowledge of web technologies. Iframe can only be used for card payment. For other payment methods, the payer will always be redirected to a new page.

For the correct display of the payment gateway in an iframe on the web page, we recommend making the following modification to your web pages.

Setting the display of the payment gateway

HTML code

<div id="comgate-container">
<iframe id='comgate-iframe' allow="payment" src="[payment URL]" frameborder="0px"></iframe>
</div>

CSS styles

#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

// function to open iframe with gateway
function comgateOpen() {
let comgate_container = document.getElementById("comgate-container");
comgate_container.style.display = "block";
}
// function to close iframe with gateway
function comgateClose() {
let 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 binding to a user action (clicking a button, etc.). The comgateClose() function then serves to possibly hide the iframe.

Example of calling the function to display the iframe by clicking the “Pay” button:

HTML code

<button id="comgate-open" onclick="comgateOpen()">Pay</button>

Redirecting the customer after completing the payment

After the payment is completed by the customer, they are redirected back to the e-shop on the URL that you have set in the client portal. We recommend performing one of the following modifications, which will ensure that the customer is redirected directly to the return URL and does not stay inside the iframe.

The first option is to redirect the external page to the URL you specified. This will refresh the entire page.

Javascript code for the internal page

window.top.location = window.self.location

The second option is to send a message from the page inside the iframe to the external page and process this event on the external page. This way, the entire page does not have to be refreshed.

Please note, the actual payment result needs to be obtained in the background in the usual way. For security reasons, it is not possible to rely on the result passed by a message from the iframe.

Javascript code for the internal page, which sends the external page a message with the payment ID and payment status, e.g., for a paid payment:

window.parent.postMessage('[payment id]|PAID', '*');

Javascript code for the external page, which processes the incoming message from the iframe:

// capture a message sent from the iframe using postMessage
if (window.addEventListener) {
window.addEventListener('message', function (e) {
// I get the id and payment result, the separator is a “pipe”
let message = e.data.split('|', 2);
let message_id = message[0];
let message_result = message[1];
let result = '';
if (message_result === 'PAID') {
// handling the PAID state
[...]
} else {
// handling other states, etc ...
[...]
}
}, false);
}

Payment gateway in the iframe from the payer’s perspective

The Comgate payment gateway allows users to repeat the payment if they failed to complete the payment the first time. The display of the payment gateway in the iframe to the user depends on the chosen payment method and also whether the selection of payment methods is on the e-shop side or the Comgate side.

If the selection of payment methods is on the e-shop side and the payment is therefore created with a payment method already selected, the card payment method must be chosen to display the iframe. If the user failed 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 an already selected payment method, the user is shown a selection of payment methods in the iframe. Here, it is necessary to choose card payment. If the user failed to complete the payment, the selection of payment methods in the iframe is shown again for the next attempt.

If a method other than card payment is chosen at any step of the payment process, the payer is redirected to a new page. The user will not return to the iframe.

Template for displaying the gateway in the e-shop

For easy implementation of our payment gateway into your e-shop, you can use the available template implementations below.

HTML code

<!doctype html>

<html lang="cs">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">

<title>Comgate :: working with iframe</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; /* width is set automatically to 100% of screen width for small displays */
height: 700px; /* for the new gateway, you can dynamically adjust the height according to your needs */
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>Demonstration of working with&nbsp;iframe</h1>
</div>
<div id="comgate-iframe-box">
<!--
In iframe configuration:
use scrolling="off" for the new gateway
use scrolling="on" for the old gateway
Note: The URL address (src) of the established payment can change.
Always use the address returned by the API, and do not interfere with it.
-->

<iframe
class="iframe"
src="https://pay2.comgate.cz/init?id=XXXX-XXXX-XXXX"
allow="payment"
frameborder="0px"
scrolling="off">

</iframe>
</div>
</div>
</body>
</html>

Payment gateway in the app

Integration of a payment gateway into a mobile or desktop application is very similar to integration into a web interface. In this case as well, a standard API protocol is utilized. The only difference is that on the web, it is possible to either opt for a redirect to the payment gateway or display the gateway within an iframe, whereas in the application, it is necessary to always initiate the payment within a component designated for displaying web pages, typically a WebView.

XML code

<?xml version="1.0" encoding="utf-8"?>

<androidx.constraintlayout.widget.ConstraintLayout
xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:tools="http://schemas.android.com/tools"
android:layout_width="match_parent"
android:layout_height="match_parent" tools:context=".MainActivity">


// <TextView...>

<WebView
android:id="@+id/comgatePaymentFrame"
android:layout_width="406dp" android:layout_height="760dp"
tools:ignore="MissingConstraints"
tools:layout_editor_absoluteX="2dp"
tools:layout_editor_absoluteY="59dp" />


// <Button...>

</androidx.constraintlayout.widget.ConstraintLayout>

For Android, .Net a Xamarin, the WebView component is available, while Apple utilizes WKWebView in Swift. The WebView interface should be displayed on as much of the screen as possible to provide ample space for the payment gateway and maximize user comfort.

Payment processing flow:

  1. The application contacts its backend (server), which requests the initiation of a payment.
  2. The server executes an HTTP request to the Comgate API (/v.1.0/create) and creates the payment. Comgate responds to this request with a response containing payment information in a query format:
    • code - return code of the response
    • message - status of payment creation
    • transId - Comgate transaction ID
    • redirect - URL for display in the WebView
  3. The server application responds to the request in step 1 and returns the payment parameters obtained from Comgate.
  4. The application parses the payment parameters (how to parse the query string in Kotlin and Java), creates a WebView component covering as much of the screen as possible, and loads the URL of the payment gateway (redirect parameter) into it.
  5. The payer is presented with the option to make the payment.
  6. While the payer attempts to make the payment, it is necessary to start a status watcher. This watcher attempts to synchronize the payment status from its server backend to the application as quickly as possible. Available methods:
    • Polling - short repeated requests to the server (approximately every 3 seconds).
    • Long Polling - the server keeps requests open until data is available or a timeout occurs. If the status is still unknown, the request is repeated.
    • WebSockets - provide a full-duplex communication channel, allowing the server to send real-time information about the payment status to the application.
    • Others…
  7. The Comgate server immediately sends push notifications to the defined URL of the application’s backend upon a change in the payment status.
  8. The payer completes the payment.
  9. The gateway displayed in the WebView detects the payment and redirects the payer to the URL defined in the store link.
  10. Hide and remove the WebView.
  11. The application contacts the backend to verify the payment status.
  12. The application displays the payer’s payment status screen.

Setting up return URLs

In the client portal, it’s necessary to define 4 special URL addresses for each store link:

  1. Success URL - for successful payments
  2. URL - for cancelled and expired payments
  3. Pending URL - for ongoing payments
  4. URL for delivering payment result - URL for delivering the payment status (push notification)

For the 1st to 3rd URL, the payer is redirected directly from the payment gateway. The addresses can be the same or differ in parameters for the payment status. The payer can also be redirected to an empty URL of the server API. In this case, automatic detection of this redirection and hiding of the WebView must be ensured.

The 4th URL address is intended for server-to-server communication. When the payment status is known (paid or cancelled/expired), Comgate immediately sends information about this to this address. It’s necessary to verify this with a follow-up request back to the Comgate API for the payment status.

How to correctly detect when it’s necessary to hide the WebView

With WebView, it’s possible to detect a specific URL and automatically perform further actions related to the payment status on it.

WebViewClient webViewClient = new WebViewClient() {

@Override
public void onPageFinished(WebView view, String url) {
super.onPageFinished(view, url);
if(url.equals("your link...")){
finish();
}
}
};

Interesting links:

Simplified implementation

How to display payment in a WebView for Android Studio in Kotlin

package com.comgate.webviewtest

import androidx.appcompat.app.AppCompatActivity
import android.os.Bundle
import android.view.View
import android.webkit.WebView
import java.net.URLDecoder
import java.nio.charset.StandardCharsets

class MainActivity : AppCompatActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_main)

// TODO create payment
// ask mobile app cloud backend to create payment at Comgate API

// cloud return structured payment data
val cloudResponseFromComgate = "code=0&message=OK&transId=XXXX-XXXX-XXXX&redirect=https%3A%2F%2Fpay1.comgate.cz%2Finit%3Fid%3DXXXX-XXXX-XXXX";

// parse response
val paymentData = this.parseQuery(cloudResponseFromComgate);
val comgateMessage = paymentData["message"];
val paymentUrl = paymentData["redirect"];
val transId = paymentData["transId"];

if(comgateMessage == "OK" && paymentUrl?.isEmpty() == false && transId?.isEmpty() == false) {
val paymentView: WebView = findViewById(R.id.comgatePaymentFrame);
paymentView.visibility = View.VISIBLE;

// URL can change over time, so always use the URL that the Comgate API returns
paymentView.loadUrl(paymentUrl);

// Run status watcher
runStatusWatcher(transId);
} else {
// TODO: payment error
}
}

private fun runStatusWatcher(transId: String) {
// TODO: create payment status watcher
// ask mobile app cloud backend to payment status, you can use:
// - Polling: repeated request every 3 seconds
// - Long polling: server holds the request open until new data is available
// - WebSockets: provides a full-duplex communication channel
// - others
}

/**
* Parse query string to Map (Key->Value)
*/

private fun parseQuery(input: String): Map<String, String> {
val result = mutableMapOf<String, String>()
input.split("&").forEach { pair ->
val (key, value) = pair.split("=").map {
URLDecoder.decode(it.trim(), StandardCharsets.UTF_8.toString())
}
result[key] = value
}
return result
}
}

Payment statuses

A payment can only be considered paid in the PAID status. The PENDING status is not final and may be followed by the CANCELLED status.

Payment statuses

API protocol - Comgate payment gateway

Security

Communication between the Comgate payment system and the e-shop takes place in three ways.

In all three cases, the use of the encrypted HTTPS protocol is necessary. The payment gateway only supports secure TLS/SSL protocol settings with the following allowed ciphers: https://github.com/cloudflare/sslconfig/blob/master/conf

In the case of server-to-server communication, communication is secured using a password (secret) and IP whitelist settings. These parameters can be set in the client portal environment.

Cloudflare service precedes the payment initiation. You can find the list of allowed IP addresses of Cloudflare here: https://www.cloudflare.com/ips-v4

The IP address range used by the Comgate system is defined as 89.185.236.55/32. This range is only used for transferring the payment result in the background.

Payment Gateway Methods

Payment Buttons

Fast bank transfers (payment buttons) are provided from all major banks in the Czech Republic, Poland, and Slovakia. You can find a list of available banks in our data tables. In the case of payment buttons, you can utilize features such as refunds and cancellation of payments. It is not possible to display the payment button directly in the e-shop (iframe). The payer is always redirected to the bank.

Card Payment

The payment gateway accepts VISA, VISA Electron, Mastercard, Maestro card payments. Payments are available in currencies CZK, EUR, USD, GBP, PLN, HUF RON, NOK and SEK. It is available in 14 languages - Czech, Slovak, English, German, French, Polish, Hungarian, Croatian, Slovenian, Romanian, Norwegian, Spanish, Italian and Swedish.

Within card payment, you can use many features. These include refunding payment, canceling unfinished payment, recurring payments (for example, for subscriptions with regular deduction of funds from the payer’s card), or preauthorization. Card payment can also be displayed directly in the e-shop (iframe).

Apple Pay and Google Pay

Both Apple Pay and Google Pay services are part of the Comgate payment gateway. To view customer services, you only need to have the CARD_CZ_COMGATE or CARD_CZ_CSOB_2 card payment method enabled.

Recurring and verification payment functionality cannot be used within the service. Other functionalities are available.

Displaying services

The display of both Apple Pay and Google Pay services depends on whether the selection of payment methods is in the e-shop cart or the e-shop uses the selection of methods from Comgate. It is also necessary to distinguish whether the payer should be redirected to the card gate or Apple Pay or Google Pay will be displayed directly in the e-shop cart.

We therefore distinguish three possibilities of displaying:

1. The button in the card gateway - If the choice of payment methods is on the Comgate side, no modifications are required to display the services. It is sufficient to have the card payment method CARD_CZ_COMGATE or CARD_CZ_CSOB_2 enabled. After the payer has selected one of these methods, the payment is made through the standard process with redirection to the payment gateway, where the services are displayed automatically. Here, the payer is also allowed to manually enter the card number. If the payer reaches the gateway from a device or browser that does not support any of the services, the payer will be able to make at least a payment by credit card.

2. The button in the e-shop’s cart with the redirection of the payer to the card gateway - If the choice of payment methods is on the side of the e-shop, the payment is based as a regular payment, however, in the request you need to call the APPLEPAY_REDIRECT or GOOGLEPAY_REDIRECT method. Subsequently, the payer is redirected to the payment gateway using the obtained payment link. Both Apple Pay and Google Pay buttons will then appear automatically on the card gateway. Subsequently, the payment process from the payer’s point of view is identical to the first option. We recommend that you follow our Google Pay and Apple Pay Button Display Policy, which are available below.

3. The button in the e-shop’s cart with the redirection of the payer to the card gateway This integration option does not redirect the payer to the card gateway and the payment is completely processed directly in the e-shop environment. Implementation of this behavior is more challenging than both of the above mentioned options. For this purpose, you must use our prepared JavaScript library Checkout SDK. Detailed information on the integration process can be found in Checkout SDK documentation section.

If the merchant does not check the availability of Apple Pay and Google Pay on their side, this method may not be available as a result, even if the payer chose it in the e-shop cart. The payer is then offered a standard payment by card with a copy of the data.

Button display policy

Apple Pay in shopping cart

Apple Pay is only available to users who have a Safari web browser and a custom Apple device that has a Touch ID or Face ID. These devices include MacBook, iPhone, iPad and desktop Mac. For this reason, we recommend that you display the service in your order only to clients who can pay with Apple Pay. Instructions can be found directly at Apple’s developer site.

The easiest way to verify this is through:

if (window.ApplePaySession) {
// Apple Pay JS API is available => we are on a supported device

window.ApplePaySession.canMakePayments()
.then((result) => {
// device is able to make payments using Apple Pay
})
}

There are also several requirements required by Apple:

Google Pay in shopping cart

For Google Pay, you need to comply with the requirements required by Google:

Cases when Apple Pay does not appear

It may happen that Apple Pay will not be shown to the payer if the Apple Pay library evaluates that it is not possible to make the payment on the device.

Apple Pay does not appear when:

if the payer is in a supported Safari browser, then Apple Pay will not appear when:

Cases when Google Pay does not appear

It may happen that Google Pay will not be shown to the payer if the Google Pay library evaluates that it is not possible to make the payment on the device.

Google Pay does not appear when:

Deferred payment

Deferred payment allows e-shop customers to delay the payment for a purchase by several days. However, the e-shop receives its money in the standard time.

To display the method to the payer (the e-shop customer), it is necessary to call the LATER_ALL payment method when initiating the payment. If the selection of payment methods is on the side of Comgate, all available methods of deferred payment are displayed to the payers. If the e-shop has the selection of payment methods in its cart, we recommend using this text as the method name for the payer: “Deferred payment”. The text of the payment method description is “Shop now, pay later.”

This method is only available for the CZK currency and citizens of the Czech Republic.

Pay in Thirds

Payment in thirds allows e-shop customers to spread the payment for a purchase over three monthly installments. The e-shop receives a payment confirmation immediately and we will also credit the value of the purchase in the standard time.

To display the method to the payer (the e-shop customer), it is necessary to call the PART_ALL payment method when initiating the payment. If the selection of payment methods is on the side of Comgate, installment payment is always displayed with a payment value equal to or higher than 1500 CZK for PART_TWISTO and 3000 CZK for PART_SKIPPAY.

This method is only available for the CZK currency 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ý popis
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
email 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ý popis
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:

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' allow="payment" 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

Iframe

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.

Platobná brána v aplikácii

Integrácia platobnej brány do mobilnej, či desktopovej aplikácie (ďalej už len ako aplikácia) je veľmi podobná ako integrácia do webového rozhrania. Aj v tomto prípade je využívaný štandardný API protokol. Jediným rozdielom je, že na webe je možné zvoliť si buď redirect na platobnú bránu, alebo zobrazenie brány v iframe, zatiaľ čo v aplikácii je potrebné platbu vždy otvoriť v komponente určenom pre zobrazenie webovej stránky, typicky WebView.

XML kód

<?xml version="1.0" encoding="utf-8"?>

<androidx.constraintlayout.widget.ConstraintLayout
xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:tools="http://schemas.android.com/tools"
android:layout_width="match_parent"
android:layout_height="match_parent" tools:context=".MainActivity">


// <TextView...>

<WebView
android:id="@+id/comgatePaymentFrame"
android:layout_width="406dp" android:layout_height="760dp"
tools:ignore="MissingConstraints"
tools:layout_editor_absoluteX="2dp"
tools:layout_editor_absoluteY="59dp" />


// <Button...>

</androidx.constraintlayout.widget.ConstraintLayout>

Pre Android, .Net a Xamarin je dostupný komponent WebView, zatiaľ čo Apple používa vo svojom Swifte WKWebView. Rozhranie WebView by malo byť zobrazené na čo najväčšej časti obrazovky tak, aby mala platobná brána dostatok priestoru pre zobrazenie a maximalizovala tak používateľský komfort.

Priebeh spracovania platby:

  1. Aplikácia kontaktuje svoj backend (server), ktorý požiada o založenie platby
  2. Server vykoná HTTP request na Comgate API (/v.1.0/create) a založí platbu. Comgate na túto žiadosť vráti odpoveď obsahujúcu informácie o platbe vo formáte query:
    • code - návratový kód odpovede
    • message - stav vytvorenia platby
    • transId - Comgate ID transakcie
    • redirect - url pre zobrazenie vo WebView
  3. Server aplikácia na požiadavku v bode 1 odpovie a vráti parametre platby získané od Comgate.
  4. Aplikácia parametre platby rozparsuje (ako parsovať query string v Kotlinu a Javě), vytvorí cez čo najväčšiu časť displeja WebView komponent a v ňom načíta URL platobnej brány (parameter redirect).
  5. Platcovi sa zobrazí možnosť platby.
  6. Počas toho, čo sa platca pokúša zaplatiť, je nutné spustiť status watcher. Ten sa snaží čo najrýchlejšie synchronizovať stav platby zo svojho serverového backendu do aplikácie. Dostupné metódy:
    • Polling - krátke opakované requesty na server (cca každé 3 sekundy)
    • Long Polling - server drží requesty otvorené pokiaľ nie sú dáta dostupné alebo nedôjde k timeoutu. Pokiaľ ešte nie je známy status, request sa opakuje.
    • WebSockets - poskytujú full-duplex komunikačný kanál, kedy je server schopný aplikácii v reálnom čase poslať informáciu o stave platby.
    • ďalšie…
  7. Server Comgate zasiela okamžite po zmene stavu platby push notifikace na definovanú URL backendu aplikácie.
  8. Platca zaplatí objednávku.
  9. Brána zobrazená vo WebView zistí, že došlo k zaplateniu a presmeruje platcu na URL definovanú v prepojení obchodu.
  10. Skrytie a odstránenie WebView.
  11. Aplikácia kontaktuje backend pre overenie stavu platby.
  12. Aplikácia platcovi zobrazí obrazovku o stave platby.

Nastavenie návratových URL

V klientskom portáli je pre každé prepojenie obchodu potrebné definovať 4 špeciálne URL adresy, jedná sa o:

  1. url zaplatený - zaplatené platby
  2. url zrušený - zrušené a expirované platby
  3. url nevyriešený - stále prebiehajúce platby
  4. url pre odovzdanie výsledku platby - URL pre odovzdanie stavu platby (push notifikácia)

Na 1. - 3. adresu je platca presmerovaný priamo z platobnej brány. Adresy môžu byť rovnaké, môžu sa líšiť v parametroch pre stav platby. Platcu je tiež možné presmerovať na nejakú prázdnu URL serverového API. V tomto prípade je nutné zabezpečiť automatické zistenie tohto presmerovania a skrytie WebView.

4. adresa je určená pre server–server komunikáciu. Vo chvíli, kedy je stav platby známy (zaplatená alebo zrušená/expirovaná), comgate okamžite na túto adresu pošle o tejto skutočnosti informáciu. Tú je nutné overiť sprievodným requestom späť na Comgate API pre stav platby.

Ako správne poznať moment, kedy je potrebné skryť WebView

Pri WebView je možné detekovať konkrétnu URL a na tej automaticky vykonať ďalšie akcie súvisiace so stavom platby.

Java kód

WebViewClient webViewClient = new WebViewClient() {

@Override
public void onPageFinished(WebView view, String url) {
super.onPageFinished(view, url);
if(url.equals("your link...")){
finish();
}
}
};

Zaujímavé odkazy:

Zjednodušená Implementácia:

Ako zobraziť platbu vo WebView pre Android štúdio v Kotline

package com.comgate.webviewtest

import androidx.appcompat.app.AppCompatActivity
import android.os.Bundle
import android.view.View
import android.webkit.WebView
import java.net.URLDecoder
import java.nio.charset.StandardCharsets

class MainActivity : AppCompatActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_main)

// TODO create payment
// ask mobile app cloud backend to create payment at Comgate API

// cloud return structured payment data
val cloudResponseFromComgate = "code=0&message=OK&transId=XXXX-XXXX-XXXX&redirect=https%3A%2F%2Fpay1.comgate.cz%2Finit%3Fid%3DXXXX-XXXX-XXXX";

// parse response
val paymentData = this.parseQuery(cloudResponseFromComgate);
val comgateMessage = paymentData["message"];
val paymentUrl = paymentData["redirect"];
val transId = paymentData["transId"];

if(comgateMessage == "OK" && paymentUrl?.isEmpty() == false && transId?.isEmpty() == false) {
val paymentView: WebView = findViewById(R.id.comgatePaymentFrame);
paymentView.visibility = View.VISIBLE;

// URL can change over time, so always use the URL that the Comgate API returns
paymentView.loadUrl(paymentUrl);

// Run status watcher
runStatusWatcher(transId);
} else {
// TODO: payment error
}
}

private fun runStatusWatcher(transId: String) {
// TODO: create payment status watcher
// ask mobile app cloud backend to payment status, you can use:
// - Polling: repeated request every 3 seconds
// - Long polling: server holds the request open until new data is available
// - WebSockets: provides a full-duplex communication channel
// - others
}

/**
* Parse query string to Map (Key->Value)
*/

private fun parseQuery(input: String): Map<String, String> {
val result = mutableMapOf<String, String>()
input.split("&").forEach { pair ->
val (key, value) = pair.split("=").map {
URLDecoder.decode(it.trim(), StandardCharsets.UTF_8.toString())
}
result[key] = value
}
return result
}
}

Stavy platieb

Platbu možno považovať za zaplatenú iba v stave PAID. Stav PENDING nie je koncový a môže po ňom nasledovať stav CANCELLED.

Stavy plateb

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.

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 a Google Pay

Apple Pay aj Google Pay sú súčasťou platobnej brány Comgate. Na zobrazenie týchto služieb stačí, aby mali zákazníci povolenú platobnú metódu CARD_CZ_COMGATE alebo CARD_CZ_CSOB_2.

V rámci služby nie je možné používať funkcie opakovaných a overovacích platieb. Ostatné funkcie sú k dispozícii.

Zobrazenie služieb

Zobrazenie služieb Apple Pay aj Google Pay závisí od toho, či je výber platobných metód v košíku e-shopu alebo či e-shop používa výber metód Comgate. Taktiež je potrebné rozlišovať, či má byť platiteľ presmerovaný na kartovú bránu, alebo či sa Apple Pay alebo Google Pay zobrazuje priamo v prostredí košíka e-shopu.

K dispozícii sú tri možnosti zobrazenia:

1. Tlačidlo v bráne karty - Ak sa výber spôsobov platby nachádza na stránke Comgate, na zobrazenie služieb nie sú potrebné žiadne úpravy. Stačí, ak je zapnutá platobná metóda CARD_CZ_COMGATE alebo CARD_CZ_CSOB_2. Po výbere jednej z týchto metód platiteľom platba prejde štandardným procesom s presmerovaním na platobnú bránu, kde sa služby zobrazia automaticky. Tu môže platiteľ tiež ručne zadať číslo karty. Ak platiteľ pristupuje k platobnej bráne zo zariadenia alebo prehliadača, ktorý nepodporuje niektorú zo služieb, bude môcť vykonať aspoň platbu kreditnou kartou.

3. Tlačidlo v košíku e-shopu s presmerovaním platiteľa na platobnú bránu - Ak je výber platobných metód na strane e-shopu, platba sa nastaví ako bežná platba, ale v požiadavke je potrebné zavolať metódu APPLEPAY_REDIRECT alebo GOOGLEPAY_REDIRECT. Platiteľ je potom presmerovaný na platobnú bránu pomocou získaného platobného odkazu. Na platobnej bráne sa potom automaticky zobrazia tlačidlá Apple Pay aj Google Pay. Proces platby z pohľadu platiteľa je potom totožný s prvou možnosťou. Odporúčame dodržiavať naše zásady zobrazovania tlačidiel Google Pay a Apple Pay, ktoré sú k dispozícii nižšie.

3. Tlačidlo v košíku e-shopu bez presmerovania na platobnú bránu Pri tejto možnosti integrácie nie je platiteľ presmerovaný na kartovú bránu a platba sa kompletne spracuje priamo v prostredí e-shopu. Implementácia tohto správania je náročnejšia ako oba vyššie uvedené varianty. Na tento účel je potrebné použiť našu JavaScriptovú knižnicu Checkout SDK. Podrobné informácie o postupe integrácie nájdete v sekcii dokumentácie Checkout SDK.

Ak obchodník na svojej strane neskontroluje dostupnosť Apple Pay a Google Pay, táto metóda nemusí byť vo výsledku dostupná, aj keď ju platiteľ v košíku e-shopu zvolil. Platiteľovi sa potom ponúkne štandardná platba kartou s kópiou údajov.

Zásady zobrazovania tlačidiel

Apple Pay v košíku e-shopu

Apple Pay je k dispozícii len používateľom s webovým prehliadačom Safari a zariadením Apple s Touch ID alebo Face ID. Medzi tieto zariadenia patria MacBook, iPhone, iPad a stolný Mac. Z tohto dôvodu odporúčame, aby si túto službu v objednávke zobrazovali len klienti, ktorí môžu platiť pomocou služby Apple Pay. Návod nájdete priamo na stránke vývojárov spoločnosti Apple.

Túto skutočnosť si najjednoduchšie overíte tak, že:

if (window.ApplePaySession) {
// Rozhranie Apple Pay JS API je k dispozícii => sme na podporovanom zariadení

window.ApplePaySession.canMakePayments()
.then((result) => {
// zariadenie dokáže uskutočňovať platby pomocou služby Apple Pay
})
}

Existuje aj niekoľko požiadaviek vyžadovaných spoločnosťou Apple:

Google Pay v košíku e-shopu

V prípade služby Google Pay musíte splniť formálne požiadavky spoločnosti Google:

Prípady, keď sa Apple Pay nezobrazí

Služba Apple Pay sa platiteľovi nemusí zobraziť, ak knižnica Apple Pay vyhodnotí, že platbu nie je možné v zariadení spracovať.

Apple Pay sa nezobrazí, keď:

ak je platiteľ v podporovanom prehliadači Safari, Apple Pay sa nezobrazí, keď:

Prípady, v ktorých sa služba Google Pay nezobrazuje

Môže sa stať, že služba Google Pay sa platiteľovi nezobrazí, ak knižnica Google Pay vyhodnotí, že platbu nemožno v zariadení spracovať.

Platba Google sa nezobrazí, keď:

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

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

ATTENTIONUPOZORNĚNÍUPOZORNENIE

The URL and structure of the payment code may change. Always use the address returned by the API and do not tamper with it. If you want to save the payment code, use the transId parameter. Never parse data from specific positions in the text, they can also change.URL adresa a struktura kódu založené platby se může měnit. Vždy použijte adresu, kterou vám vrátí API, a nijak do ní nezasahujte. Pokud chcete uložit kód platby, použijte parametr transId. Nikdy neparsujte data z konkrétních pozic v textu, mohou se též měnit.Adresa URL a štruktúra kódu platby sa môže zmeniť. Vždy používajte adresu vrátenú rozhraním API a nemanipulujte s ňou. Ak chcete platobný kód uložiť, použite parameter transId. Nikdy neparazitujte na údajoch z konkrétnych pozícií v texte, tie sa tiež môžu zmeniť.

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: true
secret: gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y
preauth: true
initRecurring: true
verification: true
applePayPayload: string
expirationTime: string
dynamicExpiration: true
url_paid: string
url_cancelled: string
url_pending: string

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 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á 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 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 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 prevedie peniaze. Ak parameter nevyplníte, použije sa predvolený účet Klienta. Zoznam účtov Klienta nájdete na https://portal.comgate.cz/.
email 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’.
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.
url_paid string false Custom settings for single payment. E.g.: ‘https://www.example.com/result.php?id=${id}&refId=${refId}Individuální nastavení pro jednotlivé platby. Např. ‘https://www.example.com/result.php?id=${id}&refId=${refId}Posamezne nastavitve za posamezna plačila. Na primer: ‘https://www.example.com/result.php?id=${id}&refId=${refId}
url_cancelled string false Custom settings for single payment. E.g.: ‘https://www.example.com/result.php?id=${id}&refId=${refId}Individuální nastavení pro jednotlivé platby. Např. ‘https://www.example.com/result.php?id=${id}&refId=${refId}Posamezne nastavitve za posamezna plačila. Na primer: ‘https://www.example.com/result.php?id=${id}&refId=${refId}
url_pending string false Custom settings for single payment. E.g.: ‘https://www.example.com/result.php?id=${id}&refId=${refId}Individuální nastavení pro jednotlivé platby. Např. ‘https://www.example.com/result.php?id=${id}&refId=${refId}Posamezne nastavitve za posamezna plačila. Na primer: ‘https://www.example.com/result.php?id=${id}&refId=${refId}

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.

cURLPHPJavaPythonC# Code samples

# You can also use wget
curl -X POST https://payments.comgate.cz/v1.0/create \
--data "&merchant=123456&price=1000&curr=CZK&label=Product 123&refId=order445566&method=ALL&email=platce@email.com&prepareOnly=true&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y" \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Accept: application/x-www-form-urlencoded'
<?php

$headers = array(
'Content-Type' => 'application/x-www-form-urlencoded',
'Accept' => 'application/x-www-form-urlencoded',
);

// Define array of request body.
$request_params = [
"merchant" => "123456",
"price" => "1000",
"curr" => "CZK",
"label" => "Product 123",
"refId" => "order445566",
"method" => "ALL",
"email" => "platce@email.com",
"prepareOnly" => "true",
"secret" => "gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y",
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://payments.comgate.cz/v1.0/create');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($request_params));
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

try {
$response = curl_exec($ch);

if ($response === false) {
throw new \Exception(curl_error($ch), curl_errno($ch));
}

print_r($response);
} catch (\Exception $e) {
// handle exception or api errors.
print_r($e->getMessage());
} finally {
curl_close($ch);
}

// ...

String params = "&merchant=123456&price=1000&curr=CZK&label=Product 123&refId=order445566&method=ALL&email=platce@email.com&prepareOnly=true&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",
"price": "1000",
"curr": "CZK",
"label": "Product 123",
"refId": "order445566",
"method": "ALL",
"email": "platce@email.com",
"prepareOnly": "true",
"secret": "gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y",
}, headers = headers)

print(r.text)
using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;
using System.Collections.Generic;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
private HttpClient Client { get; set; }

/// <<summary>>
/// Setup http client
/// <</summary>>
public HttpExample()
{
Client = new HttpClient();
}


/// Make a dummy request
public async Task MakePostRequest()
{
string url = "https://payments.comgate.cz/v1.0/create";

var content = new Dictionary<string, string> {
{"merchant", "123456"},
{"price", "1000"},
{"curr", "CZK"},
{"label", "Product 123"},
{"refId", "order445566"},
{"method", "ALL"},
{"email", "platce@email.com"},
{"prepareOnly", "true"},
{"secret", "gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y"},
};

await PostAsync(content, url);
}

/// Performs a POST Request
public async Task PostAsync(Dictionary<string, string> content, string url)
{
//Serialize Object
StringContent jsonContent = SerializeObject(content);

//Execute POST request
HttpResponseMessage response = await Client.PostAsync(url, jsonContent);
}



/// Serialize an object to Json
private StringContent SerializeObject(Dictionary<string, string> content)
{
//Serialize Object
string jsonObject = JsonConvert.SerializeObject(content);

//Create Json UTF8 String Content
return new StringContent(jsonObject, Encoding.UTF8, "application/json");
}

/// Deserialize object from request response
private async Task DeserializeObject(HttpResponseMessage response)
{
//Read body
string responseBody = await response.Content.ReadAsStringAsync();

//Deserialize Body to object
var result = JsonConvert.DeserializeObject(responseBody);
}
}

cancel

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

cURLPHPJavaPythonC# 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

$headers = array(
'Content-Type' => 'application/x-www-form-urlencoded',
'Accept' => 'application/x-www-form-urlencoded',
);

// Define array of request body.
$request_params = [
"merchant" => "123456",
"transId" => "AB12-CD34-EF56",
"secret" => "gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y",
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://payments.comgate.cz/v1.0/cancel');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($request_params));
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

try {
$response = curl_exec($ch);

if ($response === false) {
throw new \Exception(curl_error($ch), curl_errno($ch));
}

print_r($response);
} catch (\Exception $e) {
// handle exception or api errors.
print_r($e->getMessage());
} finally {
curl_close($ch);
}

// ...

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)
using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;
using System.Collections.Generic;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
private HttpClient Client { get; set; }

/// <<summary>>
/// Setup http client
/// <</summary>>
public HttpExample()
{
Client = new HttpClient();
}


/// Make a dummy request
public async Task MakePostRequest()
{
string url = "https://payments.comgate.cz/v1.0/cancel";

var content = new Dictionary<string, string> {
{"merchant", "123456"},
{"transId", "AB12-CD34-EF56"},
{"secret", "gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y"},
};

await PostAsync(content, url);
}

/// Performs a POST Request
public async Task PostAsync(Dictionary<string, string> content, string url)
{
//Serialize Object
StringContent jsonContent = SerializeObject(content);

//Execute POST request
HttpResponseMessage response = await Client.PostAsync(url, jsonContent);
}



/// Serialize an object to Json
private StringContent SerializeObject(Dictionary<string, string> content)
{
//Serialize Object
string jsonObject = JsonConvert.SerializeObject(content);

//Create Json UTF8 String Content
return new StringContent(jsonObject, Encoding.UTF8, "application/json");
}

/// Deserialize object from request response
private async Task DeserializeObject(HttpResponseMessage response)
{
//Read body
string responseBody = await response.Content.ReadAsStringAsync();

//Deserialize Body to object
var result = JsonConvert.DeserializeObject(responseBody);
}
}

recurring

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 paragraphs.
Test recurring payments created with the e-mail ‘recurring.cancelled@comgate.cz’ will have all subsequent payments (apart from the initial one) tagged as CANCELLED (unpaid)
Opakované platby, zapamatování karetních údajů
Platební brána umožňuje zadávání opakovaných plateb, to je plateb na jedno kliknutí. První (iniciační) platba probíhá standardním procesem s přesměrováním na platební bránu, následující platby už probíhají kompletně na pozadí. Systém tak umožňuje plátci zaplatit během několika sekund bez nutnosti vyplňovat informace o platební kartě.
Tato funkcionalita je dostupná na vyžádání. V případě opakovaných plateb na začátku zakládáme iniciační platbu, která se zakládá jako běžná platba, pouze se v požadavku nachází navíc parametr ‘initRecurring’ - metoda create. Následné opakované platby jsou už zakládány metodou recurring a jsou vázány na Comgate ID iniciační transakce. Toto ID musí být v systému Klienta vázáno na konkrétního Plátce.
Po založení opakované platby nedochází k přesměrování Plátce na platební bránu, protože celý proces probíhá na pozadí, Klientovi je pouze předán stav založení platby, a ten následně zobrazí tento stav Plátci.

Následující opakované platby
Založení druhé a následující opakované platby do platební brány je možné pouze při akceptaci karet pro e-shopy, které mají službu povolenou. První (iniciační) platba probíhá standardní cestou (viz Založení platby). Proces založení druhé a každé další platby probíhá kompletně na pozadí, tyto platby jsou vázány na iniciační přes Comgate ID iniciační platby. Toto ID se musí nacházet v požadavku v parametru ‘initRecurringId’. Plátci je v systému e-shopu jako výsledek zobrazen stav platby.

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

Rekurentní platby (recurring)
Rekurentí platby, tzn. opakované platby s předem definovanou částkou a periodou (např. měsíční, týdenní apod.) lze realizovat pomocí služby Opakované platby, která je popsána v předchozích odstavcích.
Testovací rekurentní platby (s výjimkou iniciační) založené s e-mailem ‘recurring.cancelled@comgate.cz’ budou automaticky označeny jako CANCELLED (nezaplacené)
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.
Testovacie opakované platby (okrem iniciačných) vytvorené pomocou e-mailu ‘recurring.cancelled@comgate.cz’ budú automaticky označené ako CANCELLED (nezaplatené)

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/
email 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 error
návratový kód metody a popis chyby:
0 OK
1100 neznámá chyba
1102 zadaný jazyk není podporován
1103 nesprávně zadaná metoda
1104 nelze načíst platbu
1200 databázová chyba
1301 neznámý e-shop
1303 propojení nebo jazyk chybí
1304 neplatná kategorie
1305 chybí popis produktu
1308 vybraný způsob platby není povolen
1309 nesprávná částka
1310 neznámá měna
1311 neplatný identifikátor bankovního účtu e-shopu
1316 e-shop nemá povolené opakované platby
1317 neplatná metoda – nepodporuje opakované platby
1318 iniciační platba nebyla nalezena
1319 nelze založit platbu, problém na straně banky
1399 neočekávaný výsledek z databáze
1400 chybný dotaz
1500 neočekávaná chyba
Návratový kód metódy a opis chyby:
0 OK
1100 neznáma chyba
1102 zadaný jazyk nie je podporovaný
1103 nesprávne zadaná metóda
1104 nemožno načítať platbu
1200 databázová chyba
1301 neznámy e-shop
1303 prepojenie alebo jazyk chýba
1304 neplatná kategória
1305 chýba opis produktu
1308 vybraný spôsob platby nie je povolený
1309 nesprávna čiastka
1310 neznáma mena
1311 neplatný identifikátor bankového účtu e-shopu
1316 e-shop nemá povolené opakované platby
1317 neplatná metóda - nepodporuje opakované platby
1318 iniciačná platba nebola nájdená
1319 nemožno založiť platbu, problém na strane banky
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

cURLPHPJavaPythonC# 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

$headers = array(
'Content-Type' => 'application/x-www-form-urlencoded',
'Accept' => 'application/x-www-form-urlencoded',
);

// 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",
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://payments.comgate.cz/v1.0/recurring');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($request_params));
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

try {
$response = curl_exec($ch);

if ($response === false) {
throw new \Exception(curl_error($ch), curl_errno($ch));
}

print_r($response);
} catch (\Exception $e) {
// handle exception or api errors.
print_r($e->getMessage());
} finally {
curl_close($ch);
}

// ...

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)
using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;
using System.Collections.Generic;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
private HttpClient Client { get; set; }

/// <<summary>>
/// Setup http client
/// <</summary>>
public HttpExample()
{
Client = new HttpClient();
}


/// Make a dummy request
public async Task MakePostRequest()
{
string url = "https://payments.comgate.cz/v1.0/recurring";

var content = new Dictionary<string, string> {
{"merchant", "123456"},
{"price", "10000"},
{"curr", "CZK"},
{"label", "string"},
{"refId", "2010102600"},
{"email", "platce@email.com"},
{"prepareOnly", "true"},
{"secret", "gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y"},
{"initRecurringId", "AB12-CD34-EF56"},
};

await PostAsync(content, url);
}

/// Performs a POST Request
public async Task PostAsync(Dictionary<string, string> content, string url)
{
//Serialize Object
StringContent jsonContent = SerializeObject(content);

//Execute POST request
HttpResponseMessage response = await Client.PostAsync(url, jsonContent);
}



/// Serialize an object to Json
private StringContent SerializeObject(Dictionary<string, string> content)
{
//Serialize Object
string jsonObject = JsonConvert.SerializeObject(content);

//Create Json UTF8 String Content
return new StringContent(jsonObject, Encoding.UTF8, "application/json");
}

/// Deserialize object from request response
private async Task DeserializeObject(HttpResponseMessage response)
{
//Read body
string responseBody = await response.Content.ReadAsStringAsync();

//Deserialize Body to object
var result = JsonConvert.DeserializeObject(responseBody);
}
}

refund

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 error
návratový kód metódy a opis chyby:
0 OK
1100 neznáma chyba
1200 databázová chyba
1400 chybná otázka
1401 refundovaná platba je v stave CANCELLED
1402 čiastka prevyšuje povolenú výšku
1500 neočakávaná chyba
návratový kód metódy a opis chyby:
0 OK
1100 neznáma chyba
1200 databázová chyba
1400 chybná otázka
1401 refundovaná platba je v stave CANCELLED
1402 čiastka prevyšuje povolenú výšku
1500 neočakávaná chyba
message string true none none

cURLPHPJavaPythonC# 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

$headers = array(
'Content-Type' => 'application/x-www-form-urlencoded',
'Accept' => 'application/x-www-form-urlencoded',
);

// Define array of request body.
$request_params = [
"merchant" => "123456",
"transId" => "AB12-CD34-EF56",
"secret" => "gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y",
"amount" => "10000",
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://payments.comgate.cz/v1.0/refund');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($request_params));
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

try {
$response = curl_exec($ch);

if ($response === false) {
throw new \Exception(curl_error($ch), curl_errno($ch));
}

print_r($response);
} catch (\Exception $e) {
// handle exception or api errors.
print_r($e->getMessage());
} finally {
curl_close($ch);
}

// ...

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)
using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;
using System.Collections.Generic;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
private HttpClient Client { get; set; }

/// <<summary>>
/// Setup http client
/// <</summary>>
public HttpExample()
{
Client = new HttpClient();
}


/// Make a dummy request
public async Task MakePostRequest()
{
string url = "https://payments.comgate.cz/v1.0/refund";

var content = new Dictionary<string, string> {
{"merchant", "123456"},
{"transId", "AB12-CD34-EF56"},
{"secret", "gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y"},
{"amount", "10000"},
};

await PostAsync(content, url);
}

/// Performs a POST Request
public async Task PostAsync(Dictionary<string, string> content, string url)
{
//Serialize Object
StringContent jsonContent = SerializeObject(content);

//Execute POST request
HttpResponseMessage response = await Client.PostAsync(url, jsonContent);
}



/// Serialize an object to Json
private StringContent SerializeObject(Dictionary<string, string> content)
{
//Serialize Object
string jsonObject = JsonConvert.SerializeObject(content);

//Create Json UTF8 String Content
return new StringContent(jsonObject, Encoding.UTF8, "application/json");
}

/// Deserialize object from request response
private async Task DeserializeObject(HttpResponseMessage response)
{
//Read body
string responseBody = await response.Content.ReadAsStringAsync();

//Deserialize Body to object
var result = JsonConvert.DeserializeObject(responseBody);
}
}

capturePreauth

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 error
návratový kód metody a popis chyby:
0 OK
1100 neznámá chyba
1104 nelze načíst platbu
1200 databázová chyba
1301 neznámý e-shop
1303 propojení nebo jazyk chybí
1399 neočekávaný výsledek z databáze
1400 chybný dotaz
1500 neočekávaná chyba
návratový kód metódy a opis chyby:
0 OK
1100 neznáma chyba
1104 nemožno načítať platbu
1200 databázová chyba
1301 neznámy e-shop
1303 prepojenie alebo jazyk chýba
1399 neočakávaný výsledok z databázy
1400 chybná otázka
1500 neočakávaná chyba
message string true none none

cURLPHPJavaPythonC# 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

$headers = array(
'Content-Type' => 'application/x-www-form-urlencoded',
'Accept' => 'application/x-www-form-urlencoded',
);

// Define array of request body.
$request_params = [
"merchant" => "123456",
"transId" => "AB12-CD34-EF56",
"secret" => "gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y",
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://payments.comgate.cz/v1.0/capturePreauth');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($request_params));
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

try {
$response = curl_exec($ch);

if ($response === false) {
throw new \Exception(curl_error($ch), curl_errno($ch));
}

print_r($response);
} catch (\Exception $e) {
// handle exception or api errors.
print_r($e->getMessage());
} finally {
curl_close($ch);
}

// ...

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)
using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;
using System.Collections.Generic;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
private HttpClient Client { get; set; }

/// <<summary>>
/// Setup http client
/// <</summary>>
public HttpExample()
{
Client = new HttpClient();
}


/// Make a dummy request
public async Task MakePostRequest()
{
string url = "https://payments.comgate.cz/v1.0/capturePreauth";

var content = new Dictionary<string, string> {
{"merchant", "123456"},
{"transId", "AB12-CD34-EF56"},
{"secret", "gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y"},
};

await PostAsync(content, url);
}

/// Performs a POST Request
public async Task PostAsync(Dictionary<string, string> content, string url)
{
//Serialize Object
StringContent jsonContent = SerializeObject(content);

//Execute POST request
HttpResponseMessage response = await Client.PostAsync(url, jsonContent);
}



/// Serialize an object to Json
private StringContent SerializeObject(Dictionary<string, string> content)
{
//Serialize Object
string jsonObject = JsonConvert.SerializeObject(content);

//Create Json UTF8 String Content
return new StringContent(jsonObject, Encoding.UTF8, "application/json");
}

/// Deserialize object from request response
private async Task DeserializeObject(HttpResponseMessage response)
{
//Read body
string responseBody = await response.Content.ReadAsStringAsync();

//Deserialize Body to object
var result = JsonConvert.DeserializeObject(responseBody);
}
}

cancelPreauth

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 error
návratový kód metody a popis chyby:
0 OK
1100 neznámá chyba
1104 nelze načíst platbu
1200 databázová chyba
1301 neznámý e-shop
1303 propojení nebo jazyk chybí
1399 neočekávaný výsledek z databáze
1400 chybný dotaz
1500 neočekávaná chyba
návratový kód metódy a opis chyby:
0 OK
1100 neznáma chyba
1104 nemožno načítať platbu
1200 databázová chyba
1301 neznámy e-shop
1303 prepojenie alebo jazyk chýba
1399 neočakávaný výsledok z databázy
1400 chybná otázka
1500 neočakávaná chyba
message string true none none

cURLPHPJavaPythonC# 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

$headers = array(
'Content-Type' => 'application/x-www-form-urlencoded',
'Accept' => 'application/x-www-form-urlencoded',
);

// Define array of request body.
$request_params = [
"merchant" => "123456",
"transId" => "AB12-CD34-EF56",
"secret" => "gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y",
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://payments.comgate.cz/v1.0/cancelPreauth');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($request_params));
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

try {
$response = curl_exec($ch);

if ($response === false) {
throw new \Exception(curl_error($ch), curl_errno($ch));
}

print_r($response);
} catch (\Exception $e) {
// handle exception or api errors.
print_r($e->getMessage());
} finally {
curl_close($ch);
}

// ...

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)
using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;
using System.Collections.Generic;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
private HttpClient Client { get; set; }

/// <<summary>>
/// Setup http client
/// <</summary>>
public HttpExample()
{
Client = new HttpClient();
}


/// Make a dummy request
public async Task MakePostRequest()
{
string url = "https://payments.comgate.cz/v1.0/cancelPreauth";

var content = new Dictionary<string, string> {
{"merchant", "123456"},
{"transId", "AB12-CD34-EF56"},
{"secret", "gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y"},
};

await PostAsync(content, url);
}

/// Performs a POST Request
public async Task PostAsync(Dictionary<string, string> content, string url)
{
//Serialize Object
StringContent jsonContent = SerializeObject(content);

//Execute POST request
HttpResponseMessage response = await Client.PostAsync(url, jsonContent);
}



/// Serialize an object to Json
private StringContent SerializeObject(Dictionary<string, string> content)
{
//Serialize Object
string jsonObject = JsonConvert.SerializeObject(content);

//Create Json UTF8 String Content
return new StringContent(jsonObject, Encoding.UTF8, "application/json");
}

/// Deserialize object from request response
private async Task DeserializeObject(HttpResponseMessage response)
{
//Read body
string responseBody = await response.Content.ReadAsStringAsync();

//Deserialize Body to object
var result = JsonConvert.DeserializeObject(responseBody);
}
}

methods

POST /v1.0/methods

Obtaining allowed methods
Method for obtaining the settings that the e-shop has enabled in the Comgate 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 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 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 (CZK, EUR, PLN, HUF, USD, GBP, RON, NOK, SEK).Vyplněním parametru na hodnoty CZK nebo EUR dojde k vrácení metod, které podporují zadanou měnu (CZK, EUR, PLN, HUF, USD, GBP, RON, NOK, SEK).Vyplnením parametra na hodnoty CZK alebo EUR dôjde k vráteniu metód, ktoré podporujú zadanú menu (CZK, EUR, PLN, HUF, USD, GBP, RON, NOK, SEK).
country string 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 JSON
vrátí HTTP 200 (OK)!!
struktura vráceného JSONu
vrá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 error
návratový kód metody a popis chyby:
0 OK
1100 neznámá chyba
1200 databázová chyba
1300 e-shop nemá žádnou metodu
1400 chybný dotaz
1500 neočekávaná chyba
návratový kód metódy a opis chyby:
0 OK
1100 neznáma chyba
1200 databázová chyba
1300 e-shop nemá žiadnu metódu
1400 chybná otázka
1500 neočakávaná chyba
» extraMessage string false none specification of the error messageupřesnění chybového hlášeníupresnenie chybového hlásenia

cURLPHPJavaPythonC# 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

$headers = array(
'Content-Type' => 'application/x-www-form-urlencoded',
'Accept' => 'application/json',
);

// Define array of request body.
$request_params = [
"merchant" => "123456",
"secret" => "gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y",
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://payments.comgate.cz/v1.0/methods');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($request_params));
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

try {
$response = curl_exec($ch);

if ($response === false) {
throw new \Exception(curl_error($ch), curl_errno($ch));
}

print_r($response);
} catch (\Exception $e) {
// handle exception or api errors.
print_r($e->getMessage());
} finally {
curl_close($ch);
}

// ...

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)
using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;
using System.Collections.Generic;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
private HttpClient Client { get; set; }

/// <<summary>>
/// Setup http client
/// <</summary>>
public HttpExample()
{
Client = new HttpClient();
}


/// Make a dummy request
public async Task MakePostRequest()
{
string url = "https://payments.comgate.cz/v1.0/methods";

var content = new Dictionary<string, string> {
{"merchant", "123456"},
{"secret", "gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y"},
};

await PostAsync(content, url);
}

/// Performs a POST Request
public async Task PostAsync(Dictionary<string, string> content, string url)
{
//Serialize Object
StringContent jsonContent = SerializeObject(content);

//Execute POST request
HttpResponseMessage response = await Client.PostAsync(url, jsonContent);
}



/// Serialize an object to Json
private StringContent SerializeObject(Dictionary<string, string> content)
{
//Serialize Object
string jsonObject = JsonConvert.SerializeObject(content);

//Create Json UTF8 String Content
return new StringContent(jsonObject, Encoding.UTF8, "application/json");
}

/// Deserialize object from request response
private async Task DeserializeObject(HttpResponseMessage response)
{
//Read body
string responseBody = await response.Content.ReadAsStringAsync();

//Deserialize Body to object
var result = JsonConvert.DeserializeObject(responseBody);
}
}

status

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 response
popis chyby v závislosti na návratovém kódu:
0 OK
1100 neznámá chyba
1200 databázová chyba
1400 chybný dotaz
1500 neočekávaná chyba

v případě code=0 jsou v odpovědi následující parametry:
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 will transfer the moneyidentifikátor bankovního účtu e-shopu, na který Comgate převede penízeidentifikátor bankového účtu e-shopu, na ktorý Comgate prevedie peniaze
email 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 successful
aktuální stav transakce, hodnoty
‘PENDING’ – platba je založena, finální výsledek není známý
‘PAID’ – platba byla úspěšně zaplacena
‘CANCELLED’ – platba nebyla dokončena korektně a je zrušena
‘AUTHORIZED’ – vyžádaná předautorizace proběhla úspěšně
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’
vs string false none variable payment symbol (may not always be available)variabilní symbol platby (nemusí být vždy dostupné)variabilný symbol platby (nie je vždy k dispozícii)

cURLPHPJavaPythonC# 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

$headers = array(
'Content-Type' => 'application/x-www-form-urlencoded',
'Accept' => 'application/x-www-form-urlencoded',
);

// Define array of request body.
$request_params = [
"merchant" => "123456",
"transId" => "AB12-CD34-EF56",
"secret" => "gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y",
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://payments.comgate.cz/v1.0/status');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($request_params));
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

try {
$response = curl_exec($ch);

if ($response === false) {
throw new \Exception(curl_error($ch), curl_errno($ch));
}

print_r($response);
} catch (\Exception $e) {
// handle exception or api errors.
print_r($e->getMessage());
} finally {
curl_close($ch);
}

// ...

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)
using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;
using System.Collections.Generic;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
private HttpClient Client { get; set; }

/// <<summary>>
/// Setup http client
/// <</summary>>
public HttpExample()
{
Client = new HttpClient();
}


/// Make a dummy request
public async Task MakePostRequest()
{
string url = "https://payments.comgate.cz/v1.0/status";

var content = new Dictionary<string, string> {
{"merchant", "123456"},
{"transId", "AB12-CD34-EF56"},
{"secret", "gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y"},
};

await PostAsync(content, url);
}

/// Performs a POST Request
public async Task PostAsync(Dictionary<string, string> content, string url)
{
//Serialize Object
StringContent jsonContent = SerializeObject(content);

//Execute POST request
HttpResponseMessage response = await Client.PostAsync(url, jsonContent);
}



/// Serialize an object to Json
private StringContent SerializeObject(Dictionary<string, string> content)
{
//Serialize Object
string jsonObject = JsonConvert.SerializeObject(content);

//Create Json UTF8 String Content
return new StringContent(jsonObject, Encoding.UTF8, "application/json");
}

/// Deserialize object from request response
private async Task DeserializeObject(HttpResponseMessage response)
{
//Read body
string responseBody = await response.Content.ReadAsStringAsync();

//Deserialize Body to object
var result = JsonConvert.DeserializeObject(responseBody);
}
}

TAG_api_for_downloading_files

transferList

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

cURLPHPJavaPythonC# 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

$headers = array(
'Content-Type' => 'application/x-www-form-urlencoded',
'Accept' => 'application/json',
);

// Define array of request body.
$request_params = [
"merchant" => "123456",
"secret" => "gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y",
"date" => "2023-03-22",
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://payments.comgate.cz/v1.0/transferList');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($request_params));
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

try {
$response = curl_exec($ch);

if ($response === false) {
throw new \Exception(curl_error($ch), curl_errno($ch));
}

print_r($response);
} catch (\Exception $e) {
// handle exception or api errors.
print_r($e->getMessage());
} finally {
curl_close($ch);
}

// ...

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)
using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;
using System.Collections.Generic;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
private HttpClient Client { get; set; }

/// <<summary>>
/// Setup http client
/// <</summary>>
public HttpExample()
{
Client = new HttpClient();
}


/// Make a dummy request
public async Task MakePostRequest()
{
string url = "https://payments.comgate.cz/v1.0/transferList";

var content = new Dictionary<string, string> {
{"merchant", "123456"},
{"secret", "gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y"},
{"date", "2023-03-22"},
};

await PostAsync(content, url);
}

/// Performs a POST Request
public async Task PostAsync(Dictionary<string, string> content, string url)
{
//Serialize Object
StringContent jsonContent = SerializeObject(content);

//Execute POST request
HttpResponseMessage response = await Client.PostAsync(url, jsonContent);
}



/// Serialize an object to Json
private StringContent SerializeObject(Dictionary<string, string> content)
{
//Serialize Object
string jsonObject = JsonConvert.SerializeObject(content);

//Create Json UTF8 String Content
return new StringContent(jsonObject, Encoding.UTF8, "application/json");
}

/// Deserialize object from request response
private async Task DeserializeObject(HttpResponseMessage response)
{
//Read body
string responseBody = await response.Content.ReadAsStringAsync();

//Deserialize Body to object
var result = JsonConvert.DeserializeObject(responseBody);
}
}

singleTransfer

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

cURLPHPJavaPythonC# 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

$headers = array(
'Content-Type' => 'application/x-www-form-urlencoded',
'Accept' => 'application/json',
);

// Define array of request body.
$request_params = [
"merchant" => "123456",
"secret" => "gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y",
"transferId" => "1234567",
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://payments.comgate.cz/v1.0/singleTransfer');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($request_params));
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

try {
$response = curl_exec($ch);

if ($response === false) {
throw new \Exception(curl_error($ch), curl_errno($ch));
}

print_r($response);
} catch (\Exception $e) {
// handle exception or api errors.
print_r($e->getMessage());
} finally {
curl_close($ch);
}

// ...

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)
using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;
using System.Collections.Generic;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
private HttpClient Client { get; set; }

/// <<summary>>
/// Setup http client
/// <</summary>>
public HttpExample()
{
Client = new HttpClient();
}


/// Make a dummy request
public async Task MakePostRequest()
{
string url = "https://payments.comgate.cz/v1.0/singleTransfer";

var content = new Dictionary<string, string> {
{"merchant", "123456"},
{"secret", "gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y"},
{"transferId", "1234567"},
};

await PostAsync(content, url);
}

/// Performs a POST Request
public async Task PostAsync(Dictionary<string, string> content, string url)
{
//Serialize Object
StringContent jsonContent = SerializeObject(content);

//Execute POST request
HttpResponseMessage response = await Client.PostAsync(url, jsonContent);
}



/// Serialize an object to Json
private StringContent SerializeObject(Dictionary<string, string> content)
{
//Serialize Object
string jsonObject = JsonConvert.SerializeObject(content);

//Create Json UTF8 String Content
return new StringContent(jsonObject, Encoding.UTF8, "application/json");
}

/// Deserialize object from request response
private async Task DeserializeObject(HttpResponseMessage response)
{
//Read body
string responseBody = await response.Content.ReadAsStringAsync();

//Deserialize Body to object
var result = JsonConvert.DeserializeObject(responseBody);
}
}

csvSingleTransfer

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

cURLPHPJavaPythonC# 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

$headers = array(
'Content-Type' => 'application/x-www-form-urlencoded',
'Accept' => 'application/json',
);

// Define array of request body.
$request_params = [
"merchant" => "123456",
"secret" => "gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y",
"transferId" => "5217530",
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://payments.comgate.cz/v1.0/csvSingleTransfer');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($request_params));
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

try {
$response = curl_exec($ch);

if ($response === false) {
throw new \Exception(curl_error($ch), curl_errno($ch));
}

print_r($response);
} catch (\Exception $e) {
// handle exception or api errors.
print_r($e->getMessage());
} finally {
curl_close($ch);
}

// ...

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)
using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;
using System.Collections.Generic;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
private HttpClient Client { get; set; }

/// <<summary>>
/// Setup http client
/// <</summary>>
public HttpExample()
{
Client = new HttpClient();
}


/// Make a dummy request
public async Task MakePostRequest()
{
string url = "https://payments.comgate.cz/v1.0/csvSingleTransfer";

var content = new Dictionary<string, string> {
{"merchant", "123456"},
{"secret", "gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y"},
{"transferId", "5217530"},
};

await PostAsync(content, url);
}

/// Performs a POST Request
public async Task PostAsync(Dictionary<string, string> content, string url)
{
//Serialize Object
StringContent jsonContent = SerializeObject(content);

//Execute POST request
HttpResponseMessage response = await Client.PostAsync(url, jsonContent);
}



/// Serialize an object to Json
private StringContent SerializeObject(Dictionary<string, string> content)
{
//Serialize Object
string jsonObject = JsonConvert.SerializeObject(content);

//Create Json UTF8 String Content
return new StringContent(jsonObject, Encoding.UTF8, "application/json");
}

/// Deserialize object from request response
private async Task DeserializeObject(HttpResponseMessage response)
{
//Read body
string responseBody = await response.Content.ReadAsStringAsync();

//Deserialize Body to object
var result = JsonConvert.DeserializeObject(responseBody);
}
}

aboSingleTransfer

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

cURLPHPJavaPythonC# 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

$headers = array(
'Content-Type' => 'application/x-www-form-urlencoded',
'Accept' => 'application/json',
);

// Define array of request body.
$request_params = [
"merchant" => "123456",
"secret" => "gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y",
"transferId" => "transfer_id",
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://payments.comgate.cz/v1.0/aboSingleTransfer');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($request_params));
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

try {
$response = curl_exec($ch);

if ($response === false) {
throw new \Exception(curl_error($ch), curl_errno($ch));
}

print_r($response);
} catch (\Exception $e) {
// handle exception or api errors.
print_r($e->getMessage());
} finally {
curl_close($ch);
}

// ...

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)
using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;
using System.Collections.Generic;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
private HttpClient Client { get; set; }

/// <<summary>>
/// Setup http client
/// <</summary>>
public HttpExample()
{
Client = new HttpClient();
}


/// Make a dummy request
public async Task MakePostRequest()
{
string url = "https://payments.comgate.cz/v1.0/aboSingleTransfer";

var content = new Dictionary<string, string> {
{"merchant", "123456"},
{"secret", "gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y"},
{"transferId", "transfer_id"},
};

await PostAsync(content, url);
}

/// Performs a POST Request
public async Task PostAsync(Dictionary<string, string> content, string url)
{
//Serialize Object
StringContent jsonContent = SerializeObject(content);

//Execute POST request
HttpResponseMessage response = await Client.PostAsync(url, jsonContent);
}



/// Serialize an object to Json
private StringContent SerializeObject(Dictionary<string, string> content)
{
//Serialize Object
string jsonObject = JsonConvert.SerializeObject(content);

//Create Json UTF8 String Content
return new StringContent(jsonObject, Encoding.UTF8, "application/json");
}

/// Deserialize object from request response
private async Task DeserializeObject(HttpResponseMessage response)
{
//Read body
string responseBody = await response.Content.ReadAsStringAsync();

//Deserialize Body to object
var result = JsonConvert.DeserializeObject(responseBody);
}
}

csvDownload

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

cURLPHPJavaPythonC# 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

$headers = array(
'Content-Type' => 'application/x-www-form-urlencoded',
'Accept' => 'application/zip',
);

// Define array of request body.
$request_params = [
"merchant" => "123456",
"secret" => "gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y",
"date" => "YYYY-MM-DD",
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://payments.comgate.cz/v1.0/csvDownload');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($request_params));
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

try {
$response = curl_exec($ch);

if ($response === false) {
throw new \Exception(curl_error($ch), curl_errno($ch));
}

print_r($response);
} catch (\Exception $e) {
// handle exception or api errors.
print_r($e->getMessage());
} finally {
curl_close($ch);
}

// ...

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)
using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;
using System.Collections.Generic;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
private HttpClient Client { get; set; }

/// <<summary>>
/// Setup http client
/// <</summary>>
public HttpExample()
{
Client = new HttpClient();
}


/// Make a dummy request
public async Task MakePostRequest()
{
string url = "https://payments.comgate.cz/v1.0/csvDownload";

var content = new Dictionary<string, string> {
{"merchant", "123456"},
{"secret", "gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y"},
{"date", "YYYY-MM-DD"},
};

await PostAsync(content, url);
}

/// Performs a POST Request
public async Task PostAsync(Dictionary<string, string> content, string url)
{
//Serialize Object
StringContent jsonContent = SerializeObject(content);

//Execute POST request
HttpResponseMessage response = await Client.PostAsync(url, jsonContent);
}



/// Serialize an object to Json
private StringContent SerializeObject(Dictionary<string, string> content)
{
//Serialize Object
string jsonObject = JsonConvert.SerializeObject(content);

//Create Json UTF8 String Content
return new StringContent(jsonObject, Encoding.UTF8, "application/json");
}

/// Deserialize object from request response
private async Task DeserializeObject(HttpResponseMessage response)
{
//Read body
string responseBody = await response.Content.ReadAsStringAsync();

//Deserialize Body to object
var result = JsonConvert.DeserializeObject(responseBody);
}
}

aboDownload

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

cURLPHPJavaPythonC# 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

$headers = array(
'Content-Type' => 'application/x-www-form-urlencoded',
'Accept' => 'application/zip',
);

// Define array of request body.
$request_params = [
"merchant" => "123456",
"secret" => "gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y",
"date" => "YYYY-MM-DD",
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://payments.comgate.cz/v1.0/aboDownload');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($request_params));
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

try {
$response = curl_exec($ch);

if ($response === false) {
throw new \Exception(curl_error($ch), curl_errno($ch));
}

print_r($response);
} catch (\Exception $e) {
// handle exception or api errors.
print_r($e->getMessage());
} finally {
curl_close($ch);
}

// ...

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)
using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;
using System.Collections.Generic;

/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
private HttpClient Client { get; set; }

/// <<summary>>
/// Setup http client
/// <</summary>>
public HttpExample()
{
Client = new HttpClient();
}


/// Make a dummy request
public async Task MakePostRequest()
{
string url = "https://payments.comgate.cz/v1.0/aboDownload";

var content = new Dictionary<string, string> {
{"merchant", "123456"},
{"secret", "gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y"},
{"date", "YYYY-MM-DD"},
};

await PostAsync(content, url);
}

/// Performs a POST Request
public async Task PostAsync(Dictionary<string, string> content, string url)
{
//Serialize Object
StringContent jsonContent = SerializeObject(content);

//Execute POST request
HttpResponseMessage response = await Client.PostAsync(url, jsonContent);
}



/// Serialize an object to Json
private StringContent SerializeObject(Dictionary<string, string> content)
{
//Serialize Object
string jsonObject = JsonConvert.SerializeObject(content);

//Create Json UTF8 String Content
return new StringContent(jsonObject, Encoding.UTF8, "application/json");
}

/// Deserialize object from request response
private async Task DeserializeObject(HttpResponseMessage response)
{
//Read body
string responseBody = await response.Content.ReadAsStringAsync();

//Deserialize Body to object
var result = JsonConvert.DeserializeObject(responseBody);
}
}

Checkout SDK

Comgate Checkout SDK je JavaScriptová knihovna, která usnadňuje implementaci Comgate platebních metod, včetně Apple Pay a Google Pay, přímo do košíku internetového obchodu.

Funkce

Připravujeme

Kompatibilita

Funkce Podporované metody
Apple Pay CARD_CZ_COMGATE, CARD_CZ_CSOB_2
Google Pay CARD_CZ_COMGATE, CARD_CZ_CSOB_2
Click To Pay CARD_CZ_COMGATE
Platba kartou přímo v košíku CARD_CZ_COMGATE
Automatický rozcestník libovolná konfigurace metod

Tutorial - postup implementace

Krok 1: Vytvoření a konfigurace propojení obchodu v klientském portálu

Doporučujeme vytvořit nové propojení obchodu a používat jej výhradně pro platby zpracovávané prostřednictvím Comgate Checkout SDK.

UPOZORNĚNÍ

Pro zpracování platby prostřednictvím Checkout SDK musí být použity údaje (Identifikátor Checkout SDK, např. 2042b190-0c31-4b34-8ce4-xxxxxxxxxxxx) ze stejného propojení obchodu, jakým byla platba založena v systému Comgate.

Zobrazení seznamu propojení obchodu

  1. v klientském portálu vyberte v horním menu Integrace -> Nastevní obchodu a zvolte váš obchod
  2. pod nadpisem stránky vyberte záložku Propojení obchodu

Vytvoření nového propojení obchodu

Aktivace Checkout SDK na propojení obchodu

  1. vyberte Upravit propojení obchodu (symbol tužky vpravo)
  2. Zaklikněte Povolit Checkout SDK
  3. zaklikněte Apple Pay, pokud ho plánujete používat
  4. zaklikněte Google Pay, pokud ho plánujete používat
  5. klikněte na tlačítko Uložit
  6. vyčkejte na uložení a zobrazení seznamu propojení obchodu
  7. zobrazte detail uloženého propojení (symbol oka vpravo)
  8. poznamenejte si hodnotu Identifikátor Checkout SDK, bude potřeba níže

Detail propojení obchodu by následně měl obsahovat i tyto informace:

alt text

Krok 2: Příprava domény pro Checkout SDK (pouze Apple Pay a Google Pay)

INFORMACE

Tento krok je nepovinný a je vyžadován pouze v případě, že bude docházet k implementaci Google Pay nebo Apple Pay.

A) Ověření domény pro Apple Pay

K ověření domény pro Apple pay je potřeba stáhnout speciální verifikační soubor, zpřístupnit ho na konkrétní URL a na samotný závěr zkontrolovat správné náhrání onoho staženého souboru. Tím dojde k zahájení procesu automatické zaregistrace domény v Apple.

Před tím, než dojde k nahrání souboru na vaši doménu je potřeba rozhodnout, jakou metodou se budou zpracovávat karetní transakce. Pro Apple Pay poskytujeme 2 podporované metody: CARD_CZ_CSOB_2 a CARD_CZ_COMGATE. Tuto informaci je možné zjistit v Klientském portálu na stránce Nastavení obchodu v záložce Platební metody. V seznamu Povolené platební metody zkuste vyhledat všechny metody začínající na CARD_ a měla by být vždy zobrazena maximálně jedna z podporovaných. Pokud jich je zobrazeno více, použije se první dle tohoto pořadí: CSOB, COMGATE. Pokud ovšem narazíte pouze na CARD_CZ_BS a přesto chcete používat Google Pay a Apple Pay v košíku e-shopu, je nutné zvážit migraci na jednu z podporovaných karetních metod.

Pro metodu CARD_CZ_CSOB_2 stáhněte soubor:
https://payments.comgate.cz/data/apple-pay/csob/apple-developer-merchantid-domain-association

Pro metodu CARD_CZ_COMGATE stáhněte soubor:
https://payments.comgate.cz/data/apple-pay/comgate/apple-developer-merchantid-domain-association

Stažený soubor je potřeba zpřístupnit na adrese: https://www.vas-web.cz/.well-known/apple-developer-merchantid-domain-association.

Správné nahrání souboru je nutné si ověřit v Klientském portálu na detailu propojení obchodu, a to kliknutím na tlačítko “Zkontrolovat pro NAZEV_METODY”. Ve chvíli, kdy dojde k zobrazení zelené potvrzovací hlášky, zadá se do našeho systému požadavek o registraci vaší domény v Apple. Zpracování probíhá zcela automaticky a je zpravidla dokončeno do 10 minut. V ojedinělých případech může trvat i několik hodin. Vyčkejte až 24 hodin a stav znovu zkontrolujte (je dostupný na detailu propojení obchodu).

INFORMACE

Soubor apple-developer-merchantid-domain-association musí na doméně zůstat po celou dobu používání Apple Pay v košíku e-shopu. Při každé platbě si servery Apple sahají pro obsah souboru a validují ho.

Společnost Apple vyžaduje dodržování pravidel pro použití tlačítka Apple Pay na vašem e-shopu. Pravidla lze nalézt na adrese: https://developer.apple.com/design/human-interface-guidelines/apple-pay/#Using-Apple-Pay-buttons

Při nedodržení těchto pravidel může být přístup k funkcím Comgate Checkout SDK - Apple Pay pozastaven, a to až do opravy použití v souladu s pravidly společnosti Apple.

Možné stavy registrace
Stav Popis
Povoleno registrace úspěšně provedena a funkce je zapnuta
Zakázáno funkce je vypnuta
(čeká na registraci) čeká na vyřízení, bude provedeno
(čeká na přeregistraci) čeká na vyřízení, bude provedeno
(zakázáno pro celý obchod) Apple Pay je zakázáno pro celý obchod, detaily se dozvíte na zákaznické podpoře
(chyba registrace) při registraci vznikla chyba (Zkuste Apple Pay deaktivovat, změnu uložit a následně opět znovu aktivovat a uložit. Pokud tento postup nepomůže a žádost o (pře)registraci nebude zadána, kontaktujte zákaznickou podporu.)

B) Ověření domény pro Google Pay

Registraci vaší domény v Google Pay provádíme ručně. Ve chvíli, kdy aktivujete Google Pay pro Checkout SDK, budete vyzvání k zaslání screenshotů použití tlačítka Google Pay ve vašem e-shopu (viz informace níže) na adresu podpora@comgate.cz. Pokud již byla doména jednou zaregistrována s předchozím propojením, tak s vytvořením nového propojení obchodu již není potřeba tuto doménu znovu registrovat.

UPOZORNĚNÍ

Pokud dojde k odstranění posledního propojení obchodu, u kterého bylo Google Pay pro Checkout SDK povoleno a je potřeba vytvořit nové propojení obchodu s aktivním Google Pay pro Checkout SDK, je potřeba kontaktovat zákaznickou podporu Comgate, která ověří, že je doména skutečně v Google Pay registrována a v návaznosti na to znovu aktivuje Google Pay pro Checkout SDK v novém propojení obchodu.

Pokud se chcete této komplikaci vyvarovat, založte nové propojení a aktivujte na něm Checkout SDK společně s Google Pay dříve, než odstraníte poslední propojení s aktivním Google Pay pro Checkout SDK.

Do e-mailu prosím napište informaci, že se jedná o aktivaci Google Pay pro Checkout SDK a uveďte CELOU URL obchodu, pro který chcete registraci provést.

Tyto obrázky vyžaduje společnost Google při registraci samotné domény. Registrace ze strany Google trvá několik dnů. V některých případech se může protáhnout i na několik týdnů.

V budoucnu plánujeme proces automatizovat.

POSTUPUJTE PEČLIVĚ

Prosíme, připravte si sadu 5 obrázků, které budou ukazovat použití Google Pay tlačítka ve vašem webu.

Pro hladké schválení ze strany společnosti Google je potřeba dodržet všechny požadavky, které jsou dostupné na adrese: https://developers.google.com/pay/api/web/guides/brand-guidelines.

Připravte si prosím tyto obrázky (doporučujeme pořídit z počítače):

  1. výběr produktu (když uživatel prohlíží produkt nebo službu),
  2. obrazovka před nákupem (když je uživatel připraven provést nákup),
  3. obrazovka platební metody (když uživatel vybere jako platební metodu Google Pay),
  4. obrazovka platby Google Pay (když se uživateli zobrazí platební údaje, které si uložil do Google Pay
    Tip: Android vám nedovolí pořídit snímek obrazovky této obrazovky, takže vyfoťte obrazovku pomocí jiného zařízení.
    ),
  5. obrazovka po nákupu (když uživatel provedl úspěšný nákup)
Více na: https://developers.google.com/pay/api/web/guides/brand-guidelines#put-it-all-together

Každý screenshot může mít maximálně 1MB. Stejný screenshot se může v některých případech použít pro více kategorií.

Obrázek tlačítka pro případné zakomponování do stránky (pomocí GIMP/Photoshop) lze vygenerovat na adrese: https://developers.google.com/pay/api/web/guides/resources/customize

Při nedodržení těchto pravidel může být přístup k funkcím Comgate Checkout SDK - Google Pay pozastaven, a to až do opravy použití v souladu s pravidly společnosti Google.

Možné stavy registrace
Stav Popis
Povoleno registrace úspěšně provedena a funkce je zapnuta
Zakázáno funkce je vypnuta
(čeká na obrázky pro registraci) čeká na dodání obrázků pro registraci domény
(čeká na registraci) čeká na vyřízení, bude provedeno
(čeká na potvrzení registrace v Google) čeká na schválení společností Google
(zakázáno pro celý obchod) Google Pay je zakázáno pro celý obchod, detaily se dozvíte na zákaznické podpoře
(chyba registrace) při registraci vznikla chyba, detaily se dozvíte na zákaznické podpoře

Krok 3: Příprava vývojového prostředí na localhostu

INFORMACE

Tento krok je nepovinný a není potřeba ke správnému fungování Checkout SDK na produkci. Při vývoji na localhostu bez tohoto kroku není možné spustit platební rozhraní služeb Apple Pay a Google Pay a otestovat si celý proces placení - a to ani pro testovací platby. Samotná tlačítka budou na webu zobrazena vždy.

Pokud chcete při vývoji funkce lokálně testovat, je potřeba upravit soubor hosts ve vašem operačním systému. Vývoj přes adresu localhost nebo přímo přes IP adresu není možný pro testování Apple Pay a Google Pay. Na localhostu dojde pouze k zobrazení tlačítek obou služeb.

V klientském portálu si prosím zjistěte, jakého providera používáte pro zpracování karetních transakcí. Podporované hodnoty jsou CARD_CZ_CSOB_2 a CARD_CZ_COMGATE. V případě, že používáte CARD_CZ_COMGATE, tak jsou příklady konfigurace pro hosts soubor shodné a není třeba je měnit. Pokud však používáte CARD_CZ_CSOB_2, tak je potřeba v souboru hosts použít doménu checkout2.comgate.dev.

Nakonfigurujte váš vývojový server (nginx, Apache, …), tak aby aby vašemu projektu přiřadil doménu ‘checkout1.comgate.dev’ a upravte hosts soubor, aby tato doména odkazovala na váš vývojový stroj.

Linux - změna hosts souboru

Mac - změna hosts souboru

Windows - změna hosts souboru

Nyní by měla adresa https://checkout1.comgate.dev/ odkazovat na váš vývojový stroj. Apply Pay a Google Pay by měly být připraveny k testování.

Krok 4: Vložení Checkout SDK do zdrojového kódu obchodu

Vložte následující JavaScript soubor do své stránky. Vhodné umístění je na před koncem prvku HEAD.

<!-- Comgate Checkout SDK version 1.x.y -->
<script src="https://static.comgate.cz/checkout/@1" async></script>

[Kód na GitHubu]

Tento kód zajistí načtení nejnovější verze naší Checkout SDK. Nemusíte se obávat, všechny majoritní verze 1 budou zpětně kompatibilní. V případě, že byste chtěli trvale používat konkrétní verzi, můžete použít její celý název, který získáte po přístupu na adresu https://static.comgate.cz/checkout/@1. Tento postup ale není doporučen, neboť byste se připravili o průběžně dodávané kompatibilní opravy a aktualizace.

INFORMACE

Lze také použít defer místo async: <script src="..." defer></script>. Je však potřeba správně rozhodnout (viz přiložený odkaz níže), která z možností je nejvíce vyhovující vašim požadavkům.

Jak správně vložit skript do stránky

Krok 5: Získání konfiguračních parametrů pro Checkout SDK

Veškeré konfigurační údaje pro vytvoření první instance Checkout SDK lze získat z klientského portálu z detailu propojení obchodu, které bylo pro tento účel nakonfigurováno v prvním kroce.

V současné době je ‘Identifikátor Checkout SDK’ jediný parametr jehož hodnotu potřebujete v Klientském portále získat. Slouží jako statický parametr pro inicializaci instance třídy ComgateCheckout. Parametr se v kódu jmenuje checkoutId.

Více informací o parametrech v sekci Definice API komponent.

Krok 6: Volba vhodného přístupu implementace

V současné době existují dva možné přístupy k implementaci Checkout SDK do košíku e-shopu:

A) Zpracování předem založené platby

Jedná se o základní a nejjednodušší implementační přístup. Na stránce není nutné provádět žádné složitější akce.

INFORMACE

Při vytváření instance třídy ComgateCheckout je nutné znát Comgate ID transakce. To znamená, pokud se zákazník rozhodne změnit například způsob dopravy, tak je potřeba založit novou platbu s aktualizovanou cenou a následně přenačíst celou stránku.

Comgate ID transakce je do stránky možné vložit například při generování kódu na straně serveru.

Pokud je zvolen tento přístup, pokračujte krokem 7 A.

B) Dynamické založení a zpracování platby

Tento přístup umožňuje dosáhnout více dynamického chování vaší stránky.

INFORMACE

Při vytváření instance třídy ComgateCheckout není nutné znát Comgate ID transakce. To znamená, pokud se zákazník rozhodne bezprostředně před zaplacením změnit například způsob dopravy, není to žádný problém. K založení samotné platby dojde až na samotný závěr, kdy klikne na tlačítko k provedení platby a potvrdí, že je již s parametry objednávky plně spokojen. Nemusí tak dojít ke zbytečnému přenačtení celé stránku.

Tento náročnější přístup vyžaduje implementaci části funkcionality jak na frontendu (strana prohlížeče), tak na backendu (strana serveru). Umožňuje však dosáhnout dynamičtějšího chování stránky při zpracování plateb.

Pokud je zvolen tento přístup, pokračujte krokem 7 B.

Detailní scénář zpracování platby

Když jsou zobrazena tlačítka Apple Pay a Google Pay není nutné mít založenou platbu v systému Comgate. Ve chvíli, kdy chce plátce zaplatit a klikne na libovolné tlačítko, dojde k ověření, zda již bylo specifikováno Comgate ID platby, či nikoliv. V případě že ano a ID je stále validní, tak placení probíhá automaticky dále.

V situaci, kdy nebylo ID platby specifikováno nebo již není validní (invalidatePayment()), tak dojde k volání callbacku onRequirePayment(...). V tomto callbacku je nutné odeslat request na váš server (backend), kde dojde k založení platby v systému Comgate pomocí tajných přihlašovacích údajů z propojení obchodu. Pro snadné odesílání requestů jsme v Comgate Checkout SDK připravili pomocnou metodu eshopRequest(...). Po založení platby by mělo být ID transakce vráceno zpět klientovi, který ho předepsaným způsobem předá ComgateCheckout instanci a ta pokračuje ve zpracování platby.

V případě, že plátce platbu v průběhu zastaví, a vrátí se do dynamického košíku, je možné již dříve dodané ID transakce zneplatnit voláním metody invalidatePayment(). Proces se zakládáním nové platby se tak opakuje. V opačném případě je použito ID transakce z předchozího pokusu.

Krok 7: Vytvoření instance Comgate Checkout SDK

Pro použití ComgateCheckout funkcí (např. Apple Pay, Google Pay) je nutné vytvořit instanci této třídy s konfiguračními parametry. Tato instance se následně stává centrálním bodem pro ovládání celé funkcionality.

UPOZORNĚNÍ

V současné chvíli je možné na stránce používat pouze jednu instanci třídy ComgateCheckout. Při vytvoření druhé instance může dojít k neočekávanému chování aplikace.

A) Zpracování předem založené platby [Kód na GitHubu]

<script>
// počkat na načtení Comgate Checkout SDK
document.addEventListener("ComgateCheckoutReady", function () {
// vytvoření ComgateCheckout instance
window
.ComgateCheckout({
checkoutId: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", // (povinné) získáno v kroku 5
locale: "cs", // (volitelné, výchozí: cs) jazyk rozhraní
debug: true, // (volitelné, výchozí: false) detailní vývojové informace do konzole !!! NEPOUŽÍVAT 'true' NA PRODUKCI !!!

// v seznamu uvádějte pouze služby, které chcete opravdu používat
prefetch: ['googlepay'] // (volitelné) přednačíst script pro GooglePay (ApplePay je vždy přednačteno)

transactionId: "XXXX-XXXX-XXXX", // (povinné) Comgate ID transakce získané po volání /v1.0/create

onPaid: (payload) => { // (povinné) platba byla zaplacena
/* TODO DIY */
},
onCancelled: (payload) => { // (povinné) platba byla zrušena, nebo expirovala
/* TODO DIY */
},
onPending: (payload) => { // (volitelné) v případě, že se pokus o platbu nezdařil, platba může pokračovat
/* TODO DIY nebo nedefinovat */
// pokud není vykonána žádná akce, tak je vhodné callback nedefinovat
},
onClick: (payload) => { // (volitelné) voláno po kliknutí na tlačítko, před zahájením zpracování platby [vyžadováno potvrzení]
/* TODO DIY nebo nedefinovat */
// pokud není vykonána žádná akce, tak je vhodné callback nedefinovat

// na konci definovaného callbacku je nutné zavolat
// payload.resolve() - pokračovat v platbě
// payload.reject() - zrušit akci a nepokračovat
// jinak dojde k uváznutí čekání
if ("resolve" in payload) {
payload.resolve();
}
},
onError: (payload) => { // (povinné) detaily o chybě v průběhu zpracování
/* TODO DIY */
// Podstatná část zpracování platby probíhá asynchronně a proto ji nelze navázat na standardní try-catch blok.
// v případě, že dojde k volání tohoto callbacku, platba již nepokračuje, Comgate ID transakce je možné využít znovu
// většina chyb je automaticky reportována společnosti Comgate pro jejich lazeních a případnou opravu
// chyby vzniklé nesprávnou implementací developera opraveny nebudou
}
})
.then((checkoutInstance) => {
// ComgateCheckout instance připravena pro konfiguraci konkrétních služeb
/* TODO DIY implementace vybraných funkcionalit */
})
.catch((error) => {
/* TODO DIY */
// při vytváření instance ComgateCheckout došlo k neočekávané chybě a platby nemohou být zprocesovány
// tyto chyby nejsou společností Comgate automatizovaně zaznamenávány a vznikají převážně nesprávnou implemtnací ComgateCheckout SDK
console.error("ComgateCheckout Init ERROR: ", error);
});
});
</script>

B) Dynamické založení a zpracování platby [Kód na GitHubu]

<script>
// počkat na načtení Comgate Checkout SDK
document.addEventListener("ComgateCheckoutReady", function () {
// proměnná pro referenci na instanci ComgateCheckout
let checkoutInstanceRef = null;

// vytvoření ComgateCheckout instance
window
.ComgateCheckout({
checkoutId: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", // (povinné) získáno v kroku 5
locale: "cs", // (volitelné, výchozí: cs) jazyk rozhraní
debug: true, // (volitelné, výchozí: false) detailní vývojové informace do konzole !!! NEPOUŽÍVAT 'true' NA PRODUKCI !!!

// v seznamu uvádějte pouze služby, které chcete opravdu používat
prefetch: ['googlepay'] // (volitelné) přednačíst script pro GooglePay (ApplePay je vždy přednačteno)

onRequirePayment: (payload) => { // (povinné) je vyžádáno založení a dodání Comgate ID transakce
/* TODO DIY */
// při volání callbacku je potřeba provolat API e-shopu a založit novou platbu a vrátit Comgate ID transakce
// věškeré údaje o ceně, měně a dalších parametrech je bezpečné načítat na straně serveru a nezasílat si je ve volání zde,
// mohlo by totiž dojít k jejich podvržení.
// lze využít pomocnou metodu dodanou v payload pro odesílání requestů na váš server payload.eshopRequest(/*...*/)
// nebo pomocí uložení ComgateCheckout instance do proměnné checkoutInstance.eshopRequest(/*...*/)
},
onPaid: (payload) => { // (povinné) platba byla zaplacena
/* TODO DIY */
},
onCancelled: (payload) => { // (povinné) platba byla zrušena, nebo expirovala
/* TODO DIY */
},
onPending: (payload) => { // (volitelné) v případě, že se pokus o platbu nezdařil, platba může pokračovat
/* TODO DIY nebo nedefinovat */
// pokud není vykonána žádná akce, tak je vhodné callback nedefinovat
},
onClick: (payload) => { // (volitelné) voláno po kliknutí na tlačítko, před zahájením zpracování platby [vyžadováno potvrzení]
/* TODO DIY nebo nedefinovat */
// pokud není vykonána žádná akce, tak je vhodné callback nedefinovat

// na konci definovaného callbacku je nutné zavolat
// payload.resolve() - pokračovat v platbě
// payload.reject() - zrušit akci a nepokračovat
// jinak dojde k uváznutí čekání
payload.resolve();
},
onError: (payload) => { // (povinné) detaily o chybě v průběhu zpracování
/* TODO DIY */
// Podstatná část zpracování platby probíhá asynchronně a proto ji nelze navázat na standardní try-catch blok.
// v případě, že dojde k volání tohoto callbacku, platba již nepokračuje, Comgate ID transakce je možné využít znovu
// většina chyb je automaticky reportována společnosti Comgate pro jejich lazeních a případnou opravu
// chyby vzniklé nesprávnou implementací developera opraveny nebudou
}
})
.then((checkoutInstance) => {
checkoutInstanceRef = checkoutInstance;
// ComgateCheckout instance připravena pro konfiguraci konkrétních služeb
/* TODO DIY implementace vybraných funkcionalit */
})
.catch((error) => {
/* TODO DIY */
// při vytváření instance ComgateCheckout došlo k neočekávané chybě a platby nemohou být zprocesovány
// tyto chyby nejsou společností Comgate automatizovaně zaznamenávány a vznikají převážně nesprávnou implemtnací ComgateCheckout SDK
console.error("ComgateCheckout Init ERROR: ", error);
});
});
</script>

Krok 8: Nastavení zvolené funkcionality

Ve chvíli, kdy je vytvořena instance třídy ComgateCheckout, je možné prostřednictvím jejich připravených metod začít sestavovat konkrétní potřebnou funkcionalitu.

Návod implementace vybrané funkcionality je dostupný níže:

Implementace konkrétní funkcionality

V následující sekci je popsána implementace konkrétních funkcionalit, které jsou dostupné v Checkout SDK.

Implementace Apple Pay

Nejvhodnějším způsobem, jak implementovat Apple Pay tlačítko je vytvoření funkce, která bude jako parametr přijímat referenci na instanci třídy ComgateCheckout a celá další logika se odehraje v této funkci.

V bloku then(...) vytváření instance ComgateCheckout dojde k volání této definované funkce: demo_createApplePay(checkoutInstance);

Ukázkový kód [Kód na GitHubu]

/**
* Create Apple Pay button
* @param {ComgateCheckout} checkoutInstance instance Comgate checkout
*/

function demo_createApplePay(checkoutInstance) {
checkoutInstance
.createApplePay({ // alternativní funkční zápis metody createApplePay({}), createApplePay()
// kompletní seznam parametrů je dostupný níže
style: {
// hodnoty dle dokumentace Apple Pay
style: "black", // (volitelné, výchozí: black, možnosti: black, white, white-outline) styl tlačítka
type: "pay", // (volitelné, výchozí: pay, možnosti: plain, buy, book, donate, ...) typ tlačítka
width: "400px", // výchozí: 100%
height: "45px" // výchozí: 100%
},
locale: "cs-CZ" // (volitelné, výchozí: cs-CZ, možnosti: en-US, de-DE, sk-SK, ...) jazyk rozhraní
})
.then(async (applepayInstance) => {
const res = await applepayInstance.canMakePayment();
if (res.result === true) {
applepayInstance.mount("#apple-pay-button-box");
} else {
console.log("Comgate Checkout: Apple Pay neni na tomto zarizeni dostupne");
}
})
.catch((error) => {
console.log("Comgate Checkout: Chyba při vytváření tlačítka Apple Pay.");
});
}

Implementace Google Pay

Velmi podobný způsob, jak nejvhodněji implementovat Google Pay tlačítko je taktéž vytvoření funkce, která bude jako parametr přijímat referenci na instanci třídy ComgateCheckout a celá další logika se odehraje v této funkci.

V bloku then(...) vytváření instance ComgateCheckout dojde k volání této definované funkce: demo_createGooglePay(checkoutInstance);

Ukázkový kód [Kód na GitHubu]

/**
* Create Google Pay button
* @param {ComgateCheckout} checkoutInstance instance Comgate checkout
*/

function demo_createGooglePay(checkoutInstance) {
checkoutInstance
.createGooglePay({ // alternativní funkční zápis metody createGooglePay({}), createGooglePay()
// kompletní seznam parametrů je dostupný níže
style: {
// hodnoty dle dokumentace Google Pay
style: "black", // (volitelné, výchozí: black, možnosti: black, white) styl tlačítka
type: "pay", // (volitelné, výchozí: pay, možnosti: plain, buy, book, donate, ... ) typ tlačítka
width: "400px", // výchozí: 100%
height: "45px" // výchozí: 100%
},
locale: "cs" // (volitelné, výchozí: cs, možnosti: en, de, sk, ...) jazyk rozhraní
})
.then(async (googlepayInstance) => {
const res = await googlepayInstance.canMakePayment();
if (res.result === true) {
googlepayInstance.mount("#google-pay-button-box");
} else {
console.log("Comgate Checkout: Google Pay neni na tomto zarizeni dostupne");
}
})
.catch((error) => {
console.log("Comgate Checkout: Chyba při vytváření tlačítka Google Pay.");
});
}

Zasílání požadavků na server e-shopu

V případě, kdy došlo ke zvolení přístupu s dynamickým založením a zpracováním platby, je možné využít předpřipravené metody pro odesílání požadavků na váš server. Tato metoda je dostupná v objektu payload při volání callbacku onRequirePayment, nebo na samotné instanci třídy ComgateCheckout.

Pro přístup k metodě přímo na instanci ComgateCheckout je nutné si uložit referenci na vytvořenou instanci do proměnné například ve scopu listeneru ComgateCheckoutReady (viz příklad výše, pro vytvoření instance pro “Dynamické založení a zpracování platby”).

Ukázkový kód - request metodou POST [Kód na GitHubu]

// POST request na server API e-shopu
checkoutInstanceRef
.eshopRequest({
method: "POST",
url: "https://eshop.cz/api/create-transaction",
validStatus: 201, // (volitelné, výchozí: 200) HTTP status kód, který je považován za úspěšný
checkSuccessParam: true, // (volitelné, výchozí: false) response je JSON a obsahuje parametr 'success', který musí být true
body: { // odeslat jako POST JSON body (jen POST)
param: "value",
param2: "value2"
},
query: { // odeslat jako GET parametry v URL (POST i GET)
param: "value",
param2: "value2"
}
})
.then((response) => {
// response serveru musí být podporována knihovnout Axios pro automatické rozparsování
// OK
})
.catch((error) => {
// request se nezdařil
console.log("Checkout eshopRequest ERROR: ", error);
payload.reject();
});

Ukázkový kód - request metodou GET [Kód na GitHubu]

// GET request na server API e-shopu
checkoutInstanceRef
.eshopRequest({
method: "GET",
url: "https://eshop.cz/api/create-transaction",
validStatus: 201, // (volitelné, výchozí: 200) HTTP status kód, který je považován za úspěšný
checkSuccessParam: true, // (volitelné, výchozí: false) response je JSON a obsahuje parametr 'success', který musí být true
query: { // odeslat jako GET parametry v URL (POST i GET)
param: "value",
param2: "value2"
}
})
.then((response) => {
// response serveru musí být podporována knihovnout Axios pro automatické rozparsování
// OK
})
.catch((error) => {
// request se nezdařil
console.log("Checkout eshopRequest ERROR: ", error);
payload.reject();
});

Kompletní ukázky

V následující sekci jsou dostupné odkazy na ukázky kompletní implementace (pouze v angličtině).

Použití správce závislostí

Instalace závislosti do vašeho projektu:

npm i @comgate/checkout

Načtení závislosti do zdrojového kódu:

import ComgateCheckout from '@comgate/checkout';
// styly používané pro Checkout SDK komponenty
import '@comgate/checkout/lib/comgate-checkout.css';

A následně je možné vytvořit instanci ComgateCheckout. Jediným rozdílem oproti příkladům uvedeným výše je nutné volat přímo ComgateCheckout(), místo window.ComgateCheckout().

ComgateCheckout({
checkoutId: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", // (povinné) checkout ID
locale: "en", // (volitelné, default: cs) jazyk UI
debug: true, // (volitelné, default: false) povolit debug mode
transactionId: "XXXX-XXXX-XXXX", // (povinné) Comgate ID transakce
// ...
})
.then((checkoutInstance) => {
// instance připravena
// TODO DIY
})
.catch((error) => {
// chyba v průběhu vytváření instance
// TODO DIY
});

UPOZORNĚNÍ

Při používání správce závislostí (npm, yarn, …), není ComgateCheckout mapováno na window.

Definice API komponent

Bude upřesněno později.

Parametry pro Apple Pay

(K dispozici pouze na zařízeních Apple v prohlížeči Safari)

https://applepaydemo.apple.com/

Parametry pro Google Pay

https://developers.google.com/pay/api/web/guides/resources/customize

Checkout SDK

COMING SOON

We are very sorry, but the English translation is not ready yet.

In the meantime, use the Czech version.

Using Packaging Tools

Coming soon.

Definition of components API

Coming soon.

Parameters for Apple Pay

(Only available on Apple devices in Safari browser)

https://applepaydemo.apple.com/

Parameters for Google Pay

https://developers.google.com/pay/api/web/guides/resources/customize

Checkout SDK

UŽ ČOSKORO

Je nám veľmi ľúto, ale slovenský preklad ešte nie je hotový.

Zatiaľ používajte českú verziu.

Používanie nástrojov na balenie

Už čoskoro.

Definícia komponentov API

Už čoskoro.

Parametre pre Apple Pay

(K dispozícii iba na zariadeniach Apple v prehliadači Safari)

https://applepaydemo.apple.com/

Parametre pre Google Pay

https://developers.google.com/pay/api/web/guides/resources/customize