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

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.

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

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

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 zamítnutí; pouze u platby ve stavu CANCELLED.

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

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.

paymentRejectedReason
string

Důvod zamítnutí; pouze pokud byla platba zamítnuta.

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",
  • "paymentRejectedReason": "string"
}

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