GSA API

Comgate aktuálně umožňuje 2 způsoby využití GSA protokolu – primárně jej lze využít pro komunikaci pokladny s terminálem v lokální síti, případně i přes cloudové řešení (GSA+).

Propojení přes lokální síť (GSA)

Komunikace pokladny s terminálem probíhá pomocí jednoduchého REST API zasíláním HTTP požadavků ve formátu JSON na IP adresu a port terminálu v lokální síti. Dokumentace k protokolu GSA pro propojení s pokladnou je zde.

Implementace a doporučené postupy

Obě zařízení (terminál i pokladna) musí být připojené ve stejné lokální síti. Pro komunikaci je potřeba používat protokol HTTP (nikoliv HTTPS). Jsou podporovány tyto operace:

• Získání stavu terminálu
• Platba
• Refundace (pouze u vybraných klientů)
• Předautorizace a její dokočení či zrušení (bez inkrementální/dekrementální, pouze u vybraných klientů)
• MOTO platby (pouze u vybraných klientů pro omezené účely)
• Storno (reverzal) transakce
• Získání stavu transakce
• Zrušení platby čekající na kartu či PIN
• Uzávěrka

Minimální implementace by měla zahrnovat alespoň Platbu, Storno a Uzávěrku.

IP adresa, port a heslo (secureString)

Pokladna komunikuje s terminálem pomocí jeho IP adresy. Tu je třeba v pokladním systému znát. Zároveň je vhodné zajistit, aby se IP adresa terminálu v síti neměnila (např. nepoužívat DHCP a nastavit terminálu statickou IP adresu) a nebylo tak třeba IP adresu terminálu v pokladním systému neustále měnit. Hodnota atributu secureString je 27924505. Heslo platí nejen pro testování, ale i pro produkční prostředí. Není vyloučeno, že se heslo v budoucnu změní, je tedy vhodné jej v pokladním systému udělat konfigurovatelné a předvyplněné. Totéž platí i pro port, který je aktuálně nastaven na výchozí hodnotu 33350.

Demo pokladna a kolekce pro Postman

Pro vyzkoušení GSA protokolu je k dispozici Demo pokladna, která simuluje chování pokladního systému. Demo pokladnu otevřete v prohlížeči Firefox (v Chrome spojení s terminálem nefunguje). Protokol URL adresy demo pokladny musí být HTTP, nikoliv HTTPS. Pro přihlášení zadejte IP a číslo portu terminálu a poté výše uvedené heslo. Pro úspěšné spojení musí být terminál i počítač připojeny ve stejné lokální síti. V Demo pokladně je možné si v horním menu vybrat GSA protokol v1 nebo v2 a zobrazit si kompletní REQUEST – RESPONSE komunikaci mezi pokladnou a terminálem. Dále můžete využít připravené kolekce do aplikace Postman.

Verze GSA API

Terminál prostřednictvím platební aplikace Switchio Pay nabízí několik verzí GSA API protokolu. Verzi si můžete vybrat, doporučujeme použít co nejvyšší. Zároveň je ale třeba mít na paměti, že starší verze platební aplikace Switchio Pay nepodporují nejnovější verze GSA API (viz tabulka APPLICATION VERSION HISTORY v dokumentaci). Pro zjištění nejvyšší dostupné verze GSA API na konkrétním terminálu 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/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 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.

Atribut transactionId

Tento atribut, který je vždy generován pokladnou, slouží jako unikátní ID životního cyklu jedné operace. Tedy např. v případě platby je třeba pro všechny požadavky na /payment, /status, /result i /confirm použít stejné transactionId. Pokud ale bude tato platba následně pokladnou stornována, jedná si již o další operaci a je třeba pro ni vygenerovat nové transactionId. Hodnota atributu transactionId musí být pro každou operaci unikátní (minimálně v rámci jedné uzávěrky). Doporučujeme vygenerovat random UUID složené pouze z "neškodných" znaků a-z, A-Z, 0-9 nebo znak "-" (žádná diakritika ani wildcards apod.), nicméně formát transactionId není striktně stanoven.

Zjišťování stavu probíhající transakce

