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

Authorizations:
basicAuth

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.

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

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 \

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

Čá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ř. QR_T_CZ_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

Platební QR kód ve formátu SPAYD. 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.

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

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

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.

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