GSA protokol

Comgate v súčasnosti umožňuje 2 spôsoby využitia GSA protokolu – primárne ho možno využiť na komunikáciu pokladnice s terminálom v lokálnej sieti, prípadne aj prostredníctvom cloudového riešenia (GSA+).

Prepojenie cez lokálnu sieť (GSA)

Komunikácia pokladnice s terminálom prebieha pomocou jednoduchého REST API zasielaním HTTP požiadaviek vo formáte JSON na IP adresu a port terminálu v lokálnej sieti. Dokumentácia k protokolu GSA na prepojenie s pokladnicou je k dispozícii tu.

Implementácia a odporúčané postupy

Obe zariadenia (terminál aj pokladnica) musia byť pripojené v rovnakej lokálnej sieti. Na komunikáciu je potrebné používať protokol HTTP (nie HTTPS). Sú podporované tieto operácie:

• Zistenie stavu terminálu
• Platba
• Refundácia (len u vybraných klientov)
• Predautorizácia a jej dokončenie či zrušenie (bez inkrementálnej/dekrementálnej, len u vybraných klientov)
• MOTO platby (len u vybraných klientov na obmedzené účely)
• Storno (reversal) transakcie
• Zistenie stavu transakcie
• Zrušenie platby čakajúcej na kartu či PIN
• Uzávierka

Minimálna implementácia by mala zahŕňať aspoň Platbu, Storno a Uzávierku.

IP adresa, port a heslo (secureString)

Pokladnica komunikuje s terminálom pomocou jeho IP adresy. Tú je potrebné v pokladničnom systéme poznať. Zároveň je vhodné zabezpečiť, aby sa IP adresa terminálu v sieti nemenila (napríklad nepoužívať DHCP a nastaviť terminálu statickú IP adresu) a nebolo tak potrebné IP adresu terminálu v pokladničnom systéme neustále meniť. Hodnota atribútu secureString je 27924505. Heslo platí nie len na testovanie, ale aj na produkčné prostredie. Nie je vylúčené, že sa heslo v budúcnosti zmení, je teda vhodné ho v pokladničnom systéme urobiť konfigurovateľným a predinštalovaným. Totéž platí aj pre port, ktorý je v súčasnosti nastavený na predvolenú hodnotu 33350.

Demo pokladnica a kolekcia pre Postman

Na vyskúšanie GSA protokolu je k dispozícii Demo pokladnica, ktorá simuluje správanie pokladničného systému. Demo pokladnicu otvorte v prehliadači Firefox (v Chrome spojenie s terminálom nefunguje). Protokol URL adresy demo pokladnice musí byť HTTP, nie HTTPS. Na prihlásenie zadajte IP a číslo portu terminálu a potom vyššie uvedené heslo. Na úspešné spojenie musia byť terminál aj počítač pripojené v rovnakej lokálnej sieti. V Demo pokladnici je možné si v hornom menu vybrať GSA protokol v1 alebo v2 a zobraziť si kompletnú REQUEST – RESPONSE komunikáciu medzi pokladnicou a terminálom. Ďalej môžete využiť pripravenú kolekciu do aplikácie Postman.

Verzia GSA API

Terminál prostredníctvom platobnej aplikácie Switchio Pay ponúka niekoľko verzií GSA API protokolu. Verziu si môžete vybrať, odporúčame použiť čo najvyššiu. Zároveň je ale potrebné mať na pamäti, že staršie verzie platobnej aplikácie Switchio Pay nepodporajú najnovšie verzie GSA API (viď tabuľka APPLICATION VERSION HISTORY v dokumentácii). Na zistenie najvyššej dostupnej verzie GSA API na konkrétnom termináli možno využiť napríklad volanie endpointu "info". Je potrebné vykonať iteráciu pomocou GET požiadavku na adresu endpointu od najvyššej verzie smerom k najnižšej (podľa dokumentácie):

1. GET http://{ip_adresa_terminalu}:{port}/api/switchio/pay/v8/info
2. GET http://{ip_adresa_terminalu}:{port}/api/switchio/pay/v7/info
3. GET http://{ip_adresa_terminalu}:{port}/api/switchio/pay/v6/info
4. GET http://{ip_adresa_terminalu}:{port}/api/switchio/pay/v5/info
5. GET http://{ip_adresa_terminalu}:{port}/api/switchio/pay/v4/info
6. GET http://{ip_adresa_terminalu}:{port}/api/switchio/pay/v2/info
7. GET http://{ip_adresa_terminalu}:{port}/paya/info

