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

POS QR REST API (1.0)

QR REST API slouží k internetovému propojení pokladního nebo jiného obchodního systému s Comgate a umožňuje zahájit QR / účtovou platbu na platebním terminálu a následně zjistit její výsledek. Podporujeme pouze datový formát JSON. Proces zpracování jedné transakce se obvykle skládá z následujících kroků:

Autentizace (povinný první krok)
Zavolejte metodu POST /pos/auth-api/authenticate s HTTP Basic přihlašovacími údaji (hlavička Authorization: Basic [base64_encode(user:password)]). API vrátí JWT token a jeho expiraci (expiry). Tento token použijte v hlavičce Authorization: Bearer [token] u všech volání QR API, dokud nevyprší; poté se autentizujte znovu.

Založení platby (povinný krok)
Zavolejte metodu POST /pos/qr-api/payment a předejte povinné údaje: merchantId, terminalId, amount (v minoritních jednotkách), currency a method; volitelně refId a created. Pokud je požadavek v pořádku, API vrátí unikátní identifikátor transakce transId a paymentData pro vykreslení QR kódu. Identifikátor transId uložte, je klíčový pro všechny další operace s touto platbou.

Zjištění stavu platby (volitelný krok)
Opakovaně volejte metodu GET /pos/qr-api/payment/{transId}, 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.
Testovací platby se dokončují automaticky přibližně 10 vteřin po založení podle částky: do 2 000 CZK / 80 EUR včetně přejde platba do stavu 'PAID', vyšší částka do 'CANCELLED'. Refundace testovacích plateb se dokončují stejně: částka 0,01 (1 v minoritních jednotkách) skončí jako 'CANCELLED', jakákoli jiná jako 'REFUNDED'.

Storno platby (volitelný krok)
Pokud potřebujete zrušit platbu, která zatím nedosáhla finálního stavu, zavolejte metodu POST /pos/qr-api/payment/{transId}/cancel. Odpověď obsahuje výsledný stav (status 'CANCELLED').

QR API Flow

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 a datový formát je JSON. Každý požadavek na QR API musí obsahovat autorizační hlavičku Authorization: Bearer [token] s platným JWT tokenem získaným z Auth API. Token má omezenou platnost (expiry); po jejím vypršení získejte nový přes POST /pos/auth-api/authenticate.

Auth API

Získání přístupového tokenu

