Integrácia terminálu s pokladničným systémom

Platobný terminál je možné ovládať z iného zariadenia v lokálnej sieti pomocou jednoduchého REST API. Medzi podporované operácie patrí:

• Založenie (iniciácia) platby
• Získanie stavu platby
• Storno
• Refundácia
• Predautorizácia
• Denná uzávierka
• Tlač dokladu

Vzhľadom k množstvu a rozmanitosti podporovaných pokladničných systémov doporučujeme konzultovať prípadné nejasnosti aj s ich zákazníckou podporou. 

Podklady pre integráciu

Protokol prepojenia s pokladničným systémom je k dispozícii tu. Aktuálna verzia dokumentácie je 2.0. 

Pre vyskúšanie protokolu je k dispozícii Demo aplikácia, ktorá simuluje chovanie pokladničného systému. Demo otvoríte v prehliadači Firefox. URL musí byť vo formáte http. Pre prihlásenie zadajte IP a číslo portu terminálu a potom heslo 27924505 (heslo platí nielen pre demo, ale aj pri ostrom prepojení). Terminál aj počítač musí byť pripojený v rovnakej lokálnej sieti.

Ďalej môžete využiť pripravené kolekcie do aplikácie Postman. 

Záverečné testovanie

Pre úspešné dokončenie integrácie platobného terminálu s pokladňou vykonajte vždy záverečné testovanie dľa testovacieho protokolu tu. Protokol vyplňte a pošlite na adresu podpora@comgate.cz.

Rozsah integrácie a testovania závisí na funkciách, ktoré váš pokladničný systém podporuje a ktoré sú na danom termináli povolené. Tiež doporučujeme používať najvyššiu možnú verziu API.

Postup testovania:

1) Overte, či sú terminál aj pokladňa pripojené do rovnakej lokálnej siete a pre komunikáciu sa používa protokol HTTP (nie HTTPS) (protokol str. 61).

2) Overte, že pre komunikáciu máte v pokladni nakonfigurovanú správnu IP adresu a číslo portu, ktoré vidíte na termináli (protokol str. 32).

3) Otestujte ZALOŽENIE PLATBY (protokol str. 62).

1. Obchodník na pokladničnom systéme založí novú platbu. Zadá čiastku, menu a variabilný symbol. 
2. Pokladňa iniciuje požiadavku na platbu /payment a vytvorí spojenie s platobným terminálom. 
3. Pokladňa následne vykonáva pravidelný dopyt na stav platby volaním požiadavky /status.
4. Zákazník na termináli vykoná platbu kartou (priložením, vložením).
5. Terminál platbu prijme a do pokladne vráti stav platby Finished.
6. Následne pokladňa vyžiada od terminálu potvrdenie platby požiadavkou /result. 
7. Z pokladničného systému musí byť platba potvrdená zavolaním /confirm do 60 sekúnd.
8. Terminál zobrazuje prijatie platby a dotazuje na tlač účtenky (v prípade, že je funkcia aktívna).

4) Otestujete overenie STAVU TRANSAKCIE na autorizačnom serveri (protokol str. 106).

1. Pokladňa zavolá požiadavku /transaction_status na pôvodný transaction Id platby.
2. Systém vráti status transakcie "OK".

5) Otestujte založenie REFUNDÁCIE (protokol str. 71).

1. Obchodník na pokladničnom systéme vytvorí refundáciu. Zadá čiastku, menu a variabilný symbol. 
2. Pokladňa iniciuje požiadavku na refundáciu /refund a vytvorí spojenie s platobným terminálom. 
3. Pokladňa následne vykonáva pravidelné dotazovanie na stav platby volaním požiadavky /status.
4. Zákazník na termináli použije platobnú kartu (priložením, vložením).
5. Pokladňa zavolá požiadavku /reverse s original Transaction Id platby.
6. Terminál vykoná refundáciu a do pokladne vráti stav Finished.
7. Následne pokladňa vyžiada od terminálu potvrdenie refundácie požiadavkou /result. 
8. Z pokladničného systému musí byť refundácia potvrdená zavolaním /confirm do 60 sekúnd.
9. Terminál zobrazuje vykonanie refundácie a dotazuje na tlač účtenky (v prípade, že je funkcia aktívna).

6) Otestujte STORNO (reversal) platby alebo refundácie (protokol str. 79).

Táto metóda vykoná vrátenie poslednej platby na účet zákazníka. Táto metóda môže byť použitá len pre operácie Platby a Refundácia platby.

1. Pokladňa iniciuje požiadavku na platbu /payment a vytvorí spojenie s platobným terminálom. 
2. Obchodník vykoná STORNO platby.
3. Pokladňa znova vykonáva pravidelné dotazovanie na stav platby volaním požiadavky /status.
4. Terminál storno vykoná a do pokladne vráti stav platby Finished.
5. Následne pokladňa vyžiada od terminálu potvrdenie storna požiadavkou /result. 
6. Z pokladničného systému musí byť storno potvrdené zavolaním /confirm do 60 sekúnd.
7. Terminál potvrdí vykonanie akcie a vytlačí doklad.