V prípade, že terminál verziu protokolu podporuje, tak vráti ako odpoveď s hlavičkou 200 OK objekt JSON obsahujúci meno a použitú verziu protokolu a ID terminálu, v opačnom prípade vráti terminál text "Endpoint not supported." a hlavičku HTTP 404 Not Found.

Pozn.: Terminály pravidelne aktualizujeme, všetky by mali podporovať aspoň verziu v2, prípadne je vždy možné v termináli aktualizovať platobnu aplikáciu Switchio Pay na vyššiu verziu tak, aby bolo umožnené dosiahnutie požadovanej vyššej verzie protokolu GSA API.

Atribút transactionId

Tento atribút, ktorý je vždy generovaný pokladnicou, slúži ako jedinečné ID životného cyklu jednej operácie. Teda napríklad v prípade platby je potrebné pre všetky požiadavky na /payment, /status, /result aj /confirm použiť rovnaký transactionId. Ak ale bude táto platba následne pokladnicou stornovaná, ide už o ďalšiu operáciu a je potrebné pre ňu vygenerovať nový transactionId. Hodnota atribútu transactionId musí byť pre každú operáciu jedinečná (minimálne v rámci jednej uzávierky). Odporúčame vygenerovať náhodný UUID zložený len z "neškodných" znakov a-z, A-Z, 0-9 alebo znak "-" (žiadna diakritika ani wildcards atď.), nicméne formát transactionId nie je striktne určený.

Zisťovanie stavu prebiehajúcej transakcie

Volanie stavu transakcie (endpoint /status) odporúčame spočiatku vykonať po 3 sekundách od založenia transakcie a potom cyklicky po cca 200–500 milisekundách. Akonáhle je vrátený stav Finished, je možné načítať výsledok transakcie z endpointu /result.

Potvrdenie transakcie

Každá na termináli úspešne autorizovaná transakcia vyžaduje potvrdenie z pokladnice, že výsledok transakcie prijala (endpoint /confirm). Pri čakaní na túto požiadavku beží na termináli odpočet času 60 sekúnd. Ak z pokladnice nie je transakcia potvrdená pomocou /confirm do tejto doby od úspešnej autorizácie, bude transakcia automaticky stornovaná. Zároveň vždy overte, že v odpovedi na vašu /confirm požiadavku je vrátený atribút isConfirmed s hodnotou true. Je-li vrátené false, transakcia nebola potvrdená a pravdepodobne už bola reverzovaná.

Storno transakcie

Pri zakládaní storna (endpoint /reverse) uveďte do atribútu originalTransactionId pôvodnú transactionId platby, ktorú chcete stornovaní. Ak tento atribút nevyplníte, bude stornovaná posledná vykonaná transakcia. Stornovaní transakcie je možné len do vykonania účetnej uzávierky a len z pokladničného systému. U staršej platby je následne možné vrátenie finančných prostriedkov iba pomocou refundácie, ak je na termináli povolená, popr. v Klientskom portáli.

Predautorizácia

Po vykonanej predautorizácii už nie je možné transakciu zrušiť volaním /reverse, nýbrž volaním /preauth/cancel. Ak predautorizácia nie je dokončená pomocou /preauth/complete, po niekoľkých dňoch sa automaticky zruší. Inkrementálna predautorizácia (/preauth/increment – navýšenie čiastky predautorizácie) ani dekrementálna predautorizácia (/preauth/decrement – poníženie čiastky predautorizácie) nie sú podporované.

Overenie podpisu na karte

Ak nie je nastavený tlač účtov na termináli (účty teda tlačí len pokladnica) a nevyžiada-li si terminál 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 a jeho obsluhe. V endpointu /result bude v atribúte cvmTypeList vrátená v poli hodnota SIGNATURE. Na účte z pokladničného systému by mal byť pre takýto prípad vyžiadaný podpis, obsluha by mala byť pokladničným systémom vyzvaná na kontrolu podpisu s podpisom na karte. Ak sa podpis na účte nezhoduje s podpisom na karte, je potrebné platbu na termináli z pokladnice následne stornovaní.

Overenie výsledného stavu transakcie

Overenie stavu transakcie pomocou endpointu /transaction_status môže v podstate pomôcť predovšetkým v prípade, keď sa rozpadne sieťová komunikácia medzi terminálom a pokladnicou v okamihu, keď už došlo k autorizácii transakcie, ale následne sa už nepodarilo z pokladnice odoslať požiadavku /confirm, prípadne nedošlo k vráteniu odpovede na túto požiadavku. Môžu nastať 2 situácie:

