Přeskočit na hlavní obsah

Testování integrace platebního terminálu

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

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

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

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

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.

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

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.