Přeskočit na hlavní obsah
API docs by Redocly

Metody terminálového REST API (2.0)

Terminálové REST API slouží k internetovému propojení pokladního nebo jiného obchodního systému s platebním terminálem od Comgate. Umožňuje na dálku zadávat pokyny terminálu, typicky pro zahájení platby a následné zjištění jejího výsledku. V terminálovém REST API podporujeme pouze datový formát JSON. Proces zpracování jedné transakce se obvykle skládá z následujících kroků:

Založení platby (povinný krok)
Pokladní systém zavolá metodu POST /v2.0/terminalPayment.json a předá jí povinné údaje: částku (price), měnu (curr), popř. je možné doplnit referenci platby/variabilní symbol (refId). Pokud je požadavek v pořádku, API vrátí unikátní identifikátor transakce transId. Tento kód si musíte uložit, je klíčový pro všechny další operace s touto platbou.

Zjištění stavu platby (volitelný krok)
Pokladní systém může zjišťovat, jak platba na terminálu dopadla. Opakovaně volejte metodu GET /v2.0/terminalPayment/transId/{transId}.json, dokud se stav (status) nezmění z 'PENDING' na finální hodnotu. Možné finální stavy jsou:

  • PAID - platba proběhla úspěšně,
  • CANCELLED - platba byla zrušena, zamítnuta, neproběhla korektně nebo vypršel čas.
Storno platby (volitelný krok)
Pokud potřebujete již zaplacenou transakci zrušit (např. při okamžitém vrácení zboží), můžete použít metodu DELETE /v2.0/terminalPayment/transId/{transId}.json. Storno lze provést pouze u plateb ve stavu 'PAID' a pouze do provedení uzávěrky na terminálu.

Doplňkové metody

Stav terminálu
Voláním metody GET /v2.0/terminal.json můžete ověřit, zda je terminál online.

Uzávěrka
Metoda POST /v2.0/terminalClosing.json slouží k provedení uzávěrky, která vrátí souhrnné informace o transakcích provedených od předchozí uzávěrky a vymaže historii transakcí v terminálu.

Zabezpečení a autorizace

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. Přístup ke všem metodám API může být povolen pouze z předem schválených IP adres. V takovém případě budou požadavky z jiných IP adres zamítnuty. Každý požadavek musí také obsahovat autorizační hlavičku ve formátu: Authorization: Basic [base64_encode(merchant:secret)]. Parametr 'merchant' je váš přihlašovací identifikátor k terminálu a 'secret' je heslo. Tyto údaje spolu s možnostmi nastavení povolených IP adres pro přístup k API najdete v Klientském portálu v sekci Integrace - Nastavení obchodů - Terminály.

UPOZORNĚNÍ

V současné době připravujeme další metody pro práci s předautorizacemi, refundacemi a MOTO platbami.

Založení platby

header Parameters
authorization
required
string

Autorizační hlavička je ve tvaru: Authorization: Basic [base64_encode(merchant:secret)].

Request Body schema: application/json

Vytvořit novou platbuVytv * orenie novej platby

price
required
integer <int32>

Cena za produkt v centech nebo haléřích. Například pro platbu 10 CZK je třeba použít hodnotu '1000'.
Musí být min. 1 CZK; 0,1 EUR.
Max. 1 000 000 CZK; 40 000 EUR.

curr
required
string

Kód měny dle ISO 4217. K dispozici jsou měny: CZK, EUR.

refId
string

Parametr vhodný k zadaní variabilního symbolu nebo čísla objednávky na straně Klienta (nemusí být unikátní, tzn., že lze založit více plateb se stejným refId). V Klientském portálu a denním csv je parametr označen jako ID Klienta.

Responses

Response Schema: application/json
code
required
integer

Návratový kód metody a popis chyby:
0 OK
1100 neznámá chyba
1107 cena platby není podporovaná
1200 databázová chyba
1301 neznámý terminál
1309 nesprávná částka
1310 neznámá měna
1399 neočekávaný výsledek z databáze
1400 chybný požadavek
1500 neočekávaná chyba