Volání stavu transakce (endpoint /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. Jakmile je vrácen stav Finished, je možné načíst výsledek transakce z endpointu /result.

Potvrzení transakce

Každá na terminálu úspěšně autorizovaná transakce vyžaduje potvrzení z pokladny, že výsledek transakce přijala (endpoint /confirm). Při čekání na tento požadavek běží na terminálu odpočet času 60 vteřin. Pokud z pokladny není transakce potvrzena pomocí /confirm do této doby od úspěšné autorizace, bude transakce automaticky stornována. Zároveň vždy ověřujte, že v odpovědi na váš /confirm požadavek je vrácen atribut isConfirmed s hodnotou true. Je-li vráceno false, transakce nebyla potvrzena a pravděpodobně už byla reverzována.

Storno transakce

Při zakládání storna (endpoint /reverse) uveďte do atributu originalTransactionId původní transactionId platby, kterou chcete stornovat. Pokud tento atribut nevyplníte, bude stornována poslední provedená transakce. Stornovat transakci lze pouze do provedení účetní uzávěrky a pouze z pokladního systému. U starší platby je následně možné vrácení finančních prostředků pouze pomocí refundace, je-li na terminálu povolena, popř. v Klientském portálu.

Předautorizace

Po provedené předautorizaci již není možné transakci zrušit voláním /reverse, nýbrž voláním /preauth/cancel. Pokud předautorizace není dokončena pomocí /preauth/complete, po několika dnech se automaticky zruší. Inkrementální předautorizace (/preauth/increment – navýšení částky předautorizace) ani dekrementální předautorizace (/preauth/decrement – ponížení částky předautorizace) nejsou podporovány.

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 a jeho obsluze. 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.

Ověření výsledného stavu transakce

Ověření 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 /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 pomocí terminálu stav transakce z autorizačního hostu. 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 hodnota OK a v 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.

Propojení přes cloud (GSA+)

GSA+ protokol umožňuje ovládat terminály z pokladního či jiného obchodního systému přes internet v podstatě stejným způsobem, jako pomocí původního protokolu GSA po lokální síti. Toto řešení je možné využít zejména v situaci, kdy již máte v pokladním systému implementovanou komunikaci protokolem GSA přes lokální síť a relativně drobnými úpravami lze snadno přejít na komunikaci s terminálem přes internet. Pokud však začínáte s novou integrací propojení pokladny a terminálu, místo GSA+ řešení použijte prosím REST API – CloudPOS.

Zabezpečení

Pro zajištění integrity a důvěrnosti přenášených dat probíhá veškerá komunikace výhradně přes šifrovaný protokol HTTPS. Každý požadavek musí obsahovat autorizační hlavičku. Přístup ke všem metodám API musí být také povolen pouze z předem nastavených (rozsahů) IP adres.

Implementace

Pro implementaci je možné vycházet z výše uvedených informací a dokumentace GSA protokolu (pro komunikaci v lokální síti), pro využití internetového GSA+ je však potřeba oproti dokumentaci provést několik následujících změn:

1. Je potřeba upravit začátek volané adresy endpointů tak, že místo původních adres http://{ip_terminalu}:{port}/paya/, popř. http://{ip_terminalu}:{port}/api/switchio/pay/v{x}/ bude nově adresa začínat https://payments.comgate.cz/ecr/api/v1.0/
2. Zároveň každý požadavek musí obsahovat autorizační HTTP hlavičku ve tvaru Authorization: Basic [base64_encode(merchant:secret)]. Parametr 'merchant' je login ke konkrétnímu terminálu a 'secret' je heslo. Tyto údaje najde klient v Klientském portálu v sekci Integrace – Nastavení obchodů – záložka Terminály. Zároveň zde lze pro každý terminál nastavit i rozsahy povolených IP adres pro přístup k API (IP adresa nebo adresy, ze kterých může přes API komunikovat pokladna s daným terminálem). Každý příchozí požadavek z IP adresy mimo nastavený rozsah bude zamítnut.
3. Není nutné nadále posílat v požadavcích atribut 'secureString' (ale může v požadavcích i zůstat).
4. Pro správnou konfiguraci terminálu je potřeba, aby Comgate od klienta (popř. od dodavatele pokladního systému) dostal informaci, zda pokladní systém bude s terminálem komunikovat lokálně po místní síti (GSA) nebo vzdáleně přes internet (GSA+) – a to zejména v případech, kdy pokladní systém používaný klientem podporuje oba dva způsoby komunikace.

Informace

Upozornění: GSA+ protokol nyní nepodporuje žádné endpointy s callbackem ani endpoint /cancel pro zrušení transakce čekající na kartu nebo uživatelský vstup.

Odpověď z API může být krom HTTP 200 OK i následující:

• HTTP 401 Unauthorized (v případě nesprávných údajů merchant/secret),
• HTTP 403 Forbidden (v případě požadavku z nepovolené IP adresy)
• HTTP 400 Bad Request (v případě nesprávně zaslaných parametrů)
• HTTP 500 Internal Server Error v případě jiné chyby

Č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 na terminálu 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 aktuálně EUR (978) a CZK (203). Numerický kód měny (currencyCode) vychází z ISO-4217, kompletní seznam je např. zde. Možnost platby v EUR však záleží na nastavení na straně Comgate pro konkrétní terminál. U klientů na Slovensku je to naopak, standardně mají k dispozici EUR, naopak měna CZK je nastavována individuálně.

Je možné upravit nastavení tisku účtenky z terminálu?

Ano, tisk účtenek je možné na každém terminálu vypnout nebo upravit na přání klienta nastavením na straně Comgate – lze tisknout účtenky jen pro zákazníka, jen pro obchodníka, pro obchodníka i zákazníka nebo netisknout žádné účtenky. 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. Pokud je na terminálu nastaven tisk účtenek i pro zákazníka, nebude možné provést novou operaci s terminálem do doby, než bude vypořádána tisková fronta (terminál se po provedení transakce ptá na tisk účtenky pro zákazníka).

Jaké jsou náležitosti účtenky?

• Datum provedení platby
• Číslo účtenky
• Označení obchodníka
• Adresa provozovny
• IČ/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 nebo je možné spropitné definovat přímo z pokladny při iniciaci platby v atributu "tipAmount". Povolení funkce spropitného 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 (v případě že byla transakce založena z pokladny bez nastaveného spropitného), 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.