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.
Testovacie platby sa dokončujú automaticky približne 10 sekúnd po založení podľa sumy: do 2 000 CZK / 80 EUR vrátane prejde platba do stavu 'PAID', vyššia suma do 'CANCELLED'. Refundácie testovacích platieb sa dokončujú rovnako: suma 0,01 (1 v minoritných jednotkách) skončí ako 'CANCELLED', akákoľvek iná ako 'REFUNDED'.

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)]. V JSON body je POVINNÝ identifikátor obchodníka mid (bez neho 400) — zapečie sa do tokenu a všetky nadväzujúce operácie QR API sú obmedzené na tohto obchodníka (requesty na iného obchodníka či platby iného obchodníka vracajú 403).

Authorizations:
basicAuth
Request Body schema: application/json
required
mid
required
string

Identifikátor obchodníka zapečený do tokenu (MID scoping).

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.

Response Schema: application/json
errorMessage
string

Chybová správa.

Request samples

Content type
application/json
{
  • "mid": "MERCH001"
}

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 \

Dostupné platobné metódy

Vráti QR platobné metódy dostupné pre daný terminál a menu (QR metódy jednotlivých bánk a generický QR prevod) vrátane názvov a lôg bánk. Pri EUR sa ponuka riadi krajinou prevádzky (SK → SK QR metóda, inak EU QR metóda); s parametrom bothEurQr sa vrátia SK aj EU QR metódy. Metódy sa filtrujú aj podľa podporovanej sumy a limitov okamžitých platieb podľa povinného amount.

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

Identifikátor obchodníka.

terminalId
required
string

Identifikátor terminálu.

currency
required
string

Kód meny podľa ISO 4217 (CZK alebo EUR).

amount
required
integer >= 1

Suma v minoritných jednotkách (haliere/centy) — filtruje metódy podľa podporovanej sumy a limitov okamžitých platieb.

bothEurQr
boolean

Nepovinné; pri EUR vráti SK aj EU QR metódy bez ohľadu na krajinu prevádzky.

lang
string

Nepovinný jazyk názvov metód (cs/sk/en, predvolený cs).

Responses

Response Schema: application/json
Array of objects
Array
id
string

Identifikátor metódy — odovzdáva sa ako method pri založení platby.

name
string

Lokalizovaný názov metódy.

logo
string

URL loga metódy/banky. Použite hodnotu z odpovede — názov súboru nezodpovedá identifikátoru metódy (logo banky je spoločné s platobnou bránou).

Response Schema: application/json
errorMessage
string

Chybová správa.

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",
  • "currency": "CZK",
  • "amount": 12500,
  • "bothEurQr": false,
  • "lang": "cs"
}

Response samples

Content type
application/json
{}

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 >= 1

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. BANK_CZ_T_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

Dáta platobného QR kódu; formát podľa metódy: SPAYD pre CZ metódy, PAY by square pre BANK_SK_T_OTHER, EPC QR (SEPA) pre BANK_EUR_T_OTHER. 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.

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": "BANK_CZ_T_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.

Array of objects

Refundácie tejto platby v chronologickom poradí; bez refundácií prázdne pole. Slúži na dohľadanie transRefundId v prípade, že sa vám odpoveď na založenie refundácie nedoručila. Obsahuje iba údaje známe pri založení — aktuálny stav refundácie zistíte cez GET /pos/qr-api/payment/{transId}/refund/{transRefundId}.

Response Schema: application/json
errorMessage
string

Chybová správa.

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

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.

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"
}

Založenie refundácie

Založí požiadavku na refundáciu platby. Refundovať je možné len zaplatenú (PAID) platbu. Je možná čiastočná aj plná refundácia; súčet refundácií nesmie presiahnuť sumu platby. Požiadavka sa spracováva asynchrónne — výsledok sledujte cez GET /pos/qr-api/payment/{transId}/refund/{transRefundId}.

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

Identifikátor transakcie.

Request Body schema: application/json
required
amount
required
integer >= 1

Suma refundácie v minoritných jednotkách.

created
required
string

Čas vytvorenia refundácie (ISO 8601).

refId
string

Nepovinná referencia refundácie na strane obchodníka — refundáciu s platbou páruje transId v URL.

Responses

Response Schema: application/json
transRefundId
string

Identifikátor refundácie.

status
string

Stav refundácie; ihneď po založení je PENDING.

transId
string

Identifikátor transakcie.

refId
string

Referencia refundácie (echo z requestu).

Response Schema: application/json
errorMessage
string

Chybová správa.

Response Schema: application/json
errorMessage
string

Chybová správa.

Response Schema: application/json
errorMessage
string

Chybová správa.

Response Schema: application/json
errorMessage
string

Chybová správa.

Request samples

Content type
application/json
{
  • "amount": 12500,
  • "created": "2026-05-27T10:05:00Z",
  • "refId": "REFUND-2026-001"
}

Response samples

Content type
application/json
{
  • "transRefundId": "123456",
  • "status": "PENDING",
  • "transId": "AAAA-BBBB-CCCC",
  • "refId": "REFUND-2026-001"
}

Stav refundácie

Vráti stav refundácie. Možné stavy: PENDING (v spracovaní), REFUNDED (peniaze odoslané späť), CANCELLED (refundácia zamietnutá/stornovaná).

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

Identifikátor transakcie.

transRefundId
required
string
Example: 123456

Identifikátor refundácie.

Responses

Response Schema: application/json
transRefundId
string

Identifikátor refundácie.

status
string

Stav refundácie: PENDING / REFUNDED / CANCELLED.

transId
string

Identifikátor transakcie.

refId
string

Referencia refundácie na strane obchodníka.

Response Schema: application/json
errorMessage
string

Chybová správa.

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}/refund/{transRefundId} \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJNT05FVCJ9.dummy-signature'

Response samples

Content type
application/json
{
  • "transRefundId": "123456",
  • "status": "PENDING",
  • "transId": "AAAA-BBBB-CCCC",
  • "refId": "REFUND-2026-001"
}