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
  • Tisk dokladu

Vzhledem k množství a rozmanitosti podporovaných pokladních systémů doporučujeme konzultovat případné nejasnosti také s jejich zákaznickou podporou. 

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. 

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) (protokol str. 61).

2) Ověřte, že v pokladně máte pro komunikaci nakonfigurovanou správnou IP adresu a číslo portu, které vidíte na terminálu (protokol str. 32).

3) Otestujte ZALOŽENÍ PLATBY (protokol str. 62).

1. 1. Obchodník na pokladním systému založí novou platbu. Zadá částku, měnu a variabilní symbol. 
   2. Pokladna iniciuje požadavek na platbu /payment a vytvoří spojení s platebním terminálem. 
   3. Pokladna následně provádí pravidelné dotazování na stav platby voláním požadavku /status.
   4. Zákazník na terminálu provede platbu kartou (přiložením, vložením).
   5. Terminál platbu přijme a do pokladny vrátí stav platby Finished.
   6. Následně pokladna vyžádá od terminálu potvrzení platby požadavkem /result. 
   7. Z pokladního systému musí být platba potvrzena zavoláním /confirm do 60 vteřin.
   8. Terminál zobrazuje přijetí platby a dotazuje na tisk účtenky (v případě, jeli funkce aktivní).

4) Otestujete ověření STAVU TRANSAKCE na autorizačním serveru (protokol str. 106).

1. 1. Pokladna zavolá požadavek /transaction_status na původní transactionId platby.
   2. Systém vrátí status transakce "OK".
      
      

5) Otestujte založení REFUNDACE (protokol str. 71).

1. 1. Obchodník na pokladním systému vytvoří refundaci. Zadá částku, měnu a variabilní symbol. 
   2. Pokladna iniciuje požadavek na refundaci /refund a vytvoří spojení s platebním terminálem. 
   3. Pokladna následně provádí pravidelné dotazování na stav platby voláním požadavku /status.
   4. Zákazník na terminálu použije platební kartu (přiložením, vložením).
   5. Pokladna zavolá požadavek /reverse s originalTransactionId platby.
   6. Terminál provede refundaci a do pokladny vrátí stav Finished.
   7. Následně pokladna vyžádá od terminálu potvrzení refundace požadavkem /result. 
   8. Z pokladního systému musí být refundace potvrzena zavoláním /confirm do 60 vteřin.
   9. Terminál zobrazuje provedení refundace a dotazuje na tisk účtenky (v případě, jeli 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.

1. 1. Obchodník na pokladním systému založí novou platbu. Zadá částku, měnu a variabilní symbol. 
   2. Pokladna iniciuje požadavek na platbu /payment a vytvoří spojení s platebním terminálem. 
   3. Pokladna následně provádí pravidelné dotazování na stav platby voláním požadavku /status.
   4. Obchodník provede STORNO platby.
   5. Pokladna zavolá požadavek /reverse s originalTransactionId platby.
   6. Pokladna znovu provádí pravidelné dotazování na stav platby voláním požadavku /status.
   7. Terminál storno provede a do pokladny vrátí stav platby Finished.
   8. Následně pokladna vyžádá od terminálu potvrzení storna požadavkem /result. 
   9. Z pokladního systému musí být storno potvrzeno zavoláním /confirm do 60 vteřin.
   10. Terminál potvrdí provedení akce a vytiskne doklad.

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.

1. 1. Obchodník na pokladním systému vyžádá provedení denní uzávěrky.
   2. Pokladna zavolá požadavek /closing.
   3. 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).

1. 1. Obchodník na pokladním systému založí novou předautorizaci. Zadá částku, měnu a variabilní symbol. 
   2. Pokladna iniciuje požadavek /preauth a vytvoří spojení s platebním terminálem. 
   3. Terminál zobrazí pokyn k použití platební karty. Během tohoto stavu lze zrušit předautorizaci voláním /cancel.
   4. Pokladna provádí pravidelné dotazování na stav platby voláním požadavku /status.
   5. Zákazník na terminálu provede platbu kartou (přiložením, vložením).
   6. Terminál platbu přijme a do pokladny vrátí stav platby Finished.
   7. Následně pokladna vyžádá od terminálu potvrzení předautorizace požadavkem /result.
   8. Z pokladního systému musí být platba potvrzena zavoláním /confirm do 60 vteřin.
   9. Terminál potvrdí provedení akce a nabídne tisk dokladu.

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