Protokol API platební brány
Specifikace 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, doporučený způsob testování integrace platební brány nebo detailní popis napojení na EET.
Ukázková implementace v jazyce PHP ke stažení zde.
Průběh platby
Založení platby – volitelné
Krok založení 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. Pro klasický e-shop, kde platíte za konkrétní zboží, je však vynechání tohoto kroku nevhodné.
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.
|
POST /v1.0/create HTTP/1.1 merchant=merchant_com&price=10000&curr=CZK&label=Beatles%20-0%Help!&refId=2010102600&method=ALL&prepareOnly=true&secret=ZXhhbXBsZS5jb206QUJDeHl6 |
|
HTTP/1.1 200 OK code=0&message=OK&transId=AB12-EF34-IJ56&redirect=https%3A%2F%2Fpayments.comgate.cz%2Fclient%2Finstructions%2F%3Fid%3DABCDEFGHIJ |
Komunikace mezi systémem Klienta a platební bránou je zabezpečena pomocí hesla a IP whitelistu (přístup je povolen pouze z IP adres systému Klienta). Nezbytné je použití protokolu HTTPS, který znemožňuje prozrazení hesla při případném odposlouchávání komunikace. Heslo je předáváno jako POST parametr (nikoliv GET parametr) proto, aby se neukládalo v logu komunikace webového serveru.
Přesměrování na 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/1.1 302 Found |
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.
V případě vynechání prvního kroku založení platby na pozadí je platba založena až při přesměrování Plátce z webu Klienta na server platební brány nebo odesláním webového formuláře z webu Klienta na server platební brány. Parametry platby, včetně unikátního referenčního čísla platby, jsou předány jako GET nebo POST parametry HTTP protokolu.
|
POST /v1.0/create HTTP/1.1 merchant=merchant_com&price=10000&curr=CZK&label=Beatles%20-20Help!&refId=2010102600&method=ALL |
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.
|
POST /handler.php HTTP/1.1 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 |
|
HTTP/1.1 200 OK |
Komunikace mezi systémem Klienta a serverem platební brány je zabezpečena pomocí hesla a IP whitelistu. Přístup musí být povolen pouze z IP adresy serveru platební brány. Rozsahy IP adres jsou definovány v sekci Zabezpečení. Je povinné použít protokol HTTPS, který znemožňuje prozrazení hesla při případném odposlouchávání komunikace. Heslo je předáváno jako POST parametr (nikoliv GET parametr) proto, aby se neukládalo v logu komunikace webového serveru.
E-shop na svojí straně zajistí, že zboží (služba) poskytnuté v rámci zaplacené transakce (identifikované pomocí unikátního transaction ID) bude vydáno Plátci pouze jednou (i při opakovaném předání výsledku stejné platby na server Klienta).
Přesměrování Plátce na web Klienta
Plátce je na základě stavu platby přesměrován na jedno ze tří URL, které e-shop zvolil při aktivaci služby. Identifikátory platby jsou předány jako GET parametry HTTP protokolu. Systém klienta musí být schopen ošetřit dvě základní situace:
- Při přesměrování Plátce na web Klienta výsledek platby ještě není známý. Platba je ve stavu PENDING. Tato situace je naprosto běžná a e-shop ji nesmí Plátci prezentovat jako chybu. Systém čeká buď na připsání platby na bankovní účet, nebo na potvrzení od Poskytovatele platby. Konečný výsledek platby se e-shop dozví později buď předáním výsledku platby na pozadí, nebo emailem, nebo v klientském portálu.
- Pokud se platební brána dozví výsledek platby okamžitě po provedení platby Plátcem, pak je Plátce směrován na příslušné URL (PAID nebo CANCELLED). Jestliže eshop implementoval předávání výsledku platby na pozadí, pak se přesměrování na web Klienta provede až po úspěšném předání výsledku platby na pozadí. Plátci nelze odeslat zboží nebo službu, kterou objednal, pouze na základě URL použité pro přesměrování, protože Plátce by mohl výsledek platby podvrhnout změnou URL ve webovém prohlížeči.
|
GET /result_ok.php?refId=2010102600&transId=AB12-EF34-IJ56 HTTP/1.1 |
Platební brána v e-shopu (iframe)
Platební brána umožňuje zobrazení optimalizované pro iframe. Tato funkcionalita je vhodná v případě, že nechcete plátce přesměrovávat na platební bránu, ale zobrazit ji v rámci svého systému. Aby se platební brána zobrazila v iframu, je potřeba při založení platby použít parametr embedded = true. Platební URL je vygenerována standardním způsobem, ale místo přesměrování zákazníka na bránu se zobrazí na stránce e-shopu iframe s platební URL. Získání platební URL najdete zde.
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 ostaních platebních metod dojde vždy k přesměrování plátce na novou stránku.
Pro správné zobrazení platební brány v iframu na webové stránce doporučujeme provést následující úpravu vašich webových stránek.
Nastavení zobrazení platební brány
|
<div id="comgate-container"> |
Postup pro získání platební URL najdete zde.
|
#comgate-container { |
|
// funkce pro otevření iframu s bránou |
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.
|
<button id="comgate-open" onclick="comgateOpen()">Zaplatit</button> |
Přesměrování zákazníka po dokončení platby
Po dokončení platby zákazníkem dochází k jeho přesměrován do e-shopu na URL, kterou jste nastavili v klientském portálu. Doporučujeme provést jednu z následujících úprav, které zajistí, že zákazník bude přesměrován přímo na návratovou URL a nezůstane tak uvnitř iframu.
První možností je přesměrovat vnější stránku na vámi určenou URL. Tím dojde k obnovení celé stránky.
|
window.top.location = window.self.location; |
Druhou možností je ze stránky uvnitř iframu poslat zprávu vnější stránce a na vnější stránce tuto událost zpracovat. Nemusí tedy dojít k obnovení celé stránky.
Pozor, skutečný výsledek platby je třeba získat na pozadí standardním způsobem. Z bezpečnostních důvodů nelze spoléhat na výsledek předaný zprávou z iframu. Jak získat výsledek platby na pozadí je popsáno zde.
|
window.parent.postMessage('[id platby]|PAID, '*'); |
|
// odchycení zprávy poslané z iframu pomocí postMessage |
Platební brána v iframu z pohledu plátce
Platební brána ComGate umožňuje uživatelům opakovat platbu, pokud se jim nepodařilo dokončit platbu napoprvé. Zobrazení platební brány v iframu uživateli je závislé na zvolené platební metodě a také, zda se výběr platebních metod nachází na straně e-shopu nebo na straně ComGate.
V případě, že je výběr platebních metod na straně e-shopu a platba je tak založena již s platební metodou, musí být pro zobrazení iframu zvolena metoda platby kartou. Pokud se uživateli nepodařilo platbu napoprvé dokončit, je mu pro další pokus opět zobrazena pouze metoda platby kartou. Tato verze je doporučována.
V případě, že e-shop nezakládá platbu s již vybranou platební metodou, je uživateli v iframu zobrazen výběr platebních metod. Zde je následně potřeba zvolit platbu kartou. Pokud se uživateli nepodařilo platbu dokončit, je mu pro další pokus opět zobrazen výběr platebních metod v iframu.
Pokud dojde v jakémkoliv kroku platebního procesu k vybrání jiné metody než platby kartou, dojde k přesměrování plátce na novou stránku. Uživatel se již zpět do iframu nevrátí.
Stavy plateb
- PENDING – Platba byla založená, finální výsledek platby zatím není známý.
- PAID – Plátce úspěšně dokončil platbu – je možné vydat zboží, resp. zpřístupnit službu.
- CANCELLED – Platba nebyla zaplacena, zboží nebude vydáno, resp. služba nebude poskytnuta.
Platbu lze považovat za zaplacenou pouze ve stavu PAID. Stav PENDING není koncový a může po něm následovat stav CANCELLED.
API protokol - platební brána ComGate
Zabezpečení
Komunikace mezi ComGate platebním systémem a e-shopem probíhá třemi způsoby.
- Serverová část e-shopového řešení se jako klient připojuje k serverové části platební brány a volá metody pro založení platby, získání stavu platby na pozadí, potvrzení předautorizace, zrušení předautortizace a získání seznamu platebních metod.
- Serverová část platební brány se jako klient připojuje k serverové části e-shopového řešení a volá metodu pro předání výsledku platby na pozadí.
- Prohlížeč plátce (uživatele) je přesměrován z e-shopu na platební bránu a následně z platební brány zpět do e-shopu.
Ve všech třech případech je nezbytné použití šifrovaného protokolu HTTPS. Platební brána podporuje pouze bezpečné nastavení TLS/SSL protokolu s následujícími povolenými šiframi: https://github.com/cloudflare/sslconfig/blob/master/conf
V případě komunikace server – server je komunikace zabezpečena pomocí hesla (secret) a nastavení IP whitelistu. Nastavení těchto parametrů je možné provést v prostředí klientského portálu.
Zakládaní plateb je předř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, Diners Club. Platby jsou dostupné v měnách CZK, EUR, PLN, HUF, USD, GBP, HRK a RON, NOK a SEK. Je k dispozici ve 12 jazycích - v češtině, slovenštině, angličtině, němčině, francouzštině, polštině, maďarštině, chorvatštině, slovinštině, rumunštině, norštině a švédštině.
V rámci platby kartou je možné využít mnoho funkcionalit. Mezi ně patří refundace platby, storno nedokončené platby, zapamatování karetních údajů na platební bráně pro pohodlné další nákupy, opakované platby (například pro předplatné s pravidelným strháváním prostředků z karty plátce) nebo předautorizace. Platbu kartou lze také zobrazit přímo v e-shopu (iframe).
Apple Pay
Služba Apple Pay je součástí platební brány ComGate. Pro zobrazení služby zákazníkovi stačí mít povolenou metodu platby kartou CARD_CZ_CSOB_2.
V rámci služby není možné použít funkcionalitu opakované platby díky bezpečnostnímu principu Apple Pay a tzv. karetní tokenizace. Ostatní funkcionality jsou k dispozici.
Zobrazení služby Apple Pay
Zobrazení služby Apple Pay se odvíjí podle toho, zda se výběr platebních metod nachází v košíku e-shopu nebo e-shop využívá výběru metod od ComGate. Dále je potřeba rozlišit, zda má dojít k přesměrování plátce na karetní bránu nebo se Apple Pay zobrazí přímo v prostředí košíku e-shopu. Rozlišujeme tedy tři možnosti zobrazení Apple Pay:
1. tlačítko Apple Pay v karetní bráně
V případě, že se výběr platebních metod nachází na straně ComGate, není pro zobrazení služby třeba žádných úprav. Stačí mít povolenou metodu platby kartou CARD_CZ_CSOB_2. Po výběru této metody ze strany plátce probíhá platba standardním procesem s přesměrováním na platební bránu. Služba se zobrazí automaticky na karetní bráně. Zde je zároveň plátci umožněno zadat číslo karty ručně. Pokud se na bránu dostane plátce ze zařízení či prohlížeče, které Apple Pay neumožňují, bude moci provést alespoň úhradu platební kartou.
2. tlačítko Apple Pay v košíku e-shopu s přesměrování plátce na karetní bránu
Pokud je výběr platebních metod na straně e-shopu, platba se zakládá jako běžná platba (více v založení platby), v požadavku je však třeba volat metodu APPLEPAY_REDIRECT. Následě dojde k přesměrování plátce na platební bránu pomocí získaného platebního odkazu. Tlačítko Apple Pay se poté zobrazí na karetní bráně automaticky. Proces platby z pohledu plátce je následně shodný s první variantou.
Doporučení, kdy zobrazovat Apple Pay v košíku e-shopu
Služba Apple Pay je dostupná pouze uživatelům, kteří mají k dispozici webový prohlížeč Safari a vlastní zařízení od společnosti Apple, které disponuje Touch ID nebo Face ID. K těmto zařízením patří iPhone, iPadu, Apple Watch a počítač 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.
Doporučení, jak správně zobrazovat Apple Pay
Správné použití log a názvů Apple Pay najdete v průvodci Marketingem od Apple Pay. Jak zobrazit tlačítko Apple Pay najdete na stránkách Buttons and Marks. Dále doporučujeme si pročíst průvodce k používání CSS stylů, dostupných v Safari.
3. tlačítko Apple Pay součástí košíku e-shopu, bez přesměrování na karetní bránu
Tuto část pro vás připravujeme.
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.
Popis API metod
Založení platby
Přístup je chráněn validací IP adresy a integrita předávaných dat je zajištěna použitím HTTPS protokolu. URL metody: https://payments.comgate.cz/v1.0/create
|
Parametr |
Typ |
Povinný |
Popis |
|
merchant |
string |
A |
identifikátor e-shopu v systému ComGate - naleznete v Klientském portálu v sekci Nastaveni obchodů - Propojeni obchodu. |
|
test |
boolean |
N |
Hodnota „true“ znamená, že platba bude založena jako testovací, hodnota „false“ znamená produkční verzi. Pokud parametr chybí, založí se platba jako produkční. |
|
country |
string |
N |
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. Pokud parametr chybí, použije se automaticky „CZ“. Parametr slouží k omezení výběru platebních metod na platební bráně. Je potřeba aby byla zvolena správná kombinace parametrů "country" a "curr" (měna) pro daný region. Například pro zobrazení českých tlačítek a platby kartou v měně CZK zvolte kombinaci country=CZ a curr=CZK. U slovenských bankovních tlačítek a platby kartou v EUR zvolte country=SK a curr=EUR. Pro polská bankovní tlačítka a platbu kartou v PLN zvolte country=PL a curr=PLN. Pro ostatní cizí měny můžete použít parametr country=ALL nebo další kód země, který platební brána přijímá. |
|
price |
integer |
A |
Cena za produkt v centech nebo haléřích. Musí být min. 1 CZK; 0,1 EUR; 1 PLN; 100 HUF; 1 USD; 1 GBP; 5 RON; 1 HRK; 0,5 NOK; 0,5 SEK. |
|
curr |
string |
A |
Kód měny dle ISO 4217. K dispozici jsou měny: CZK, EUR, PLN, HUF, USD, GBP, RON, HRK, NOK, SEK. |
|
label |
string |
A |
Krátký popis produktu (1-16 znaků) – dle této položky je možné filtrovat platby v Klientském portálu. |
|
refId |
string |
A |
Parametr vhodný k zadaní variabilního symbolu nebo čísla objednávky na straně Klienta (nemusí být unikátní, tzn., že lze založit více plateb se stejným refId). V Klientském portálu a denním csv. je parametr označen jako ID Klienta. |
|
payerId |
string |
N |
Identifikátor Plátce v systému Klienta. Identifikátor musí být ověřen například přihlášením Plátce do systému Klienta pomocí hesla, pokud není, tak parametr nevyplňujte. Používá se při platbě kartou, kde platební brána ukládá čísla karet Plátců, takže při další platbě Plátce nemusí číslo karty znovu zadávat. Tato funkce musí být pro konkrétního Klienta povolena v systému karetního zpracovatele. |
|
method |
string |
A |
Metoda platby z tabulky platebních metod, hodnota „ALL“ v případě, že si má metodu vybrat plátce, nebo jednoduchý výraz s výběrem metod (popsáno níže). |
|
account |
string |
N |
Identifikátor bankovního účtu Klienta, na který ComGate Payments převede peníze. Pokud parametr nevyplníte, použije se výchozí účet Klienta. Seznam účtů Klienta najdete na https://portal.comgate.cz/. |
|
|
string |
A |
Kontaktní email na Plátce (pro účely případné reklamace) |
|
phone |
string |
N |
Kontaktní telefon na Plátce (pro účely případné reklamace) |
|
name |
string |
N |
Identifikátor produktu – tato položka se nachází v denním csv. Klienta pod názvem Produkt. |
|
lang |
string |
N |
Kód jazyka (ISO 639-1), ve kterém budou Plátci zobrazeny instrukce pro dokončení platby, standardně povolené hodnoty („cs”, „sk“, „en”, "pl", "fr", "ro", "de", "hu", "si", "hr"), pokud parametr chybí, použije se „cs“, v případě požadavku na další jazyk, kontaktujte platby-podpora@comgate.cz. |
|
prepareOnly |
boolean |
A |
V případě zakládání platby na pozadí vyplňte „true“. Při zakládání platby přesměrováním vyplňte buď „false“ nebo parametr nepoužívejte. Jaký povolený způsob založení platby máte nastaven, zjistíte v Klientském portálu v sekci Integrace - Propojení obchodu. |
|
secret |
string |
N |
V případě zakládání platby na pozadí vyplňte heslo pro komunikaci na pozadí. Při zakládání platby přesměrováním parametr ponechte prázdný, nebo jej nepoužívejte. |
|
preauth |
boolean |
N |
V případě požadavku na předautorizaci platby kartou nastavte na „true“. V případě normální platby vyplňte „false“ nebo parametr nepoužívejte. Pouze pro platby kartou. |
|
initRecurring |
boolean |
N |
Příznak pro založení iniciační transakce pro opakované platby. Pouze pro Klienty, kteří mají službu povolenou. |
|
verification |
boolean |
N |
Parametr ověřovací platby, v případě požadavku na založení ověřovací platby (hodnota „true“) není nutné posílat parametr initRecurring. |
|
eetReport |
boolean |
N |
Příznak odeslání dat do EET. Pokud je vyplněno, přetěžuje nastavení EET v konfiguraci obchodu v Klientském Portálu. |
|
eetData |
JSON |
N |
Struktura s daty pro zaevidování platby do EET. nastavení z konfigurace v Klientském Portálu. |
| embedded | string | N | Parametr se používá při platbě kartou na platební bráně. Hodnota „true“ zajistí zobrazení karetní brány v iframe. Pokud chcete zobrazit standardní bránu, parametr nevyplňujte nebo zadejte hodnotu „false“. |
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.
|
parametr |
typ |
povinný |
popis |
|
code |
integer |
A |
Návratový kód metody a popis chyby: |
|
message |
string |
A |
|
|
transId |
string |
N |
Unikátní alfanumerický identifikátor (kód) transakce, který bude zobrazen Plátci v různých fázích platby. |
|
redirect |
string |
N |
URL stránky, kam má být Plátce přesměrován pro realizaci platby. |
|
POST /v1.0/create HTTP/1.1 merchant=merchant_com&price=10000&curr=CZK&label=Beatles%20-%20Help!&refId=2010102600&method=ALL |
|
POST /v1.0/create HTTP/1.1 merchant=merchant_com&price=10000&curr=CZK&label=Beatles%20-%20Help!&refId=2010102600&method=ALL&prepareOnly=true&secret=ZXhhbXBsZS5jb206QUJDeHl6 |
|
HTTP/1.1 200 OK code=0&message=OK&transId=AB12-EF34-IJ56&redirect= https%3A%2F%2Fpayments.comgate.cz%2Fclient%2Finstructions%2Findex%3Fid%3DABCDEFGHIJ |
Výběr platební metody
Doporučujeme v rámci nákupního procesu v e-shopu zobrazit plátci výběr platebních metod a na základě jeho výběru založit platbu s vyplněním parametru method na jednu konkrétní hodnotu (např. platba kartou nebo platba převodem z ČS apod). Potom dojde k přímému zobrazení stránky poskytovatele konkrétní platby (banka).
V případě, že parametr method není vyplněn jednou konkrétní hodnotou, dojde k zobrazení nabídky platebních metod na platební bráně. Nabídka platebních metod může být specifikována jednoduchým výrazem, který se zadává do parametru method. Výraz se vždy vyhodnocuje na základě metod, které má e-shop povolené.
Povolené oddělovače identifikátorů metod jsou „+“ pro přičtení metody a „-“ pro odečtení metody z/do výběru.
Příklad:
BANK_ALL + CARD_CZ_CS – BANK_CZ_KB = všechny bankovní metody včetně platby kartou bez bankovního tlačítka Komerční banky.
BANK_CZ_CS_P + BANK_CZ_KB + BANK_CZ_RB = pouze bankovní tlačítka u České spořitelny, Komerční banky a Reiffeisen Bank (pouze tyto 3 na rozdíl od BANK_ALL, který by vybral všechny povolené bankovní metody e-shopu).
Platební brána umožňuje, aby Plátce měl při výběru platební metody v prostředí brány ComGate předvybranou jednu konkrétní platební metodu. Stačí, aby byl plátce přesměrován na platební bránu pomocí získaného platebního odkazu s přidaným parametrem „method“ s vybranou metodou.
| https://payments.comgate.cz/client/instructions/index?id=ABCDEFGHIJ&method=CARD_CZ_CS |
Po příchodu na bránu bude mít Plátce již zaškrtnutou metodu CARD_CZ_CS, výběr metody ale dále zůstane na něm. Tato funkce má smysl pouze pro platby založené s metodou ALL, BANK_ALL nebo s vlastním výběrem metody.
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.
Potvrzení předautorizace
V případě, že e-shop založil platbu s požadavkem na předautorizaci platby kartou (s využitím parametru preauth=true), voláním této funkce vyžádá stržení peněz, které byly v rámci předautorizace zablokovány. 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. URL metody: https://payments.comgate.cz/v1.0/capturePreauth
|
parametr |
typ |
povinný |
popis |
|
merchant |
string |
A |
identifikátor e-shopu v systému ComGate |
|
transId |
string |
A |
unikátní alfanumerický identifikátor (kód) transakce (transactionId) |
|
secret |
string |
A |
heslo pro komunikaci na pozadí |
| amount | string | N | částka předautorizace, která má být z karty stržena - může být v plné nebo částečné výši transakce |
|
parametr |
typ |
povinný |
popis |
|
code |
integer |
A |
|
|
message |
string |
|
návratový kód metody a popis chyby: |
|
POST /v1.0/capturePreauth HTTP/1.1 merchant=merchant_com&transId=XA52-3R2M-EB9C&secret=ZXhhbXBsZS5jb206QUJDeHl6 |
|
HTTP/1.1 200 OK code=0&message=OK |
Zrušení předautorizace
V případě, že e-shop založil platbu s požadavkem na předautorizaci platby kartou (s využitím parametru preauth=true), voláním této funkce dává najevo, že peníze, které byly v rámci předautorizace zablokovány, nechce inkasovat a peníze se na kartě mohou opět uvolnit. Volání lze použít pouze pro platby, u nichž byl ohlášen stav AUTHORIZED. URL metody: https://payments.comgate.cz/v1.0/cancelPreauth
|
parametr |
typ |
povinný |
Popis |
|
merchant |
string |
A |
identifikátor e-shopu v systému ComGate |
|
transId |
string |
A |
unikátní alfanumerický identifikátor (kód) transakce (transactionId) |
|
secret |
string |
A |
heslo pro komunikaci na pozadí |
|
parametr |
typ |
povinný |
popis |
|
code |
integer |
A |
|
|
message |
string |
|
návratový kód metody a popis chyby: |
|
POST /v1.0/cancelPreauth HTTP/1.1 merchant=merchant_com&transId=XA52-3R2M-EB9C&secret=ZXhhbXBsZS5jb206QUJDeHl6 |
|
HTTP/1.1 200 OK code=0&message=OK |
Opakované platby
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, kteří mají službu povolenou. První (iniciační) platba probíhá standardní cestou (viz Založení platby). Proces založení druhé a každé další platby probíhá kompletně na pozadí, tyto platby jsou vázány na iniciační přes ComGate ID iniciační platby. Toto ID se musí nacházet v požadavku v parametru initRecurringId. Plátci je v systému e-shopu jako výsledek zobrazen stav platby. URL metody: https://payments.comgate.cz/v1.0/recurring
|
parametr |
typ |
povinný |
Popis |
|
merchant |
string |
A |
identifikátor e-shopu v systému ComGate |
|
country |
string |
N |
kód země („CZ“, „SK“, „PL“, „ALL“), pokud parametr chybí, použije se „CZ“ |
|
test |
boolean |
N |
Hodnota „true“ znamená, že platba bude založena jako testovací, hodnota „false“ znamená produkční verzi. Pokud parametr chybí, založí se platba jako produkční. |
|
price |
integer |
A |
Cena za produkt v centech nebo haléřích. Musí být min. 10 CZK (včetně), max. neomezeno. |
|
curr |
string |
A |
kód měny dle ISO 4217, standardně „CZK“ |
|
label |
string |
A |
krátký popis produktu (1-16 znaků) |
|
refId |
string |
A |
Reference platby v systému e-shopu (nemusí být unikátní, tzn., že lze založit více plateb se stejným refId). |
|
payerId |
string |
N |
Identifikátor Plátce v systému e-shopu. Identifikátor musí být ověřen například přihlášením Plátce do e-shopu pomocí hesla, pokud není, tak parametr nevyplňujte. Používá se při platbě kartou, kde platební brána ukládá čísla karet Plátců, takže při další platbě Plátce nemusí číslo karty znovu zadávat. Tato funkce musí být pro konkrétní e-shop povolena v systému platební brány. |
|
account |
string |
N |
Identifikátor bankovního účtu e-shopu, na který ComGate převede peníze. Pokud parametr nevyplníte, použije se výchozí účet e-shopu. Seznam účtů e-shopu najdete na https://portal.comgate.cz/. |
|
|
string |
A |
kontaktní email na Plátce (pro účely případné reklamace) |
|
phone |
string |
N |
kontaktní telefon na Plátce (pro účely případné reklamace) |
|
name |
string |
N |
Identifikátor produktu - dle této položky je potom možné se zorientovat ve statistikách plateb ComGate platebního systému. |
|
prepareOnly |
boolean |
A |
Parametr musí nabývat hodnoty „true“. Opakované platby nelze zakládat přesměrováním. |
|
secret |
string |
A |
heslo pro komunikaci na pozadí |
|
initRecurringId |
string |
A |
ComGate ID iniciační platby |
|
eetReport |
boolean |
N |
Příznak odeslání dat do EET. Pokud je vyplněno, přetěžuje nastavení EET v konfiguraci obchodu v Klientském Portálu. |
|
eetData |
JSON |
N |
Struktura s daty pro zaevidování platby do EET. Odpovídá parametrům ze specifikace protokolu EET. Pokud má e-shop nastaveno odesílání tržby do EET a parametr nebude vyplněn, použije se výchozí nastavení z konfigurace v Klientském Portálu. |
Všechny parametry jsou urlencoded, stejně jako v případě HTTP requestu pro založení standardní platby. V odpovědi se nachází parametr code, podle kterého e-shop určí, jaký výsledek zobrazí plátci. Code = 0 znamená úspěch, platba byla založena, jakýkoliv jiný kód znamená chybu a tudíž nezaložení platby.
|
parametr |
typ |
povinný |
popis |
|
code |
integer |
A |
návratový kód metody a popis chyby: |
|
message |
string |
A |
|
|
transId |
string |
N |
unikátní alfanumerický identifikátor (kód) transakce, který bude zobrazen Plátci v různých fázích platby |
|
POST /v1.0/recurring HTTP/1.1 merchant=merchant_com&price=10000&curr=CZK&label=Beatles%20-%20Help!&email= email%40platce.cz&refId=2010102600&prepareOnly=true&secret=ZXhhbXBsZS5jb206QUJDeHl6&initRecurringId=AB12-EF34-IJ56 |
|
HTTP/1.1 200 OK code=0&message=OK&transId=AB34-EF56-XY78 |
Rekurentní platby (recurring)
Rekuretní platby, tzn. opakované platby s předem definovanou částkou a periodou (např. měsíčí, týdenní apod.) lze realizovat pomocí služby Opakované platby, která je popsána v předchozích odstavcích.
Předvyplněné karetní údaje
Platební brána umožňuje zapamatování karetních údajů Plátce tak, že při následné platbě na platební bráně dojde k automatickému předvyplnění čísla karty a údaje o platnosti. Pro dokončení platby postačí zadat CVV kód. V tomto případě dochází k přesměrování Plátce na web platební brány, narozdíl od funkčnosti Opakovaných plateb, kde následná platba může proběhnout plně na pozadí, bez účasti Plátce.
Tato funkcionalita je dostupná na vyžádání. Pro její využití je nutné při založení platby vyplnit parametr PayerId. Obchodník (merchant) musí zajistit ověření a přihlášení Plátce v rámci e-shopu.
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. URL metody: https://payments.comgate.cz/v1.0/refund
Pokud platba nebyla dokončena a je ve stavu pending je možné využít metodu storno platby.
|
parametr |
typ |
povinný |
Popis |
|
merchant |
string |
A |
identifikátor e-shopu v systému ComGate |
|
transId |
string |
A |
unikátní alfanumerický identifikátor (kód) transakce (transactionId) |
|
secret |
string |
A |
heslo pro komunikaci na pozadí |
|
amount |
string |
A |
částka refundace – může být v plné nebo částečné výši transakce |
|
curr |
string |
N |
měna refundace, pokud není vyplněno, použije se „CZK“ |
|
test |
string |
N |
Hodnota „true“ znamená, že refundace bude založena jako testovací. Refundace a platba bude prověřena standardní cestou, pouze nedojde k refundaci původní platby. |
| refId | string | N | parametr vhodný k zadaní identifikačního čísla refundace na straně Klienta (nemusí být unikátní, tzn., že lze založit více refundací se stejným refId); v Klientském portálu v sekci refundací a denním csv u refundace je parametr označen jako ID Klienta. V případě, že tento parametr k refundaci není připojen, k platbě se zobrazí původní refId založené platby. |
| parametr | typ | povinný | popis |
| code | integer | A | |
| message | string | A |
návratový kód metody a popis chyby: |
|
POST /v1.0/refund HTTP/1.1 merchant=merchant_com&transId=XA52-3R2M-EB9C&secret=ZXhhbXBsZS5jb206QUJDeHl6amount=100 |
|
HTTP/1.1 200 OK code=0&message=OK |
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. Narozdíl od refundace musí být platba ve stavu očekávaná (pending). URL metody: https://payments.comgate.cz/v1.0/cancel
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.
|
parametr |
typ |
povinný |
popis |
|
merchant |
string |
A |
identifikátor e-shopu v systému ComGate |
|
transId |
string |
A |
unikátní alfanumerický identifikátor (kód) transakce (transactionId) |
|
secret |
string |
A |
heslo pro komunikaci na pozadí |
|
element |
typ |
povinný |
popis |
|
code |
integer |
A |
|
|
message |
string |
A |
návratový kód metody a popis chyby: |
|
POST /v1.0/cancel merchant=123456&transId=XA52-3R2M-EB9C&secret=ZXhhbXBsZS5jb206QUJDe12sg |
|
HTTP/1.1 200 OK |
Předání výsledku platby na pozadí
Platební brána předává výsledný stav platby HTTP požadavkem na server e-shopu. Parametry tohoto volání specifikují detail právě dokončené platby.
URL metody: https://adresa-vaseho-e-shopu/absdefg - metoda je volána na server e-shopu
|
parametr |
Typ |
povinný |
Popis |
|
merchant |
string |
A |
identifikátor e-shopu v systému ComGate |
|
test |
boolean |
A |
Hodnota „true“ znamená, že platba byla založena jako testovací, hodnota „false“ znamená produkční verzi. |
|
price |
integer |
A |
cena za produkt v centech nebo haléřích |
|
curr |
string |
A |
kód měny dle ISO 4217 |
|
label |
string |
A |
krátký popis produktu (1-16 znaků) |
|
refId |
string |
A |
reference platby (variabilní symbol, číslo objednávky) v systému e-shopu |
|
payerId |
string |
N |
identifikátor Plátce v systému e-shopu |
| payerName | string | N | předání jména účtu patřící Plátci |
| payerAcc | string | N | předání čísla účtu Plátce |
|
method |
string |
N |
použitá metoda platby, z tabulky platebních metod |
|
account |
string |
N |
identifikátor bankovního účtu e-shopu, na který ComGate Payments převede peníze |
|
|
string |
A |
kontaktní email na Plátce |
|
phone |
string |
N |
kontaktní telefon na Plátce |
|
name |
string |
N |
identifikátor produktu – dle této položky je možné vyhledávat ve statistikách plateb ComGate platebního systému. |
|
transId |
string |
A |
unikátní alfanumerický identifikátor (kód) transakce (transactionId) |
|
secret |
string |
A |
heslo pro komunikaci na pozadí |
|
status |
string |
A |
aktuální stav transakce, hodnoty |
|
fee |
string |
N |
Pokud má e-shop nastavené automatické strhávání poplatku za platbu, bude v tomto poli spočítaný poplatek za transakci, jinak bude pole nabývat hodnoty „unknown“. |
|
eetData |
JSON |
N |
struktura s daty po zaevidování platby do EET |
|
Parametr |
Typ |
povinný |
Popis |
|
code |
integer |
A |
Návratový kód metody a popis chyby: systém očekává návratový kód 0 a popis „OK“, v případě, že výsledek platby byl v pořádku přijat. |
|
POST /handler.php HTTP/1.1 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 |
|
HTTP/1.1 200 OK |
|
parametr |
typ |
povinný |
Popis |
|
fik |
string |
N |
fiskální identifikační kód poplatníka |
|
bkp |
string |
A |
bezpečnostní kód poplatníka |
|
pkp |
string |
N |
podpisový kód poplatníka zakódovaný v base64 |
|
celk_trzba |
integer |
A |
celková částka tržby |
|
poradove_cislo |
integer |
A |
pořadové číslo účtenky |
|
zakl_nepodl_dph |
integer |
N |
celková částka plnění osvobozených od DPH, ostatních plnění |
|
zakl_dan1 |
integer |
N |
celkový základ daně se základní sazbou DPH |
|
dan1 |
integer |
N |
celková DPH se základní sazbou |
|
zakl_dan2 |
integer |
N |
celkový základ daně s první sníženou sazbou DPH |
|
dan2 |
integer |
N |
celková DPH s první sníženou sazbou |
|
zakl_dan3 |
integer |
N |
celkový základ daně s druhou sníženou sazbou DPH |
|
dan3 |
integer |
N |
celková DPH s druhou sníženou sazbou |
|
cest_sluz |
integer |
N |
celková částka v režimu DPH pro cestovní službu |
|
pouzit_zboz1 |
integer |
N |
celková částka v režimu DPH pro prodej použitého zboží se základní sazbou |
|
pouzit_zboz2 |
integer |
N |
celková částka v režimu DPH pro prodej použitého zboží s první sníženou sazbou |
|
pouzit_zboz3 |
integer |
N |
celková částka v režimu DPH pro prodej použitého zboží s druhou sníženou |
|
urceno_cerp_zuct |
integer |
N |
celková částka plateb určená k následnému čerpání nebo zúčtování |
|
cerp_zuct |
integer |
N |
celková částka plateb, které jsou následným čerpáním nebo zúčtováním |
|
datum_trzby |
string |
A |
datum tržby ve formátu YYYY-MM-DD HH24:MI:SS |
|
ic_poplatnika |
string |
N |
IČ poplatníka |
|
dic_poplatnika |
string |
A |
DIČ poplatníka |
|
id_provozovny |
string |
A |
označení provozovny |
|
id_pokladny |
string |
A |
označení pokladního zařízení |
|
adresa_poplatnika |
string |
N |
adresa poplatníka |
|
rezim_trzby |
string |
A |
režim, ve kterém byla tržba uskutečněna |
|
{ |
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á. URL metody: https://payments.comgate.cz/v1.0/status
|
parametr |
typ |
povinný |
Popis |
|
merchant |
string |
A |
identifikátor e-shopu v systému ComGate |
|
transId |
string |
A |
unikátní alfanumerický identifikátor (kód) transakce (transactionId) |
|
secret |
string |
A |
heslo pro komunikaci na pozadí |
|
parametr |
typ |
povinný |
popis |
|
code |
integer |
A |
návratový kód metody a popis chyby: |
|
message |
string |
A |
|
|
merchant |
string |
A |
identifikátor e-shopu v systému ComGate |
|
test |
boolean |
A |
Hodnota „true“ znamená, že platba byla založena jako testovací, hodnota „false“ znamená produkční verzi. |
|
price |
integer |
A |
cena za produkt v centech nebo haléřích |
|
curr |
string |
A |
kód měny dle ISO 4217 |
|
label |
string |
A |
krátký popis produktu (1-16 znaků) |
|
refId |
string |
A |
reference platby v systému e-shopu |
|
payerId |
string |
N |
identifikátor Plátce v systému e-shopu |
|
method |
string |
N |
použitá metoda platby, z tabulky platebních metod |
|
account |
string |
N |
identifikátor bankovního účtu e-shopu, na který ComGate Payments převede peníze |
|
|
string |
A |
kontaktní email na Plátce |
|
phone |
string |
N |
kontaktní telefon na Plátce |
|
name |
string |
N |
identifikátor produktu - dle této položky je potom možné se zorientovat ve statistikách plateb ComGate platebního systému. |
|
transId |
string |
A |
unikátní alfanumerický identifikátor (kód) transakce (transactionId) |
|
secret |
string |
A |
heslo pro komunikaci na pozadí |
|
status |
string |
A |
aktuální stav transakce, hodnoty |
|
payerName |
string | N | předání jména účtu patřící Plátci |
| payerAcc | string | N | předání čísla účtu Plátce |
|
fee |
string |
N |
pokud má e-shop nastavené automatické strhávání poplatku za platbu, bude v tomto poli spočítaný poplatek za transakci, jinak bude pole nabývat hodnoty „unknown“ |
|
eetData |
JSON |
N |
Struktura s daty po zaevidování platby do EET. Stejná struktura, jako v případě |
|
POST /v1.0/status HTTP/1.1 merchant=merchant_com&transId=XA52-3R2M-EB9C&secret=ZXhhbXBsZS5jb206QUJDeHl6 |
|
HTTP/1.1 200 OK code=0&message=OK&merchant=merchant_com&test=false&price=10000&curr=CZK&label=Beatles%20-%20Help!&refId=2010102600&method=CARD&email=info%40customer.com&phone=%2B420123456789&transId=AB12-EF34-IJ56&secret=ZXhhbXBsZS5jb206QUJDeHl6&status=PAID |
Získání povolených metod
Metoda pro získání nastavení, které má e-shop povolené v ComGate Payments Platebním Systému. Touto metodou lze získat seznam dostupných platebních metod pro realizaci plateb. URL metody: https://payments.comgate.cz/v1.0/methods
|
parametr |
typ |
povinný |
Popis |
|
merchant |
string |
A |
identifikátor e-shopu v systému ComGate |
|
secret |
string |
A |
heslo pro komunikaci na pozadí |
|
type |
string |
N |
Formát vrácených dat („xml“ nebo „json“). Pokud nebude vyplněno, použije se „xml“. |
|
lang |
string |
N |
Výběr, v jakém jazyce budou popisy metod. Povolené hodnoty jsou „cs“, „en“, „pl“. Pokud nebude vyplněno, použije se „cs“. |
| curr | string | N | Vyplněním parametru na hodnoty CZK nebo EUR dojde k vrácení metod, které podporují zadanou měnu. |
| country | string | N | Kód země („CZ“, „SK“), parametr slouží k omezení výběru platebních metod pro zadanou zemi. |
V odpovědi se nachází XML nebo JSON, podle zvoleného parametru. Oba formáty mají stejnou úroveň zanoření.
|
element |
typ |
povinný |
popis |
|
/methods/method/id |
string |
A |
dostupná metoda platby |
|
/methods/method/name |
string |
A |
název metody, ve zvoleném jazyce |
|
/methods/method/description |
string |
A |
delší popis metody, ve zvoleném jazyce |
|
/methods/method/logo |
string |
A |
HTTP link na logo metody |
V případě chyby mají data následující tvar.
|
element |
typ |
povinný |
popis |
|
/error/code |
string |
A |
návratový kód metody a popis chyby: |
|
/error/message |
string |
A |
0 OK |
|
/error/extraMessage |
string |
N |
upřesnění chybového hlášení |
|
POST /v1.0/methods HTTP/1.1 merchant=merchant_com&secret=ZXhhbXBsZS5jb206QUJDeHl6&type=xml&lang=cs |
|
HTTP/1.1 200 OK <?xml version="1.0" encoding="UTF-8"?> |
|
HTTP/1.1 200 OK |
|
HTTP/1.1 200 OK <?xml version="1.0" encoding="UTF-8"?> |
|
HTTP/1.1 200 OK { |
Zasílání tržby do EET
Do systému EET musí obchodník evidovat každou platbu provedenou kartou nebo v hotovosti. Daňoví plátci musí posílat detail daně, neplátci DPH pouze celkovou částku. Další informace jsou obsaženy v EET řešení.
Nejprve se obchodník musí zaregistrovat do EET a stáhnout si certifikát pro zabezpečenou komunikaci. Následně obchodník provede konfiguraci propojení s EET v rozhraní klientského portálu.
Pokud je EET správně nastaveno v klientském portálu, pak je možné přejít k založení platby. V rámci plateb EET se rozlišují dva režimy:
- Automatický (výchozí) režim umožňuje obchodníkovi posílat platby do EET, aniž by musel implementovat něco navíc do komunikačního protokolu platební brány ComGate. Tento režim slouží neplátcům DPH a plátcům DPH, kteří prodávají zboží pouze v jedné daňové sazbě odpovídající nastavení v klientském portálu. Pokud je platba provedena v zahraniční měně, bude do EET zaevidovaná v Kč a jako kurz pro přepočet se použije kurz dané měny vyhlášený ČNB z předchozího dne.
- Rozšířený režim přináší nutnost upravit komunikační protokol platební brány ComGate. Do protokolu bude obchodník posílat kompletní rozpad částky pro EET v parametru eetData (viz příklad níže, názvy parametrů jsou dle specifikace EET). Tento režim je nutný pro všechny, kdo prodávají zboží ve více sazbách DPH, cestovní služby, prodávají a uplatňují vouchery nebo prodávají použité zboží. Data se předávají ve formátu JSON, částky jsou uváděny v haléřích.
|
Parametr |
typ |
povinný |
Popis |
|
celk_trzba |
integer |
A |
celková částka tržby |
|
zakl_nepodl_dph |
integer |
N |
celková částka plnění osvobozených od DPH, ostatních plnění |
|
zakl_dan1 |
integer |
N |
celkový základ daně se základní sazbou DPH |
|
dan1 |
integer |
N |
celková DPH se základní sazbou |
|
zakl_dan2 |
integer |
N |
celkový základ daně s první sníženou sazbou DPH |
|
dan2 |
integer |
N |
celková DPH s první sníženou sazbou |
|
zakl_dan3 |
integer |
N |
celkový základ daně s druhou sníženou sazbou DPH |
|
dan3 |
integer |
N |
celková DPH s druhou sníženou sazbou |
|
cest_sluz |
integer |
N |
celková částka v režimu DPH pro cestovní službu |
|
pouzit_zboz1 |
integer |
N |
celková částka v režimu DPH pro prodej použitého zboží se základní sazbou |
|
pouzit_zboz2 |
integer |
N |
celková částka v režimu DPH pro prodej použitého zboží s první sníženou sazbou |
|
pouzit_zboz3 |
integer |
N |
celková částka v režimu DPH pro prodej použitého zboží s druhou sníženou |
|
urceno_cerp_zuct |
integer |
N |
celková částka plateb určená k následnému čerpání nebo zúčtování |
|
cerp_zuct |
integer |
N |
celková částka plateb, které jsou následným čerpáním nebo zúčtováním |
|
1. Zákaznice zakoupila obnošenou bundu za 330 Kč, nové nenošené punčocháče za 50 Kč a potraviny za 115 Kč. { |
2. Zákazník vložil celou částku 500 Kč do své elektronické peněženky a zároveň z této peněženky
uhradil nákup zboží v ceně 200 Kč včetně DPH.
{
"celk_trzba": "50000",
"zakl_nepodl_dph": "0",
"zakl_dan1": "16528",
"dan1": "3472",
"zakl_dan2": "0",
"dan2": "0",
"zakl_dan3": "0",
"dan3": "0",
"cest_sluz": "0",
"pouzit_zboz1": "0",
"pouzit_zboz2": "0",
"pouzit_zboz3": "0",
"urceno_cerp_zuct": "50000",
"cerp_zuct": "20000"
}
3. Zákazník zaplatil celkem 18 000 Kč, z této částky zakoupil zájezd v ceně 17 500 Kč, za 200 Kč nakoupil zboží a 300 Kč přibylo na jeho zákaznickém účtu
pro následné čerpání (nabíjení „kreditu“).
{
"celk_trzba": "1800000",
"zakl_nepodl_dph": "0",
"zakl_dan1": "16528",
"dan1": "3472",
"zakl_dan2": "0",
"dan2": "0",
"zakl_dan3": "0",
"dan3": "0",
"cest_sluz": "1750000",
"pouzit_zboz1": "0";
"pouzit_zboz2": "0",
"pouzit_zboz3": "0",
"urceno_cerp_zuct": "30000",
"cerp_zuct": "0"
}
Verifikační, ověřovací platby
Pokud chce e-shop využít opakovaných plateb v budoucnu a chce Plátce „registrovat“ nyní, může využít ověřovací transakce. Při vyplnění parametru verification na hodnotou „true“ dojde k založení ověřovací transakce. Jakmile Plátce platbu uhradí, dojde k její automatické refundaci, není tedy nutné následně platbu refundovat ručně. Ověřovací transakce jinak funguje stejně jako iniciační transakce, tzn. je možné zakládat opakované platby s využitím jejího ComGate ID. Z důvodu limitací ze strany bank není možné kombinovat opakované platby a předautorizace.
API pro stahování souborů
Seznam převodů v rámci dne
Metoda transferList slouží k získání informace, jaké převody byly uskutečněny v rámci daného dne.
URL metody: https://payments.comgate.cz/v1.0/transferList
| parametr | typ | povinný | popis |
| merchant | string | A | identifikátor e-shopu v systému ComGate |
| secret | string | A |
heslo pro komunikaci na pozadí |
| date | string | A | metoda vrací převody za jeden den |
| test | boolean | N | vrátí předem definovaný vzorový převod |
|
POST /v1.0/transferList HTTP/1.1 merchant=135258&secret=wi9VplRz0UNqoxFqSM4udyxyA1ia5z32&date=2019-07-25 |
|
HTTP/1.1 200 OK [{"transferId":5211530,"transferDate":"2019-07-25","accountCounterparty":"0\/0000","accountOutgoing":"281481882\/0300","variableSymbol":"86616655"}] |
Detail bankovního převodu
Metoda singleTransfer zobrazuje detailní informace ke konkrétnímu bankovnímu převodu.
Povinný parametr transferId získá obchodník pomocí metody transferList.
URL metody: https://payments.comgate.cz/v1.0/singleTransfer
| parametr | typ | povinný | popis |
| merchant | string | A | identifikátor e-shopu v systému ComGate |
| secret | string | A |
heslo pro komunikaci na pozadí |
| transferId | string | A |
detaily ke konkrétnímu bankovnímu převodu |
| test | boolean | N | vhodné pro testování - vrátí detaily k přededem definovaným vzorovým převodům |
|
POST /v1.0/singleTransfer HTTP/1.1 merchant=135258&secret=wi9VplRz0UNqoxFqSM4udyxyA1ia5z32&transferId=5211530 |
|
HTTP/1.1 200 OK { }, { } ] |
CSV k vybranému převodu
Díky metodě csvSingleTransfer si lze stáhnout denní výpis ve formátu CSV.
URL metody: https://payments.comgate.cz/v1.0/csvSingleTransfer
| parametr | typ | povinný | popis |
| merchant | string | A | identifikátor e-shopu v systému ComGate |
| secret | string | A |
heslo pro komunikaci na pozadí |
| transferId | string | A |
detaily ke konkrétnímu bankovnímu převodu |
| download | string | N | Pokud není vyplněno, nebo je false, tak vrací data : název souboru a jeho obsah; pokud je true, tak vrací rovnou CSV soubor. |
| test | boolean | N | Pro účely testování vrátí ukázkový CSV soubor. |
|
POST /v1.0/csvSingleTransfer HTTP/1.1 |
|
HTTP/1.1 200 OK { |
ABO k vybranému převodu
Díky metodě aboSingleTransfer si lze stáhnout denní výpis ve formátu ABO.
URL metody: https://payments.comgate.cz/v1.0/aboSingleTransfer
| parametr | typ | povinný | popis |
| merchant | string | A | identifikátor e-shopu v systému ComGate |
| secret | string | A |
heslo pro komunikaci na pozadí |
| transferId | string | A |
detaily ke konkrétnímu bankovnímu převodu |
| download | string | N | Pokud není vyplněno, nebo je false, tak vrací data : název souboru a jeho obsah; pokud je true, tak vrací rovnou ABO soubor. |
| type | string | N | 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". |
| test | boolean | N | Pro účely testování vrátí ukázkový ABO soubor. |
|
POST /v1.0/aboSingleTransfer HTTP/1.1 merchant=135258&secret=wi9VplRz0UNqoxFqSM4udyxyA1ia5z32&transferId=5211530&download=true&type=v1 |
|
HTTP/1.1 200 OK { |
CSV pro převody v rámci dne
Přímé stažení CSV souborů pro konkrétní den metodou csvDowload. Stažený soubor ve formátu ZIP bude obsahovat jeden nebo více souborů CSV, pokud je více převodů v rámci dne. Lze využít např. pro volání pomocí wget.
URL metody: https://payments.comgate.cz/v1.0/csvDownload
| parametr | typ | povinný | popis |
| merchant | string | A | identifikátor e-shopu v systému ComGate |
| secret | string | A |
heslo pro komunikaci na pozadí |
| date | string | A |
povinný pouze za jeden den |
| test | boolean | N | Pro účely testování vrátí ukázkový CSV soubor ve formátu ZIP. |
|
POST /v1.0/csvDownload HTTP/1.1 merchant=135258&secret=wi9VplRz0UNqoxFqSM4udyxyA1ia5z32&date=2019-07-25 |
|
HTTP/1.1 200 OK ZIP soubor obsahující CSV k převodům za den v parametru ke stažení jako response |
ABO pro převody v rámci dne
Přímé stažení ABO souborů pro konkrétní den metodou aboDowload. Stažený soubor ve formátu ZIP bude obsahovat jeden nebo více souborů ABO.
Lze využít např. pro volání pomocí wget.
URL metody: https://payments.comgate.cz/v1.0/aboDownload
| parametr | typ | povinný | popis |
| merchant | string | A | identifikátor e-shopu v systému ComGate |
| secret | string | A |
heslo pro komunikaci na pozadí |
| date | string | A |
povinný pouze za jeden den |
| type | string | N | 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". |
| test | boolean | N | Pro účely testování vrátí ukázkový ABO soubor ve formátu ZIP. |
|
POST /v1.0/aboDownload HTTP/1.1 merchant=135258&secret=wi9VplRz0UNqoxFqSM4udyxyA1ia5z32&date=2019-07-25&type=v2 |
|
HTTP/1.1 200 OK |
Číselníky
|
stav |
Popis |
|
PENDING |
Platba byla založená, finální výsledek platby zatím není známý. |
|
PAID |
Plátce úspěšně zaplatil platbu – je možné vydat zboží, resp. zpřístupnit službu. |
|
CANCELLED |
Platba nebyla zaplacena, zboží nebude vydáno, resp. služba nebude poskytnuta. Ve výjimečných případech se může stát, že tento stav bude změněn na stav PAID. |
|
AUTHORIZED |
Předautorizace platby proběhla úspěšně (peníze na kartě plátce byly zablokovány). Čeká se na další požadavek, kterým bude potvrzena nebo zrušena. |
|
typ |
Popis |
identifikátor |
|
Platební metodu si vybere Plátce v rozcestníku. |
ALL |
|
|
Platební karta |
poskytovatel automaticky |
CARD_ALL (nebo CARD) |
| Odložená platba | poskytovatel automaticky | LATER_ALL |
| odložená platba od Equa bank | LATER_PLATIMPAK | |
|
Bankovní platby |
Banku Plátce vybere v rozcestníku ComGate Payments. |
BANK_ALL |
|
bankovní převod Air Bank |
BANK_CZ_AB |
|
|
bankovní převod ČSOB |
BANK_CZ_CSOB |
|
|
bankovní převod Equa Bank |
BANK_CZ_EB |
|
|
bankovní převod jiných bank |
BANK_CZ_OTHER |
|
|
bankovní tlačítko Raiffeisen Bank |
BANK_CZ_RB |
|
|
bankovní tlačítko Komerční Banky |
BANK_CZ_KB |
|
|
bankovní tlačítko GE Money Bank |
BANK_CZ_GE |
|
|
bankovní tlačítko Sberbank CZ |
BANK_CZ_VB |
|
|
bankovní tlačítko FIO Banky |
BANK_CZ_FB |
|
|
bankovní tlačítko České spořitelny |
BANK_CZ_CS_P |
|
|
bankovní tlačítko mBank |
BANK_CZ_MB_P |
|
|
bankovní tlačítko ČSOB |
BANK_CZ_CSOB_P |
|
|
bankovní tlačítko era |
BANK_CZ_PS_P |
|
|
bankovní tlačítko UniCredit Bank |
BANK_CZ_UC |
|
|
bankovní tlačítko Slovenské spořiteľňy |
BANK_SK_SP |
|
|
bankovní tlačítko VÚB Banky |
BANK_SK_VUB |
|
|
bankovní tlačítko Tatra Banky |
BANK_SK_TB |
|
|
bankovní tlačítko ČSOB |
BANK_SK_CSOB |
|
|
bankovní tlačítko Poštovná Banka |
BANK_SK_PB |
|
|
bankovní převod Prima Bank |
BANK_SK_DEXIA |
|
|
bankovní převod Fio Banky |
BANK_SK_FB |
|
| bankovní převod jiných bank | BANK_SK_OTHER | |
| bankovní tlačítko Alior Bank | BANK_PL_ALR | |
| bankovní tlačítko BGŻ BNP Paribas Polska | BANK_PL_BGZ | |
| bankovní tlačítko Blik | BANK_PL_BL | |
| bankovní tlačítko Bank Millennium | BANK_PL_BM | |
| bankovní tlačítko Bank Ochrony Środowiska | BANK_PL_BOS | |
| bankovní tlačítko Bank Pocztowy | BANK_PL_BP | |
| bankovní tlačítko BPS | BANK_PL_BPS | |
| bankovní tlačítko Banki Spółdzielcze | BANK_PL_BSP | |
| bankovní tlačítko BZ WBK | BANK_PL_BZ | |
| bankovní tlačítko Credit Agricole | BANK_PL_CA | |
| bankovní tlačítko Citi Handlowy | BANK_PL_CH | |
| bankovní tlačítko Deutsche Bank | BANK_PL_DB | |
| bankovní tlačítko Eurobank | BANK_PL_EB | |
| bankovní tlačítko GetIn Online | BANK_PL_GO | |
| bankovní tlačítko Idea Bank | BANK_PL_IDB | |
| bankovní tlačítko ING Bank Śląski | BANK_PL_ING | |
| bankovní tlačítko Inteligo | BANK_PL_INT | |
| bankovní tlačítko mBank | BANK_PL_MB | |
| bankovní tlačítko Nest Bank | BANK_PL_NEB | |
| bankovní tlačítko Noble Bank | BANK_PL_NOB | |
| bankovní tlačítko Plus Bank | BANK_PL_PB | |
| bankovní tlačítko Bank Pekao | BANK_PL_PEK | |
| bankovní tlačítko PKO BP | BANK_PL_PKO | |
| bankovní tlačítko Raiffeisen Polbank | BANK_PL_RB | |
| bankovní tlačítko T-Mobile Usługi Bankowe | BANK_PL_TM | |
| bankovní tlačítko Toyota Bank | BANK_PL_TOB | |
| bankovní tlačítko Volkswagen Bank |
BANK_PL_VWB |