Skip to main content
API docs by Redocly

Metódy terminálového REST API (2.0)

Terminálové REST API slúžia na internetové prepojenie pokladničného alebo iného obchodného systému s platobným terminálom od Comgate. Umožňuje na diaľku zadávať pokyny terminálu, typicky pre začatie platby a následné zistenie jej výsledku. V terminálovom REST API podporujeme iba dátový formát JSON. Proces spracovania jednej transakcie sa obvykle skladá z nasledujúcich krokov:

Založenie platby (povinný krok)
Pokladničný systém zavolá metódu POST /v2.0/terminalPayment.json a odovzdá jej povinné údaje: čiastku (price), menu (curr), popr. je možné doplniť referenciu platby/variabilný symbol (refId). Pokiaľ je požiadavka v poriadku, API vráti unikátny identifikátor transakcie transId. Tento kód si musíte uložiť, je kľúčový pre všetky ďalšie operácie s touto platbou.

Zistenie stavu platby (voliteľný krok)
Pokladničný systém môže zisťovať, ako platba na termináli dopadla. Opakovane volajte metódu GET /v2.0/terminalPayment/transId/{transId}.json, kým sa stav (status) nezmení z 'PENDING' na finálnu hodnotu. Možné finálne stavy sú:

  • PAID - platba prebehla úspešne,
  • CANCELLED - platba bola zrušená, zamietnutá, neprebehla korektne alebo vypršal čas.
Storno platby (voliteľný krok)
Pokiaľ potrebujete už zaplatenú transakciu zrušiť (napr. pri okamžitom vrátení tovaru), môžete použiť metódu DELETE /v2.0/terminalPayment/transId/{transId}.json. Storno je možné uskutočniť iba pri platbách v stave 'PAID' a iba do vykonania uzávierky na termináli.

Doplnkové metódy

Stav terminálu
Volaním metódy GET /v2.0/terminal.json môžete overiť, či je terminál online.

Uzávierka
Metóda POST /v2.0/terminalClosing.json slúži na vykonanie uzávierky, ktorá vráti súhrnné informácie o transakciách vykonaných od predchádzajúcej uzávierky a vymaže históriu transakcií v termináli.

Zabezpečenie a autorizácia

Pre zaistenie integrity a dôvernosti prenášaných dát prebieha všetka komunikácia výhradne cez šifrovaný protokol. Prístup ku všetkým metódam API môže byť povolený iba z vopred schválených IP adries. V takom prípade budú požiadavky z iných IP adries zamietnuté. Každá požiadavka musí tiež obsahovať autorizačnú hlavičku vo formáte: Authorization: Basic [base64_encode(merchant:secret)]. Parameter 'merchant' je váš prihlasovací identifikátor k terminálu a 'secret' je heslo. Tieto údaje spolu s možnosťami nastavenia povolených IP adries pre prístup k API nájdete v Klientskom portáli v sekcii Integrácia - Nastavenie obchodov - Terminály.

UPOZORNENIE

V súčasnej dobe pripravujeme ďalšie metódy pre prácu s predautorizáciami, refundáciami a MOTO platbami.

Založenie platby

header Parameters
authorization
required
string

Autorizačná hlavička je v tvare: 'Authorization: Basic [base64_encode(merchant:secret)]'. Merchant je login identifikátor e-shopu v systéme Comgate - nájdete v Klientskom portáli v sekcii Integrácia - Nastavenie obchodov - Terminály. Secret je heslo.

Request Body schema: application/json

Vytv * orenie novej platby

price
required
integer <int32>

Cena za produkt v centoch alebo halieroch. Napríklad pre platbu 10 EUR je treba použiť hodnotu '1000'.
Musí byť min. 1 CZK; 0,1 EUR.
Max. 1 000 000 CZK; 40 000 EUR.

curr
required
string

Kód meny podľa ISO 4217. K dispozícii sú meny: EUR, CZK.

refId
string

Parameter vhodný na zadanie variabilného symbolu alebo čísla objednávky na strane Klienta (nemusí byť unikátne, tzn., že možno založiť viac platieb s rovnakým refId). V Klientskom portáli a denným csv je parameter označený ako ID Klienta.

Responses

Response Schema: application/json
code
required
integer

Návratový kód metódy a popis chyby:
0 OK
1100 neznáma chyba
1107 cena platby nie je podporovaná
1200 databázová chyba
1301 neznámy terminál
1309 nesprávna čiastka
1310 neznáma mena
1399 neočakávaný výsledok z databázy
1400 chybná požiadavka
1500 neočakávaná chyba

message
required
string
transId
string

Unikátny alfanumerický identifikátor (kód) transakcie

Request samples

Content type
application/json
{
  • "price": 1000,
  • "curr": "CZK",
  • "refId": "2010102600"
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "OK",
  • "transId": "AB12-CD34-EF56"
}

Stav platby

Získanie stavu platby eventuálne s detailnými dátami o transakcii (ak sú k dispozícii).

path Parameters
transId
required
string
Example: AAAA-BBBB-CCCC

Unikátny alfanumerický identifikátor (kód) transakcie (transactionId)

header Parameters
authorization
required
string

Autorizačná hlavička je v tvare: 'Authorization: Basic [base64_encode(merchant:secret)]'. Merchant je login identifikátor e-shopu v systéme Comgate - nájdete v Klientskom portáli v sekcii Integrácia - Nastavenie obchodov - Terminály. Secret je heslo.

Responses

Response Schema: application/json
code
required
integer

Návratový kód metódy

message
required
string

Návratový kód metódy a popis chyby:
0 OK
1100 neznáma chyba
1200 databázová chyba
1400 chybný dotaz
1500 neočakávaná chyba

