Integrace terminálu s pokladním systémem
Platební terminál lze ovládat z jiného zařízení v lokální síti pomocí jednoduchého REST API. Mezi podporované operace patří:
Založení (iniciace) platby
Získání stavu platby
Storno
Refundace
Předautorizace
Denní uzávěrka
Vzhledem k množství a rozmanitosti podporovaných pokladních systémů doporučujeme konzultovat případné nejasnosti také s jejich zákaznickou podporou.
Terminál i pokladna musí být připojena do stejné lokální sítě a pro komunikaci používat protokol HTTP (nikoliv HTTPS) (viz také níže v závěrečném testování).
Podklady k integraci
Protokol propojení s pokladním systémem je k dispozici zde. Aktuální verze dokumentace je 2.0.
Pro vyzkoušení protokolu je k dispozici Demo aplikace, která simuluje chování pokladního systému. Demo otevřete v prohlížeči Firefox. URL musí být ve formátu http. Pro přihlášení zadejte IP a číslo portu terminálu a poté heslo 27924505 (heslo platí nejen pro demo, ale i při ostrém propojení). Terminál i počítač musí být připojeny ve stejné lokální síti.
Dále můžete využít připravené kolekce do aplikace Postman.
Ověření podpisu na kartě
Pokud není nastaven tisk účtenek na terminálu (účtenky tedy tiskne pouze pokladna) a nevyžádá-li si terminál jiný typ ověření přímo (zadání PIN), může dojít k vyžádání ověření podpisu na kartě.
V takovém případě je odpovědnost za ověření podpisu na kartě na pokladním systému. V endpointu "result" bude v atributu cvmTypeList vrácena v poli hodnota SIGNATURE. Na účtence z pokladního systému by měl být pro takový případ vyžádán podpis, obsluha by měla být pokladním systémem vyzvána ke kontrole podpisu s podpisem na kartě. Pokud podpis na účtence neodpovídá podpisu na kartě, je potřeba platbu na terminálu z pokladny následně stornovat.
Závěrečné testování
Pro úspěšné dokončení integrace platebního terminálu s pokladnou proveďte vždy závěrečné testování dle testovacího protokolu zde. Protokol vyplňte a zašlete na adresu podpora@comgate.cz.
Rozsah integrace a testování závisí na funkcích, které váš pokladní systém podporuje a které jsou na daném terminálu povoleny. Doporučujeme také používat nejvyšší možnou verzi API.
Postup testování:
1) Ověřte, zda terminál i pokladna jsou připojeny do stejné lokální sítě a pro komunikaci se používá protokol HTTP (nikoliv HTTPS).
2) Ověřte, že v pokladně máte pro komunikaci nakonfigurovanou správnou IP adresu a číslo portu, které vidíte na terminálu.
3) Otestujte ZALOŽENÍ PLATBY (protokol str. 62).
Obchodník na pokladním systému založí novou platbu. Zadá částku, měnu a variabilní symbol.
Pokladna iniciuje požadavek na platbu /payment a vytvoří spojení s platebním terminálem.
Pokladna následně provádí pravidelné dotazování na stav platby voláním požadavku /status.
Zákazník na terminálu provede platbu kartou (přiložením, vložením).
Terminál platbu přijme a do pokladny vrátí stav platby Finished.
Následně pokladna načte výsledek založení platby z /result.
Z pokladního systému musí být platba potvrzena zavoláním /confirm do 60 vteřin.
Terminál zobrazuje přijetí platby a dotazuje na tisk účtenky (v případě, je-li funkce aktivní).
Volání stavu platby /status doporučujeme zpočátku provést po 3 vteřinách od založení transakce a poté cyklicky po cca 200-500 milisekundách. Pokud neprovedete potvrzení /confirm do 60 vteřin od přijetí pozitivního stavu platby, bude transakce automaticky stornována. Pokud je terminál nastaven na tisk účtenek nejen pro obchodníka, ale i pro zákazníka, nebude možné provést novou platbu do doby, než bude vypořádána tisková fronta (terminál se po provedení transakce ptá na tisk účtenky pro zákazníka).
4) Otestujete ověření STAVU TRANSAKCE na autorizačním serveru (protokol str. 106).
Pokladna zavolá požadavek /transaction_status na původní transactionId platby.
Systém vrátí status transakce "OK".
5) Otestujte založení REFUNDACE (protokol str. 71).
Obchodník na pokladním systému vytvoří refundaci. Zadá částku, měnu a variabilní symbol.
Pokladna iniciuje požadavek na refundaci /refund a vytvoří spojení s platebním terminálem.
Pokladna následně provádí pravidelné dotazování na stav refundace voláním požadavku /status.
Zákazník na terminálu použije platební kartu (přiložením, vložením).
Terminál provede refundaci a do pokladny vrátí stav Finished.
Následně pokladna načte výsledek refundace z /result.
Z pokladního systému musí být refundace potvrzena zavoláním /confirm do 60 vteřin.
Terminál zobrazuje provedení refundace a dotazuje na tisk účtenky (v případě, je-li funkce aktivní).
6) Otestujte STORNO (reversal) platby nebo refundace (protokol str. 79).
Tato metoda provede vrácení poslední platby na účet zákazníka. Tato metoda může být použita pouze pro operace Platby a Refundace platby.
Obchodník provede STORNO platby.
Pokladna zavolá požadavek /reverse s originalTransactionId platby.
Pokladna znovu provádí pravidelné dotazování na stav storna voláním požadavku /status.
Terminál storno provede a do pokladny vrátí stav storna Finished.
Následně pokladna načte výsledek storna z /result.
Při zakládání STORNO musí být použito původní transactionId platby, kterou chcete stornovat. Pokud tento parametr nevyplníte, bude stornována poslední provedená transakce. Stornovat platbu lze pouze do provedení účetní uzávěrky a pouze z pokladního systému. Následně je možné vrácení finančních prostředků pouze pomocí refundace, je-li na terminálu povolena.
7) Otestujte provedení UZÁVĚRKY (protokol str. 38).
Uzávěrka se provádí za účelem kontroly skutečného stavu provedených transakcí za určité časové období. Po provedení uzávěrky dojde k vynulování součtů transakcí a vymazání transakcí z historie terminálu. Každá další transakce se promítne již v nové uzávěrce.
Obchodník na pokladním systému vyžádá provedení denní uzávěrky.
Pokladna zavolá požadavek /closing.
Uzávěrka je provedena, pokladna vrátí úspěšné dokončení a historie transakcí na terminálu je vymazána.
8) Otestujte funkci PŘEDAUTORIZACE (protokol str. 83).
Obchodník na pokladním systému založí novou předautorizaci. Zadá částku, měnu a variabilní symbol.
Pokladna iniciuje požadavek /preauth a vytvoří spojení s platebním terminálem.
Terminál zobrazí pokyn k použití platební karty. Během tohoto stavu lze zrušit předautorizaci voláním /cancel.
Pokladna provádí pravidelné dotazování na stav předautorizace voláním požadavku /status.
Zákazník na terminálu provede předautorizaci kartou (přiložením, vložením).
Terminál předautorizaci přijme a do pokladny vrátí stav předautorizace Finished.
Následně pokladna načte výsledek předautorizace z /result.
Z pokladního systému musí být předautorizace potvrzena zavoláním /confirm do 60 vteřin.
Terminál potvrdí provedení akce a nabídne tisk dokladu (v případě, je-li funkce aktivní).
Po dokončení předautorizace již není možné transakci zrušit voláním /cancel, nýbrž voláním /preauth/cancel. Pokud předautorizace není dokončena, po několika dnech se automaticky zruší. Inkrementální předautorizace /preauth/increment (navýšení částky předautorizace) nejsou podporovány.
Časté otázky
Jak z pokladny vyvolat průběžnou uzávěrku (mezisoučet)?
Z pokladny je možné vyvolat pouze uzávěrku standardní. Vyvolání mezisoučtu je možné pouze prostřednictvím terminálu.
Jaký je rozdíl mezi mezisoučtem a uzávěrkou?
Uzávěrka se provádí za účelem kontroly skutečného stavu provedených transakcí za určité časové období. Po provedení uzávěrky dojde k vynulování součtů transakcí a vymazání transakcí z historie. Každá další transakce se promítne již v nové uzávěrce.
Mezisoučet slouží k průběžnému ověření součtu transakcí. Mezisoučet provede součet transakcí, které na terminálu proběhly v časovém úseku od poslední uzávěrky. Mezi dvěma uzávěrkami je možno provádět libovolný počet mezisoučtů. Stavy transakcí ani záznamy o transakcích se provedením mezisoučtu nemažou, mezisoučet tedy neovlivní další uzávěrku.
Jaký je rozdíl mezi pojmy refundace a reversal?
Refundace je proces, při kterém jsou finanční prostředky vráceny zpět plátci. Refundace může být vyvolána z různých důvodů, jako jsou vrácení zboží nebo služby nebo v případě, kdy plátce nesouhlasí s provedenou platbou a vyžaduje její vrácení. Refundace není vázána na konkrétní transakci nebo kartu, lze vrátit libovolnou částku na libovolnou kartu.
Reversal neboli storno je situace, kdy se transakce zruší a finance se vrátí zpět na účet plátce. Reversal se vztahuje k určité transakci a plátci je vždy vrácena celá částka této transakce. Pro reversal není třeba interakce s platební kartou.
Jaké měny umí terminál?
Podporované měny jsou CZK a EUR. Možnost platby v EUR však záleží na nastavení na straně Comgate pro konkrétní terminál.
Je možné vypnout tisk účtenky z terminálu?
Ano, tisk účtenek je možné na každém terminálu vypnout na přání klienta nastavením na straně Comgate. Z běžné praxe je vhodné doklady tisknout prostřednictvím pokladny a klienti mohou požádat Comgate o zrušení tisku účtenek z terminálu.
Jaké jsou náležitosti účtenky?
Datum provedení platby
Číslo účtenky
Označení obchodníka
Adresa provozovny
IČO/DIČ
Vymaskované číslo použité karty
Částka
Jak řešit spropitné na terminálu?
Terminál umožňuje zadávat spropitné přímo na displeji. Tato funkce je nastavována ze strany Comgate, nicméně ve výchozím nastavení Comgate spropitné na terminálech s pokladními systémy nezapíná. V případě povolení aktivního spropitného na terminálu musí být pokladní systém připraven na to, že výsledná částka úspěšné transakce může být vyšší, než s jakou byla z pokladny na terminálu transakce zakládána, a musí umět tento rozdíl správně zaúčtovat jako spropitné. Výše spropitného je vrácena v atributu tipAmount v endpointu /result.
Budete-li chtít spropitné na terminálu ve své integraci řešit, informujte nás prosím o této skutečnosti, abychom povolili možnost nastavit spropitné klientům s vaším pokladním systémem.