Ověří HTTP Basic přihlašovací údaje a vrátí JWT Bearer token sloužící k autorizaci QR API. Přihlašovací údaje předejte v hlavičce Authorization: Basic [base64_encode(user:password)]. V JSON body je POVINNÝ identifikátor obchodníka mid (bez něj 400) — zapeče se do tokenu a všechny navazující operace QR API jsou omezeny na tohoto obchodníka (requesty na jiného obchodníka či platby jiného obchodníka vrací 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

Expirace tokenu (ISO 8601).

Response Schema: application/json
errorMessage
string

Chybová zpráva.

Response Schema: application/json
errorMessage
string

Chybová zpráva.

Response Schema: application/json
errorMessage
string

Chybová zprá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

Ověření dostupnosti Auth API. Vrací HTTP 200 s prázdným tělem.

Responses

Request samples 

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

QR API

Health check

Ověření dostupnosti QR API. Vrací HTTP 200 s prázdným tělem.

Responses

Request samples 

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

Dostupné platební metody

Vrátí QR platební metody dostupné pro daný terminál a měnu (QR metody jednotlivých bank a generický QR převod) včetně názvů a log bank. U EUR se nabídka řídí zemí provozovny (SK → SK QR metoda, jinak EU QR metoda); s parametrem bothEurQr se vrátí SK i EU QR metody. Metody se filtrují i podle podporované částky a limitů okamžitých plateb dle 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 měny dle ISO 4217 (CZK nebo EUR).

amount
required
integer >= 1

Částka v minoritních jednotkách (haléře/centy) — filtruje metody dle podporované částky a limitů okamžitých plateb.

bothEurQr
boolean

Nepovinné; u EUR vrátí SK i EU QR metody bez ohledu na zemi provozovny.

lang
string

Nepovinný jazyk názvů metod (cs/sk/en, výchozí cs).

Responses

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

Identifikátor metody — předává se jako method při založení platby.

name
string

Lokalizovaný název metody.

logo
string

URL loga metody/banky. Použijte hodnotu z odpovědi — název souboru neodpovídá identifikátoru metody (logo banky je společné s platební bránou).

logoSvg
string or null

Vektorová varianta téhož loga, nebo null, když ji pro metodu nemáme. Nabízí se VEDLE logo, ne místo něj, aby klientům, kteří umí dekódovat jen rastr, logo nezhaslo - logo zůstává PNG. WARN: poměr stran se od rastru liší (PNG 120x32, tedy 3,75:1; vektory 2:1, BANK_CZ_T_PB 2,70:1), takže přepnutí znamená přepočítat i rámec, do kterého se kreslí.

Response Schema: application/json
errorMessage
string

Chybová zpráva.

Response Schema: application/json
errorMessage
string

Chybová zpráva.

Response Schema: application/json
errorMessage
string

Chybová zprá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žení platby

Vytvoří novou QR platbu. Při úspěchu vrátí identifikátor transakce transId a data platby potřebná k vykreslení 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á reference platby na straně obchodníka. Jde na výpis obchodníka (sloupec „ID od klienta“), pokud není vyplněný variableSymbol - ten pak zaujme jeho místo a reference se eviduje u platby vedle něj. V odpovědích ji vracíme nezměněnou tak i tak.

amount
required
integer >= 1

Částka v minoritních jednotkách (haléře/centy).

currency
required
string

Kód měny dle ISO 4217.

method
required
string

Platební metoda, např. BANK_CZ_T_OTHER.

created
string

Nepovinný čas vytvoření platby (ISO 8601).

variableSymbol
string <= 128 characters

Nepovinný variabilní symbol zadaný obsluhou, tedy vlastní reference obchodníka uložená k platbě. Libovolný text do 128 bajtů; delší hodnota nebo NUL vrací 400. Když je vyplněný, je to on, co se objeví na výpisu obchodníka (sloupec „ID od klienta“) a refId se eviduje u platby vedle něj; když vyplněný není, jde na výpis refId. V odpovědích se refId vrací nezměněný tak i tak. Hodnota o nejvýš deseti číslicích se navíc ukládá do vlastního sloupce variabilního symbolu platby. Do QR kódu se NEDOSTANE - pro párování příchozích peněz si platba generuje vlastní variabilní symbol.

Responses

Response Schema: application/json
transId
string

Identifikátor transakce.

refId
string

Reference platby (echo z requestu).

status
string

Stav platby; ihned po založení je PENDING.

paymentData
string

Data platebního QR kódu; formát dle metody: SPAYD pro CZ metody, PAY by square pro BANK_SK_T_OTHER, EPC QR (SEPA) pro BANK_EUR_T_OTHER. U platby ve stavu CANCELLED chybí.

paymentRejectedReason
string

Důvod zamítnutí; pouze u platby ve stavu CANCELLED.

Response Schema: application/json
errorMessage
string

Chybová zpráva.

Response Schema: application/json
errorMessage
string

Chybová zpráva.

Response Schema: application/json
errorMessage
string

Chybová zprá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átí aktuální stav platby. Dotazujte se opakovaně, dokud status nedosáhne finální hodnoty (PAID / CANCELLED).

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

Identifikátor transakce.

Responses

Response Schema: application/json
transId
string

Identifikátor transakce.

refId
string

Reference platby na straně obchodníka.

status
string

Stav platby: PENDING, PAID nebo CANCELLED.

paymentRejectedReason
string

Důvod zrušení platby; jen u platby ve stavu CANCELLED. Hodnoty jsou stabilní a dají se použít jako klíče: Customer timeout (platba expirovala), Canceled by merchant (zrušena přes /cancel), Canceled by payer, Canceled by provider, Provider timeout, Fraud suspected a Not specified. Jinou hodnotu berte jako neuvedený důvod.

Array of objects

Refundace této platby v chronologickém pořadí; bez refundací prázdné pole. Slouží k dohledání transRefundId v případě, že se vám odpověď na založení refundace nedoručila. Obsahuje pouze údaje známé při založení — aktuální stav refundace zjistíte přes GET /pos/qr-api/payment/{transId}/refund/{transRefundId}.

Response Schema: application/json
errorMessage
string

Chybová zpráva.

Response Schema: application/json
errorMessage
string

Chybová zpráva.

Response Schema: application/json
errorMessage
string

Chybová zprá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á zpráva.

Response Schema: application/json
errorMessage
string

Chybová zpráva.

Response Schema: application/json
errorMessage
string

Chybová zpráva.

Response Schema: application/json
errorMessage
string

Chybová zpráva.

Response Schema: application/json
errorMessage
string

Chybová zprá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"
}