1. požiadavka /confirm na terminál dorazila a transakcia je úspešne uzavretá, len nedorazila odpoveď s "isConfirmed: true" späť do pokladnice,
2. požiadavka /confirm na terminál ani nedorazila a terminál platbu po 60 sekundách automaticky stornoval.

Následne (prípadne neskôr, až bude sieťové spojenie na terminál opäť aktívne) je možné si vyžiadať pomocou terminálu stav transakcie z autorizačného hostu. Je potrebné počítať s časovou prodlevou podľa bodu b), potom možno už stav transakcie považovať za finálny.

Stav transakcie možno získať nasledujúcim postupom. V prvom kroku je potrebné pomocou endpointu /transaction_status vyžiadať na termináli zistenie stavu transakcie. Terminál vráti v odpovedi JSON vo tvare:

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

Ak terminál vráti iné údaje pre isStarted a status, vyžiadanie stavu transakcie nebolo z nejakého dôvodu úspešné (napríklad isStarted: false, status: Server busy značí nedokončenú operáciu, typicky napríklad je-li na termináli zobrazený dopyt na tlač účtu pre zákazníka).

Následne je potrebné zavolať endpoint /result, ktorý vráti údaje o transakcii. Tu je potrebné skontrolovať, že parameter transactionType má hodnotu TRANSACTION_STATUS!

Ak bola transakcia úspešne v poriadku dokončená, potom v responseCode bude hodnota OK a v responseMessage text potvrdené. Ak ale bola transakcia stornovaná, v responseCode bude hodnota TransactionReversed a v responseMessage bude text Transakcia reverzovaná!.

Pozn.: TransactionType = TRANSACTION_STATUS je vracané len pri prvom volaní endpointu /result nasledujúcom po volaní endpointu /transaction_status a len v ňom je správny stav transakcie. Zisťovanie stavu transakcie možno vykonávať len do vykonania uzávierky na termináli, potom (alebo v prípade nenalezenia transakcie) je vracený responseCode s hodnotou TransactionCardholderAuthorizationDataNotFound a stav transakcie už nie je v takom prípade možné overiť.

Prepojenie cez cloud (GSA+)

GSA+ protokol umožňuje ovládať terminály z pokladničného či iného obchodného systému cez internet v podstate rovnakým spôsobom, ako pomocou pôvodného protokolu GSA po lokálnej sieti. Toto riešenie je možné využiť predovšetkým v situácii, keď už máte v pokladničnom systéme implementovanú komunikáciu protokolom GSA cez lokálnu sieť a relatívne drobnými úpravami možno ľahko prejsť na komunikáciu s terminálom cez internet. Ak však začínate s novou integráciou prepojenia pokladnice a terminálu, namiesto GSA+ riešenia použite prosím REST API – CloudPOS.

Zabezpečenie

Na zaistenie integrity a dôvernosti prenášaných údajov prebieha veškerá komunikácia výlučne cez šifrovaný protokol HTTPS. Každá požiadavka musí obsahovať autorizačnú hlavičku. Prístup ku všetkým metódam API musí byť tiež povolený len z predtým nastavených (rozsahov) IP adries.

Implementácia

Na implementáciu je možné vychádzať z vyššie uvedených informácií a dokumentácie GSA protokolu (na komunikáciu v lokálnej sieti), na využitie internetového GSA+ je však potrebné oproti dokumentácii vykonať niekoľko nasledujúcich zmien:

1. Je potrebné upraviť začiatok volanej adresy endpointov tak, že namiesto pôvodných adries http://{ip_terminalu}:{port}/paya/, prípadne http://{ip_terminalu}:{port}/api/switchio/pay/v{x}/ bude nová adresa začínať https://payments.comgate.cz/ecr/api/v1.0/
2. Zároveň každá požiadavka musí obsahovať autorizačnú HTTP hlavičku vo tvare Authorization: Basic [base64_encode(merchant:secret)]. Parameter 'merchant' je login do konkrétneho terminálu a 'secret' je heslo. Tieto údaje nájde klient v Klientskom portáli v sekcii Integrácia – Nastavenie obchodov – záložka Terminály. Zároveň tu možno pre každý terminál nastaviť aj rozsahy povolených IP adries na prístup k API (IP adresa alebo adresy, z ktorých môže cez API komunikovať pokladnica s daným terminálom). Každý príchodzí požiadavka z IP adresy mimo nastavený rozsah bude zamietnutá.
3. Nie je nutné naďalej posielať v požiadavkách atribút 'secureString' (ale môže v požiadavkách aj zostať).
4. Na správnu konfiguráciu terminálu je potrebné, aby Comgate od klienta (prípadne od dodávateľa pokladničného systému) dostal informáciu, či pokladničný systém bude s terminálom komunikovať lokálne po miestnej sieti (GSA) alebo vzdialenosť cez internet (GSA+) – a to predovšetkým v prípadoch, keď pokladničný systém využívaný klientom podporuje oba dva spôsoby komunikácie.

