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

4) Otestujete ověření STAVU TRANSAKCE na autorizačním serveru

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

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

Časté otázky