Prodloužení expirace platby

Prodlouží expiraci nepotvrzené platby na 7 dní pro případ, že obchodník vydal zboží, přestože platbu nepotvrdil. Platba zůstává očekávaná a párovatelná, takže po příchodu peněz se standardní cestou překlopí na zaplacenou. Délku určuje server, volající ji nevolí. Volání je idempotentní a expiraci nikdy nezkrátí. Zaplacená platba vrátí 200 beze změny (peníze mezitím dorazily), zrušená 400 — nevzkřísí se a pozdní peníze jdou dnešním procesem do vratky.

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

Identifikátor transakce.

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

Nepovinná poznámka obchodníka uložená k platbě, např. kontakt na zákazníka pro pozdější dohledání.

Responses

Response Schema: application/json
transId
string

Identifikátor transakce.

refId
string

Reference platby.

status
string

Stav platby.

expiration
string

Nová expirace platby (ISO 8601).

Response Schema: application/json
errorMessage
string

Chybová zpráva.

Response Schema: application/json
errorMessage
string

Chybová zpráva.

Response Schema: application/json
errorMessage
string

Chybová zpráva.

Response Schema: application/json
errorMessage
string

Chybová zprá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šení platby

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

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

Identifikátor transakce.

Responses

Response Schema: application/json
transId
string

Identifikátor transakce.

status
string

Stav platby.

Response Schema: application/json
errorMessage
string

Chybová zpráva.

Response Schema: application/json
errorMessage
string

Chybová zpráva.

Response Schema: application/json
errorMessage
string

Chybová zprá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žení refundace

Založí požadavek na refundaci platby. Refundovat lze jen zaplacenou (PAID) platbu. Lze provést částečnou i plnou refundaci; součet refundací nesmí přesáhnout částku platby. Požadavek se zpracovává asynchronně — výsledek sledujte přes GET /pos/qr-api/payment/{transId}/refund/{transRefundId}.

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

Identifikátor transakce.

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

Částka refundace v minoritních jednotkách.

created
required
string

Čas vytvoření refundace (ISO 8601).

refId
string

Nepovinná reference refundace na straně obchodníka — refundaci s platbou páruje transId v URL.

Responses

Response Schema: application/json
transRefundId
string

Identifikátor refundace.

status
string

Stav refundace; ihned po založení je PENDING.

transId
string

Identifikátor transakce.

refId
string

Reference refundace (echo z requestu).

Response Schema: application/json
errorMessage
string

Chybová zpráva.

Response Schema: application/json
errorMessage
string

Chybová zpráva.

Response Schema: application/json
errorMessage
string

Chybová zpráva.

Response Schema: application/json
errorMessage
string

Chybová zprá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 refundace

Vrátí stav refundace. Možné stavy: PENDING (ve zpracování), REFUNDED (peníze odeslány zpět), CANCELLED (refundace zamítnuta/stornována).

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

Identifikátor transakce.

transRefundId
required
string
Example: 123456

Identifikátor refundace.

Responses

Response Schema: application/json
transRefundId
string

Identifikátor refundace.

status
string

Stav refundace: PENDING / REFUNDED / CANCELLED.

transId
string

Identifikátor transakce.

refId
string

Reference refundace na straně obchodníka.

Response Schema: application/json
errorMessage
string

Chybová zpráva.

Response Schema: application/json
errorMessage
string

Chybová zpráva.

Response Schema: application/json
errorMessage
string

Chybová zprá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"
}