message
required
string
transId
string

Unikátní alfanumerický identifikátor (kód) transakce

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ískání stavu platby eventuálně s detailními daty o transakci (jsou-li k dispozici).

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

Unikátní alfanumerický identifikátor (kód) transakce (transactionId)

header Parameters
authorization
required
string

Autorizační hlavička je ve tvaru: Authorization: Basic [base64_encode(merchant:secret)].

Responses

Response Schema: application/json
code
required
integer

Návratový kód metody

message
required
string

Popis chyby v závislosti na návratovém kódu:
0 OK
1100 neznámá chyba
1200 databázová chyba
1400 chybný dotaz
1500 neočekávaná chyba

v případě code=0 jsou v odpovědi následující parametry:

price
required
string

Cena za produkt v centech nebo haléřích. Například pro platbu 10 CZK bude vrácena hodnota '1000'.

curr
required
string

Kód měny dle ISO 4217

refId
required
string

Reference platby (variabilní sysmbol)

transId
required
string

Unikátní alfanumerický identifikátor (kód) transakce (transactionId)

status
required
string

Aktuální stav transakce, hodnoty
'PENDING' – platba je založena, finální výsledek není známý
'PAID' – platba byla úspěšně zaplacena
'CANCELLED' – platba nebyla dokončena korektně a je zrušena
'AUTHORIZED' – vyžádaná předautorizace proběhla úspěšně

fee
string

Spočítaný poplatek za transakci v centech nebo halířích, případně může nabývat hodnoty 'unknown'. Poplatky za platby jsou dostupné v response nejdříve druhý den na základě reportů zpracovatelů platby.

cardValid
string

Expirace karty plátce ve formátu MM/RR (pokud byla karta použita). Příklad: '04/28'

cardNumber
string

Částečné číslo karty plátce (pokud byla karta použita)

paymentErrorReason
string

Důvod zamítnutí platby (pokud je k dispozici).

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 lze zrušit, dokud není na terminálu vyvolána uzávěrka. Platba musí být úspěšně dokončená (ve stavu 'PAID').
Pokud již byla na terminálu mezitím vyvolána uzávěrka, zobrazí se chyba a je nutné použít metodu 'refund' (pokud je to možné).

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

Unikátní alfanumerický identifikátor (kód) transakce (transactionId)

header Parameters
authorization
required
string

Autorizační hlavička je ve tvaru: Authorization: Basic [base64_encode(merchant:secret)].

Responses

Response Schema: application/json
code
required
integer

návratový kód metody a popis chyby:
0 OK
1400 není možné přepnout platbu do cancelled stavu (platba nenalezena, platba není ve stavu paid, neoprávněný pří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

Zjištění stavu terminálu.

header Parameters
authorization
required
string

Autorizační hlavička je ve tvaru: Authorization: Basic [base64_encode(merchant:secret)].

Responses

Response Schema: application/json
status
required
string

Stav testu připojení k autorizačnímu serveru.
'ONLINE' – terminál je připojen k autorizačnímu serveru.
'OFFLINE' – terminál není připojen k autorizačnímu serveru.
'UNKNOWN' – stav připojení nelze zkontrolovat nebo 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ávěrka

Provede uzávěrku na terminálu. Při uzávěrce dojde k vymazání historie transakcí v terminálu.

header Parameters
authorization
required
string

Autorizační hlavička je ve tvaru: Authorization: Basic [base64_encode(merchant:secret)].

Responses

Response Schema: application/json
code
required
integer

0 - OK, jinak podrobnosti v parametru 'message'

message
required
string

OK nebo textový popis výsledku uzávěrky

batchNumber
integer

Číslo uzávěrky

Array of objects

Seznam souhrnů uzávěrky podle měn

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": [
    ]
}