Integrace terminálu s pokladním systémem
    • Pdf

    Integrace terminálu s pokladním systémem

    • Pdf

    Shrnutí článku

    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 3.01.

    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.

    Zjištění nejvyšší dostupné verze GSA API

    Pro zjištění nejvyšší dostupné verze GSA API lze využít např. volání endpointu "info".

    Je potřeba provést iterace pomocí GET požadavku na adresu endpointu od nejvyšší verze směrem k nejnižší (dle dokumentace):

    1. GET http://{ip_adresa_terminalu}:{port}/api/switchio/pay/v6/info

    2. GET http://{ip_adresa_terminalu}:{port}/api/switchio/pay/v5/info

    3. GET http://{ip_adresa_terminalu}:{port}/api/switchio/pay/v4/info

    4. GET http://{ip_adresa_terminalu}:{port}/api/switchio/pay/v2/info

    5. GET http://{ip_adresa_terminalu}:{port}/paya/info


    V případě, že terminál verzi protokolu podporuje, tak vrátí jako odpověď s hlavičkou 200 OK objekt JSON obsahující jméno a použitou verzi protokolu a ID terminálu, v opačném případě vrátí terminál text “Endpoint not supported.” a hlavičku HTTP 404 Not Found.


    Pozn.: Terminály pravidelně aktualizujeme, všechny by měly podporovat alespoň verzi v2, popř. je vždy možné v terminálu zaktualizovat platební aplikaci Switchio Pay na vyšší verzi tak, aby bylo umožněno dosažení požadované vyšší verze protokolu GSA 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

      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 načte výsledek založení platby z /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ě, 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

      1. Pokladna zavolá požadavek /transaction_status na původní transactionId platby.

      2. Systém vrátí status "OK".

      3. Pokladna zavolá požadavek /result na původní transactionId platby, provede kontrolu, že v odpovědi má parametr transactionType hodnotu TRANSACTION_STATUS a ověří stav transakce podle parametru responseCode.

    Zjištění stavu transakce

    Zjištění stavu transakce pomocí endpointu "transaction_status" může mj. pomoci zejména v případech, kdy se rozpadne síťová komunikace mezi terminálem a pokladnou v okamžiku, kdy už došlo k autorizaci transakce, ale následně se už nepodařilo z pokladny odeslat požadavek na "confirm", popř. nedošlo k vrácení odpovědi na tento požadavek. Mohou nastat 2 situace:

    1. požadavek "confirm" na terminál dorazil a transakce je úspěšně uzavřena, jen nedorazila odpověď s "isConfirmed: true" zpět do pokladny,

    2. požadavek "confirm" na terminál ani nedorazil a terminál platbu po 60 vteřinách automaticky stornoval.


    Následně (popř. později, až bude síťové spojení na terminál opět aktivní) je možné si vyžádat z terminálu stav transakce. Je potřeba počítat s časovou prodlevou dle bodu b), poté lze již stav transakce považovat za finální.


    Stav transakce lze získat následujícím postupem.

    V prvním kroku je potřeba pomocí endpointu "transaction_status" vyžádat na terminálu zjištění stavu transakce. Terminál vrátí v odpovědi JSON ve tvaru:

    {
    "transactionId": "xxxx-id-transakce-xxxx",
    "isStarted": true,
    "status": "OK"
    }

    Pokud terminál vrátí jiná data pro isStarted a status, vyžádání stavu transakce nebylo z nějakého důvodu úspěšné (např. isStarted: false, status: Server busy značí nedokončenou operaci, typicky např. je-li na terminálu zobrazen dotaz na tisk účtenky pro zákazníka).


    Následně je potřeba zavolat endpoint "result", který vrátí data o transakci. Zde je potřeba zkontrolovat, že parametr "transactionType" má hodnotu "TRANSACTION_STATUS"!


    Pokud byla transakce úspěšně v pořádku dokončena, pak v "responseCode" bude "OK" a "responseMessage" text "potvrzeno". Pokud ale byla transakce stornována, v "responseCode" bude hodnota "TransactionReversed" a v "responseMessage" bude text "Transakce reverzovana!".


    Pozn.: TransactionType = TRANSACTION_STATUS je vraceno pouze při prvním volání endpointu "result" následujícím po volání endpointu "transaction_status" a pouze v něm je správný stav transakce. Zjišťování stavu transakce lze provádět pouze do provedení uzávěrky na terminálu, poté (nebo v případě nenalezené transakce) je vracen "responseCode" s hodnotou "TransactionCardholderAuthorizationDataNotFound" a stav transakce už není v takovém případě možné ověřit.


    5) Otestujte založení REFUNDACE

      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 refundace 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. Terminál provede refundaci a do pokladny vrátí stav Finished.

      6. Následně pokladna načte výsledek refundace z /result.

      7. Z pokladního systému musí být refundace potvrzena zavoláním /confirm do 60 vteřin.

      8. Terminál zobrazuje provedení refundace a dotazuje na tisk účtenky (v případě, je-li funkce aktivní).


    6) Otestujte STORNO (reversal) platby nebo refundace

    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. Obchodník provede STORNO platby.

      2. Pokladna zavolá požadavek /reverse s originalTransactionId platby.

      3. Pokladna znovu provádí pravidelné dotazování na stav storna voláním požadavku /status.

      4. Terminál storno provede a do pokladny vrátí stav storna Finished.

      5. 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

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

      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 předautorizace voláním požadavku /status.

      5. Zákazník na terminálu provede předautorizaci kartou (přiložením, vložením).

      6. Terminál předautorizaci přijme a do pokladny vrátí stav předautorizace Finished.

      7. Následně pokladna načte výsledek předautorizace z /result.

      8. Z pokladního systému musí být předautorizace potvrzena zavoláním /confirm do 60 vteřin.

      9. 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.


    Byl tento článek užitečný?

    Changing your password will log you out immediately. Use the new password to log back in.
    First name must have atleast 2 characters. Numbers and special characters are not allowed.
    Last name must have atleast 1 characters. Numbers and special characters are not allowed.
    Enter a valid email
    Enter a valid password
    Your profile has been successfully updated.