Skip to main content
API docs by Redocly

POS QR REST API (1.0)

QR REST API slúži na internetové prepojenie pokladničného alebo iného obchodného systému s Comgate a umožňuje začať QR / účtovú platbu na platobnom termináli a následne zistiť jej výsledok. Podporujeme iba dátový formát JSON. Proces spracovania jednej transakcie sa obvykle skladá z nasledujúcich krokov:

Autentizácia (povinný prvý krok)
Zavolajte metódu POST /pos/auth-api/authenticate s HTTP Basic prihlasovacími údajmi (hlavička Authorization: Basic [base64_encode(user:password)]). API vráti JWT token a jeho expiráciu (expiry). Tento token použite v hlavičke Authorization: Bearer [token] pri všetkých volaniach QR API, kým nevyprší; potom sa autentizujte znova.

Založenie platby (povinný krok)
Zavolajte metódu POST /pos/qr-api/payment a odovzdajte povinné údaje: merchantId, terminalId, amount (v minoritných jednotkách), currency a method; voliteľne refId a created. Pokiaľ je požiadavka v poriadku, API vráti unikátny identifikátor transakcie transId a paymentData na vykreslenie QR kódu. Identifikátor transId uložte, je kľúčový pre všetky ďalšie operácie s touto platbou.

Zistenie stavu platby (voliteľný krok)
Opakovane volajte metódu GET /pos/qr-api/payment/{transId}, 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 zrušiť platbu, ktorá zatiaľ nedosiahla finálny stav, zavolajte metódu POST /pos/qr-api/payment/{transId}/cancel. Odpoveď obsahuje výsledný stav (status 'CANCELLED').

QR API Flow

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 HTTPS a dátový formát je JSON. Každá požiadavka na QR API musí obsahovať autorizačnú hlavičku Authorization: Bearer [token] s platným JWT tokenom získaným z Auth API. Token má obmedzenú platnosť (expiry); po jej vypršaní získajte nový cez POST /pos/auth-api/authenticate.

Auth API

Získanie prístupového tokenu

Overí HTTP Basic prihlasovacie údaje a vráti JWT Bearer token slúžiaci na autorizáciu QR API. Prihlasovacie údaje odovzdajte v hlavičke Authorization: Basic [base64_encode(user:password)].

Authorizations:
basicAuth

Responses

Response Schema: application/json
token
string

JWT Bearer token.

expiry
string

Expirácia tokenu (ISO 8601).

Response Schema: application/json
errorMessage
string

Chybová správa.

Response Schema: application/json
errorMessage
string

Chybová správa.

Request samples 

# You can also use wget
curl -X POST https://payments.comgate.cz/pos/auth-api/authenticate \
-H 'Authorization: Basic MTIzNDU2Omd4NHE4T1YzVEp0Nm5vSm5maGpxSkt5WDNaNlljaDB5' \
-H 'Content-Type: application/json'

Response samples

Content type
application/json
{
  • "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJNT05FVCJ9.dummy-signature",
  • "expiry": "2026-06-18T10:15:00+00:00"
}

Health check

Overenie dostupnosti Auth API. Vracia HTTP 200 s prázdnym telom.

Responses

Request samples 

# You can also use wget
curl -X GET https://payments.comgate.cz/pos/auth-api/ping \

QR API

Health check

Overenie dostupnosti QR API. Vracia HTTP 200 s prázdnym telom.

Responses

Request samples 

# You can also use wget
curl -X GET https://payments.comgate.cz/pos/qr-api/ping \

Založenie platby

Vytvorí novú QR platbu. Pri úspechu vráti identifikátor transakcie transId a dáta platby potrebné na vykreslenie QR kódu.

Authorizations:
bearerAuth
Request Body schema: application/json
required
merchantId
required
string

Identifikátor obchodníka.

terminalId
required
string

Identifikátor terminálu.

refId
string

Nepovinná referencia platby na strane obchodníka.

amount
required
integer

Suma v minoritných jednotkách (haliere/centy).

currency
required
string

Kód meny podľa ISO 4217.

method
required
string

Platobná metóda, napr. QR_T_CZ_OTHER.

created
string

Nepovinný čas vytvorenia platby (ISO 8601).

Responses

Response Schema: application/json
transId
string

Identifikátor transakcie.

refId
string

Referencia platby (echo z requestu).

status
string

Stav platby; ihneď po založení je PENDING.

paymentData
string

Platobný QR kód vo formáte SPAYD. Pri platbe v stave CANCELLED chýba.

paymentRejectedReason
string

Dôvod zamietnutia; iba pri platbe v stave CANCELLED.

Response Schema: application/json
errorMessage
string

Chybová správa.

Response Schema: application/json
errorMessage
string

Chybová správa.

Request samples

Content type
application/json
{
  • "merchantId": "MERCH001",
  • "terminalId": "TERM001",
  • "refId": "ORDER-2026-001",
  • "amount": 12500,
  • "currency": "CZK",
  • "method": "QR_T_CZ_OTHER",
  • "created": "2026-05-27T10:00:00Z"
}

Response samples

Content type
application/json
{
  • "transId": "AAAA-BBBB-CCCC",
  • "refId": "ORDER-2026-001",
  • "status": "PENDING",
  • "paymentData": "SPD*1.0*ACC:CZ6508000000192000145399*AM:125.00*CC:CZK*MSG:Platba ORDER-2026-001",
  • "paymentRejectedReason": "string"
}

Stav platby

Vráti aktuálny stav platby. Dotazujte sa opakovane, kým status nedosiahne finálnu hodnotu (PAID / CANCELLED).

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

Identifikátor transakcie.

Responses

Response Schema: application/json
transId
string

Identifikátor transakcie.

refId
string

Referencia platby na strane obchodníka.

status
string

Stav platby: PENDING, PAID alebo CANCELLED.

paymentRejectedReason
string

Dôvod zamietnutia; iba pri platbe v stave CANCELLED.

Response Schema: application/json
errorMessage
string

Chybová správa.

Response Schema: application/json
errorMessage
string

Chybová správa.

Request samples 

# You can also use wget
curl -X GET https://payments.comgate.cz/pos/qr-api/payment/{transId} \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJNT05FVCJ9.dummy-signature'

Response samples

Content type
application/json
{
  • "transId": "AAAA-BBBB-CCCC",
  • "refId": "ORDER-2026-001",
  • "status": "PAID",
  • "paymentRejectedReason": "string"
}

Zrušenie platby

Zruší platbu. Odpoveď obsahuje výsledný stav (CANCELLED).

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

Identifikátor transakcie.

Responses

Response Schema: application/json
transId
string

Identifikátor transakcie.

status
string

Stav platby.

paymentRejectedReason
string

Dôvod zamietnutia; iba ak bola platba zamietnutá.

Response Schema: application/json
errorMessage
string

Chybová správa.

Response Schema: application/json
errorMessage
string

Chybová správa.

Request samples 

# You can also use wget
curl -X POST https://payments.comgate.cz/pos/qr-api/payment/{transId}/cancel \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJNT05FVCJ9.dummy-signature' \
-H 'Content-Type: application/json'

Response samples

Content type
application/json
{
  • "transId": "AAAA-BBBB-CCCC",
  • "status": "CANCELLED",
  • "paymentRejectedReason": "string"
}