Informácie

Upozornenie: GSA+ protokol teraz nepodporuje žiadne endpointy s callbackom ani endpoint /cancel na zrušenie transakcie čakajúcej na kartu alebo užívateľský vstup.

Odpoveď z API môže byť okrem HTTP 200 OK aj nasledovná:

• HTTP 401 Unauthorized (v prípade nesprávnych údajov merchant/secret),
• HTTP 403 Forbidden (v prípade požiadavky z nepovolené IP adresy)
• HTTP 400 Bad Request (v prípade nesprávne zaslaných parametrov)
• HTTP 500 Internal Server Error v prípade inej chyby

Časté otázky

Ako z pokladnice vyvolať priebežnú uzávierku (mezisoučet)?

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

Aký je rozdiel medzi mezisouč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 na termináli k vynulovaní súčtov transakcií a vymazaniu transakcií z histórie. Každá ďalšia transakcia sa promítne už v novej uzávierke. Mezisoučet slúži na priebežné overenie súčtu transakcií. Mezisoučet vykoná súčet transakcií, ktoré na termináli prebehli v časovom úseku od poslednej uzávierky. Medzi dvoma uzávierkami je možno vykonávať ľubovoľný počet mezisoučtov. Stavy transakcií ani záznamy o transakcií sa vykonaním mezisoučtu nemažu, mezisouč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äť platiteľovi. Refundácia môže byť vyvolaná z rôznych dôvodov, ako sú vrátenie tovaru alebo služby alebo v prípade, keď platiteľ nesúhlasí s vykonanou platbou a vyžaduje jej vrátenie. Refundácia nie je viazaná na konkrétnu transakciu alebo kartu, možno vrátiť ľubovoľnú čiastku na ľubovoľnú kartu. Reversal resp. storno je situácia, keď sa transakcia zruší a finance sa vrátia späť na účet platiteľa. Reversal sa vzťahuje na určitú transakciu a platiteľovi je vždy vrátená celá čiastka tejto transakcie. Na reversal nie je potrebná interakcia s platobnou kartou.

Aké meny umí terminál?

Podporované meny sú v súčasnosti EUR (978) a CZK (203). Numerický kód meny (currencyCode) vychádza z ISO-4217, kompletný zoznam je napríklad tu. Možnosť platby v EUR však záleží na nastavení na strane Comgate pre konkrétny terminál. U klientov na Slovensku je to naopak, štandardne majú k dispozícii EUR, naopak mena CZK je nastavovaná individuálne.

Je možné upraviť nastavenie tlače účtu z terminálu?

Áno, tlač účtov je možné na každom termináli vypnúť alebo upraviť na želanie klienta nastavením na strane Comgate – možno tlačiť účty len pre zákazníka, len pre obchodníka, pre obchodníka aj zákazníka alebo netlačiť žiadne účty. Z bežnej praxe je vhodné doklady tlačiť prostredníctvom pokladnice a klienti môžu požiadať Comgate o zrušenie tlače účtov z terminálu. Ak je na termináli nastavená tlač účtov aj pre zákazníka, nebude možné vykonať novú operáciu s terminálom do doby, kým nebude vyporiadeaná tlačiareňová fronta (terminál sa po vykonaní transakcie pýta na tlač účtu pre zákazníka).

Aké sú náležitosti účtu?

• Dátum vykonania platby
• Číslo účtu
• Označenie obchodníka
• Adresa prevádzky
• IČ/DIČ
• Vymaskované číslo použitej karty
• Čiastka

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

Terminál umožňuje zadávať spropitné priamo na displeji alebo je možné spropitné definovať priamo z pokladnice pri iniciácii platby v atribúte "tipAmount". Povolenie funkcie spropitného je nastavované zo strany Comgate, nicméne v predvolenom nastavení Comgate spropitné na termináloch s pokladničnými systémami nezapína. V prípade povolenia aktívneho spropitné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 pokladnice na termináli transakcia zakládaná (v prípade že bola transakcia založená z pokladnice bez nastaveného spropitného), a musí vedieť tento rozdiel správne zaúčtovať ako spropitné. Výška spropitného je vrátená v atribúte "tipAmount" v endpointu /result. Ak chcete spropitné na termináli vo vašej integrácii riešiť, informujte nás prosím o tejto skutočnosti, abychom povolili možnosť nastaviť spropitné klientom s vaším pokladničným systémom.