v prípade code = 0 sú v odpovedi nasledujúce parametre:

price
required
string

Cena za produkt v centoch alebo halieroch. Napríklad pri platbe 10 EUR bude vrátená hodnota '1000'.

curr
required
string

Kód meny podľa ISO 4217

refId
required
string

Referencia platby (variabilný symbol)

transId
required
string

Unikátny alfanumerický identifikátor (kód) transakcie (transactionId)

status
required
string

Aktuálny stav transakcie, hodnoty
PENDING - platba je založená, finálny výsledok nie je známy
PAID - platba bola úspešne zaplatená
CANCELLED - platba nebola dokončená korektne a je zrušená
Authorized - vyžiadaná predautorizácia prebehla úspešne

fee
string

Spočítaný poplatok za transakciu v centoch alebo halieroch, prípadne môže obsahovať hodnotu 'unknown'. Poplatky za platby sú dostupné v response najskôr druhý deň na základe reportov spracovateľov platby.

cardValid
string

Expirácia karty platiteľa vo formáte MM/RR (pokiaľ bola karta použitá). Príklad: '04/28'

cardNumber
string

Čiastočné číslo karty platiteľa (pokiaľ bola karta použitá)

paymentErrorReason
string

Dôvod zamietnutia platby (ak je k dispozícii).

Request samples 

# You can also use wget
curl -X GET https://payments.comgate.cz/v2.0/terminalPayment/transId/{transId}.json \
-H 'Authorization: Basic MTIzNDU2Omd4NHE4T1YzVEp0Nm5vSm5maGpxSkt5WDNaNlljaDB5'

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "OK",
  • "price": "1000",
  • "curr": "CZK",
  • "refId": "2010102600",
  • "transId": "AB12-CD34-EF56",
  • "status": "PAID",
  • "fee": "string",
  • "cardValid": "04/28",
  • "cardNumber": "string",
  • "paymentErrorReason": "string"
}

Storno platby

Storno platby
Platbu je možné zrušiť, pokiaľ nie je na termináli vyvolaná uzávierka. Platba musí byť úspešne dokončená (v stave 'PAID').
Ak už bola na termináli medzitým vyvolaná uzávierka, zobrazí sa chyba a je nutné použiť metódu 'refund' (ak je to možné).

path Parameters
transId
required
string
Example: AAAA-BBBB-CCCC

Unikátny alfanumerický identifikátor (kód) transakcie (transactionId)

header Parameters
authorization
required
string

Autorizačná hlavička je v tvare: 'Authorization: Basic [base64_encode(merchant:secret)]'. Merchant je login identifikátor e-shopu v systéme Comgate - nájdete v Klientskom portáli v sekcii Integrácia - Nastavenie obchodov - Terminály. Secret je heslo.

Responses

Response Schema: application/json
code
required
integer

návratový kód metódy a opis chyby:
0 OK
1400 nie je možné prepnúť platbu do cancelled stavu (platba nenájdená, platba nie je v stave paid, neoprávnený prístup)

message
required
string

Request samples 

# You can also use wget
curl -X DELETE https://payments.comgate.cz/v2.0/terminalPayment/transId/{transId}.json \
-H 'Authorization: Basic MTIzNDU2Omd4NHE4T1YzVEp0Nm5vSm5maGpxSkt5WDNaNlljaDB5'

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "OK"
}

Stav terminálu

Zistenie stavu terminálu.

header Parameters
authorization
required
string

Autorizačná hlavička je v tvare: 'Authorization: Basic [base64_encode(merchant:secret)]'. Merchant je login identifikátor e-shopu v systéme Comgate - nájdete v Klientskom portáli v sekcii Integrácia - Nastavenie obchodov - Terminály. Secret je heslo.

Responses

Response Schema: application/json
status
required
string

Stav testu pripojenia k autorizačnému serveru.
'ONLINE' – terminál je pripojený k autorizačnému serveru.
'OFFLINE' – terminál nie je pripojený k autorizačnému serveru.
'UNKNOWN' – stav pripojenia nie je možné skontrolovať alebo je terminál nedostupný.

Request samples 

# You can also use wget
curl -X GET https://payments.comgate.cz/v2.0/terminal.json \
-H 'Authorization: Basic MTIzNDU2Omd4NHE4T1YzVEp0Nm5vSm5maGpxSkt5WDNaNlljaDB5'

Response samples

Content type
application/json
{
  • "status": "ONLINE"
}

Uzávierka

Vykoná uzávierku na termináli. Pri uzávierke dôjde k vymazaniu histórie transakcií v termináli.

header Parameters
authorization
required
string

Autorizačná hlavička je v tvare: 'Authorization: Basic [base64_encode(merchant:secret)]'. Merchant je login identifikátor e-shopu v systéme Comgate - nájdete v Klientskom portáli v sekcii Integrácia - Nastavenie obchodov - Terminály. Secret je heslo.

Responses

Response Schema: application/json
code
required
integer

0 - OK, inak podrobnosti v parametri 'message'

message
required
string

OK alebo textový popis výsledku uzávierky

batchNumber
integer

Číslo uzávierky

Array of objects

Zoznam súhrnov uzávierky podľa mien

Request samples 

# You can also use wget
curl -X POST https://payments.comgate.cz/v2.0/terminalClosing.json \
-H 'Authorization: Basic MTIzNDU2Omd4NHE4T1YzVEp0Nm5vSm5maGpxSkt5WDNaNlljaDB5' \
-H 'Content-Type: application/json'

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "OK",
  • "batchNumber": 1,
  • "batchData": [
    ]
}