Integrácia terminálu s pokladničným systémom
Integrácia terminálu s pokladničným systémom
Zhrnutie článku
Považujete toto zhrnutie za užitočné?
Ďakujeme za vašu spätnú väzbu
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
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.
Terminál aj pokladňa musia byť pripojené do rovnakej lokálnej siete a pre komunikáciu musí byť použitý protokol HTTP (nie HTTPS). Viac v časti Záverečné testovanie.
Podklady pre integráciu
Protokol prepojenia s pokladničným systémom je k dispozícii tu. Aktuálna verzia dokumentácie je 3.01.
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.
Overenie podpisu na karte
Pokiaľ nie je nastavená tlač účteniek na termináli (účtenky teda vytlačí len pokladňa) a ak si terminál nevyžiada iný typ overenia priamo (zadanie PIN), môže dôjsť k vyžiadaniu overenia podpisu na karte. V takom prípade je zodpovednosť za overenie podpisu na karte na pokladničnom systéme. V endpointe "result" bude v atribute cvmTypeList vrátená v poli hodnota SIGNATURE. Na účtenke z pokladničného systému by mal byť pre taký prípad vyžiadaný podpis, obsluha by mala byť pokladničným systémom vyzvaná ku kontrole podpisu s podpisom na karte. Pokiaľ podpis na účtenke nezodpovedá podpisu na karte, je potrebné platbu na termináli z pokladne následne stornovať.
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).
2) Overte, že pre komunikáciu máte v pokladni nakonfigurovanú správnu IP adresu a číslo portu, ktoré vidíte na termináli.
3) Otestujte ZALOŽENIE PLATBY.
Obchodník na pokladničnom systéme založí novú platbu. Zadá čiastku, menu a variabilný symbol.
Pokladňa iniciuje požiadavku na platbu /payment a vytvorí spojenie s platobným terminálom.
Pokladňa následne vykonáva pravidelný dopyt na stav platby volaním požiadavky /status.
Zákazník na termináli vykoná platbu kartou (priložením, vložením).
Terminál platbu prijme a do pokladne vráti stav platby Finished.
Následne pokladňa vyžiada od terminálu potvrdenie platby požiadavkou /result.
Z pokladničného systému musí byť platba potvrdená zavolaním /confirm do 60 sekúnd.
Terminál zobrazuje prijatie platby a dotazuje na tlač účtenky (v prípade, že je funkcia aktívna).
Volanie stavu platby /status doporučujeme najprv vykonať po 3 sekundách od založenia transakcie a potom cyklicky po cca 200-500 milisekundách. Pokiaľ nevykonáte potvrdenie /confirm do 60 sekúnd od prijatia pozitívneho stavu platby, bude transakcia automaticky stornovaná. Pokiaľ je terminál nastavený na tlač účteniek nielen pre obchodníka, ale aj pre zákazníka, nebude možné vykonať novú platbu do doby, kým bude vysporiadaná tlačová fronta (terminál sa po vykonaní transakcie opýta na tlač účtenky pre zákazníka).
4) Otestujete overenie STAVU TRANSAKCIE na autorizačnom serveri.
Pokladňa zavolá požiadavku /transaction_status na pôvodný transaction Id platby.
Systém vráti status "OK".
Pokladňa zavolá požiadavku /result na pôvodný transactionId platby, skontroluje, či parameter transactionType v odpovedi má hodnotu TRANSACTION_STATUS a overí stav transakcie podľa parametra responseCode.
5) Otestujte založenie REFUNDÁCIE.
Obchodník na pokladničnom systéme vytvorí refundáciu. Zadá čiastku, menu a variabilný symbol.
Pokladňa iniciuje požiadavku na refundáciu /refund a vytvorí spojenie s platobným terminálom.
Pokladňa následne vykonáva pravidelné dotazovanie na stav refundácie volaním požiadavky /status.
Zákazník na termináli použije platobnú kartu (priložením, vložením).
Terminál vykoná refundáciu a do pokladne vráti stav Finished.
Následne pokladnica načíta výsledok refundácie z /result.
Z pokladničného systému musí byť refundácia potvrdená zavolaním /confirm do 60 sekúnd.
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.
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.
Obchodník vykoná STORNO platby.
Pokladňa zavolá požiadavku /reverse s original Transaction Id platby.
Pokladňa znova vykonáva pravidelné dotazovanie na stav storna volaním požiadavky /status.
Terminál storno vykoná a do pokladne vráti stav storna Finished.
Následne pokladnica načíta výsledok storna z /result.
Pri zakladaní STORNO musí byť použité pôvodné transactionId platby, ktorú chcete stornovať. Pokiaľ tento parameter nevyplníte, bude stornovaná posledná vykonaná transakcia. Stornovať platbu je možné len do vykonania účtovnej uzávierky a to len v pokladničnom systéme. Následne je možné vrátenie finančných prostriedkov len pomocou refundácie, v prípade, že je na termináli povolená.
7) Otestujte vykonanie UZÁVIERKY.
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.
Obchodník na pokladničnom systéme vyžiada vykonanie dennej uzávierky.
Pokladňa zavolá požiadavku /closing.
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.
Obchodník na pokladničnom systéme založí novú predautorizáciu. Zadá čiastku, menu a variabilný symbol.
Pokladňa iniciuje požiadavku /preauth a vytvorí spojenie s platobným terminálom.
Terminál zobrazí pokyn pre použitie platobnej karty. Počas tohto stavu je možné zrušiť predautorizáciu volaním /cancel.
Pokladňa vykonáva pravidelné dotazovanie na stav predautorizácie volaním požiadavky /status.
Zákazník na termináli vykoná predautorizáciu kartou (priložením, vložením).
Terminál predautorizáciu prijme a do pokladne vráti stav predautrizácie Finished.
Následne pokladňa načíta od terminálu potvrdenie predautorizácie z /result.
Z pokladničného systému musí byť predautrizácia potvrdená zavolaním /confirm do 60 sekúnd.
Terminál potvrdí vykonanie akcie a ponúkne tlač dokladu (ak je funkcia aktívna).
Po dokončení predautorizácie už nie je možné transakciu zrušiť volaním /cancel, ale voláním /preauth/cancel. Pokiaľ predautorizácia nie je dokončená, po niekoľkých dňoch sa automaticky zruší. Inkrementálna predautorizácia /preauth/increment (navýšenie čiastky predautorizácie) nie sú podporované.
Č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.
Aké sú náležitosti účtenky?
Dátum vykonania platby
Číslo účtenky
Označenie obchodníka
Adresa prevádzkarne
IČO/DIČ
Vymaskované číslo použitej karty
Čiastka
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.
Bol tento článok užitočný?