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

logoSvg
string or null

Vektorová varianta toho istého loga, alebo null, keď ju pre metódu nemáme. Ponúka sa VEDĽA logo, nie namiesto neho, aby klientom, ktorí vedia dekódovať len raster, logo nezhaslo - logo zostáva PNG. WARN: pomer strán sa od rastra líši (PNG 120x32, teda 3,75:1; vektory 2:1, BANK_CZ_T_PB 2,70:1), takže prepnutie znamená prepočítať aj rámec, do ktorého sa kreslí.

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. Ide na výpis obchodníka, pokiaľ nie je vyplnený variableSymbol - ten potom zaujme jeho miesto. V odpovediach ju vraciame nezmenenú tak i tak.

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

variableSymbol
string <= 128 characters

Nepovinný variabilný symbol zadaný obsluhou, teda vlastná referencia obchodníka uložená k platbe. Ľubovoľný text do 128 bajtov; dlhšia hodnota alebo NUL vracia 400. Keď je vyplnený, je to on, čo sa objaví na výpise obchodníka (stĺpec „ID od klienta“) a refId sa eviduje pri platbe vedľa neho; keď vyplnený nie je, ide na výpis refId. V odpovediach sa refId vracia nezmenený tak či tak. Hodnota s najviac desiatimi číslicami sa navyše ukladá do vlastného stĺpca variabilného symbolu platby. Do QR kódu sa NEDOSTANE - pre párovanie prichádzajúcich peňazí si platba generuje vlastný variabilný symbol.

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",
  • "variableSymbol": "FAKTURA-2026/01"
}

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 zrušenia platby; iba pri platbe v stave CANCELLED. Hodnoty sú stabilné a dajú sa použiť ako kľúče: Customer timeout (platba expirovala), Canceled by merchant (zrušená cez /cancel), Canceled by payer, Canceled by provider, Provider timeout, Fraud suspected a Not specified. Inú hodnotu berte ako neuvedený dôvod.

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

<span class=\'cg-lang cg-lang-en\'>Change the bank on a pending payment</span><span class=\'cg-lang cg-lang-cs\'>Změna banky na rozdělané platbě</span><span class=\'cg-lang cg-lang-sk\'>Zmena banky na rozrobenej platbe</span>

<span class='cg-lang cg-lang-en'>Rewrites the payment method on an EXISTING pending payment and restarts its expiry, so that going back to the bank list does not create a second payment for one purchase. The response has the same shape as creating a payment, plus the new expiry. Nothing is written until every check passes, so a rejected request leaves the payment usable with its ORIGINAL method - pick another bank and call again. The number of changes is not limited and the expiry is never shortened. Amount limits are not re-checked here: the amount does not change, so the list from /methods still applies.<span class='cg-lang cg-lang-cs'>Přepíše metodu na EXISTUJÍCÍ rozdělané platbě a spustí její expiraci znovu, aby návrat k seznamu bank nevyrobil na jednu útratu druhou platbu. Odpověď má stejný tvar jako založení platby plus novou expiraci. Dokud neprojdou všechny kontroly, nezapisuje se nic, takže po odmítnutí platba dál platí s PŮVODNÍ metodou - stačí vybrat jinou banku a zavolat znovu. Počet změn omezený není a expirace se nikdy nezkrátí. Limity částky se tu znovu nekontrolují: částka se nemění, takže platí seznam ze /methods.<span class='cg-lang cg-lang-sk'>Prepíše metódu na EXISTUJÚCEJ rozrobenej platbe a spustí jej expiráciu znova. Po odmietnutí platba ďalej platí s PÔVODNOU metódou.

Authorizations:
bearerAuth
path Parameters
transId
required
string
Example: AA25-FD8D-9GF5
Request Body schema: application/json
required
method
required
string

<span class='cg-lang cg-lang-en'>Method identifier from /methods.<span class='cg-lang cg-lang-cs'>Identifikátor metody ze /methods.<span class='cg-lang cg-lang-sk'>Identifikátor metódy zo /methods.

Responses

Response Schema: application/json
transId
string
refId
string or null
status
string
paymentData
string

<span class='cg-lang cg-lang-en'>QR payload to redraw. Today it does not depend on the chosen bank, but it is returned so that a future change does not need both sides to be updated.<span class='cg-lang cg-lang-cs'>Data QR kódu k překreslení. Dnes na zvolené bance nezávisí, vrací se proto, aby budoucí změna neznamenala úpravu na obou stranách.<span class='cg-lang cg-lang-sk'>Dáta QR kódu na prekreslenie.

expiration
string <date-time>
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.

Response Schema: application/json
errorMessage
string

Chybová správa.

Request samples

Content type
application/json
{
  • "method": "BANK_CZ_T_KB"
}

Response samples

Content type
application/json
{
  • "transId": "AA25-FD8D-9GF5",
  • "refId": "string",
  • "status": "PENDING",
  • "paymentData": "string",
  • "expiration": "2026-09-22T15:10:00+02:00"
}

Predĺženie expirácie platby

Predĺži expiráciu nepotvrdenej platby na 7 dní pre prípad, že obchodník vydal tovar, hoci platbu nepotvrdil. Platba zostáva očakávaná a párovateľná, takže po príchode peňazí sa štandardnou cestou preklopí na zaplatenú. Dĺžku určuje server, volajúci ju nevolí. Volanie je idempotentné a expiráciu nikdy neskráti. Zaplatená platba vráti 200 bez zmeny (peniaze medzitým dorazili), zrušená 400 — nevzkriesi sa a neskoré peniaze idú dnešným procesom do vratky.

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

Identifikátor transakcie.

Request Body schema: application/json
optional
note
string <= 1000 characters

Nepovinná poznámka obchodníka uložená k platbe, napr. kontakt na zákazníka.

Responses

Response Schema: application/json
transId
string

Identifikátor transakcie.

refId
string

Referencia platby.

status
string

Stav platby.

expiration
string

Nová expirácia platby (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.

Response Schema: application/json
errorMessage
string

Chybová správa.

Request samples

Content type
application/json
{
  • "note": "Zákazník: 777123456"
}

Response samples

Content type
application/json
{
  • "transId": "AAAA-BBBB-CCCC",
  • "refId": "ORDER-2026-001",
  • "status": "PENDING",
  • "expiration": "2026-09-08T10:00:00+02:00"
}

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.

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

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