7) Otestujte vykonanie UZÁVIERKY (protokol str. 38).

Uzávierka sa vykonáva za účelom kontroly skutočného stavu vykonaných transakcií za určité časové obdobie. Po vykonaní uzávierky dôjde k vynulovaniu súčtov transakcií a vymazaniu transakcií z histórie terminálu. Každá ďalšia transakcia sa premietne už v novej uzávierke.

1. Obchodník na pokladničnom systéme vyžiada vykonanie dennej uzávierky.
2. Pokladňa zavolá požiadavku /closing.
3. Uzávierka je dokončená, pokladňa vráti úspešné dokončenie a história transakcií na termináli je vymazaná.

8) Otestujte funkciu PREDAUTORIZÁCIA (protokol str. 83).

1. Obchodník na pokladničnom systéme založí novú predautorizáciu. Zadá čiastku, menu a variabilný symbol. 
2. Pokladňa iniciuje požiadavku /preauth a vytvorí spojenie s platobným terminálom. 
3. Terminál zobrazí pokyn pre použitie platobnej karty. Počas tohto stavu je možné zrušiť predautorizáciu volaním /cancel.
4. Pokladňa vykonáva pravidelné dotazovanie na stav platby volaním požiadavky /status.
5. Zákazník na termináli vykoná platbu kartou (priložením, vložením).
6. Terminál platbu prijme a do pokladne vráti stav platby Finished.
7. Následne pokladňa vyžiada od terminálu potvrdenie predautorizácie požiadavkou /result.
8. Z pokladničného systému musí byť platba potvrdená zavolaním /confirm do 60 sekúnd.
9. Terminál potvrdí vykonanie akcie a ponúkne tlač dokladu.

Časté otázky

Ako z pokladne vyvolať prieběžnú uzávierku (medzisúčet)?

Z pokladne je možné vyvolať len uzávierku štandardnú. Vyvolanie medzisúčtu je možné len prostredníctvom terminálu. 

Aký je rozdiel medzi medzisúčtom a uzávierkou?

Uzávierka sa vykonáva za účelom kontroly skutočného stavu vykonaných transakcií za určité časové obdobie. Po vykonaní uzávierky dôjde k vynulovaniu súčtov transakcií a vymazaniu transakcií z histórie. Každá ďalšia transakcia sa premietne už v novej uzávierke.

Medzisúčet slúži k priebežnému overeniu súčtu transakcií. Medzisúčet vykoná súčet transakcií, ktoré na termináli prebehli v časovom úseku od poslednej uzávierky. Medzi dvomi uzávierkami je možné vykonávať ľubovoľný počet medzisúčtov. Stavy transakcií ani záznamy o transakciách sa vykonaním medzisúčtu nevymažú, medzisúčet teda neovplyvní ďalšiu uzávierku.

Aký je rozdiel medzi pojmami refundácia a reversal?

Refundácia je proces, pri ktorom sú finančné prostriedky vrátené späť platcovi. Refundácia môže byť vyvolaná z rôznych dôvodov, ako sú vrátenie tovaru alebo služby alebo v prípade, kedy platca nesúhlasí s vykonanou platbou a vyžaduje jej vrátenie. Refundácia nie je viazaná na konkrétnu transakciu alebo kartu, je možné vrátiť ľubovoľnú čiastku na ľubovoľnú kartu.

Reversal alebo storno je situácia, kedy sa transakcia zruší a financie sa vrátia späť na účet platcu. Reversal sa vzťahuje k určitej transakcii a platcovi je vždy vrátená celá čiastka tejto transakcie. Pre reversal nie je potrebná interakcia s platobnou kartou.

Aké meny prijíma terminál?

Podporované meny sú CZK a EUR. Možnosť platby v EUR však záleží na nastavení na strane Comgate pre konkrétny terminál.

Je možné vypnúť tlač účtenky z terminálu?

Áno, tlač účteniek je možné na každom termináli vypnúť na želanie klienta nastavením na strane Comgate. Z bežnej praxe je vhodné doklady vytlačiť prostredníctvom pokladne a klienti môžu požiadať Comgate o zrušenie tlače účteniek z terminálu.

Ako riešiť sprepitné na termináli?

Terminál umožňuje zadávať sprepitné priamo na displeji. Táto funkcia je nastavovaná zo strany Comgate, napriek tomu v predvolenom nastavení Comgate sprepitné na termináloch s pokladničnými systémami nezapína. V prípade povolenia aktívneho sprepitného na termináli musí byť pokladničný systém pripravený na to, že výsledná čiastka úspešnej transakcie môže byť vyššia, ako s akou bola z pokladne na termináli transakcia založená, a musí vedieť tento rozdiel správne zaúčtovať ako sprepitné. Výška sprepitného je vrátená v atribute tipAmount v endpointu /result. 

Ak budete chcieť sprepitné na termináli vo svojej integrácii riešiť, informujte nás prosím o tejto skutočnosti, aby sme povolili možnosť nastaviť sprepitné klientom s vašim pokladničným systémom.