Skip to main content
API docs by Redocly

POS QR REST API (1.0)

The QR REST API connects a cash register or other business system to Comgate over the Internet and lets you initiate a QR / account payment on a payment terminal and subsequently determine its result. We only support the JSON data format. The process of processing one transaction usually consists of the following steps:

Authentication (mandatory first step)
Call the POST /pos/auth-api/authenticate method with HTTP Basic credentials (header Authorization: Basic [base64_encode(user:password)]). The API returns a JWT token and its expiry. Use this token in the Authorization: Bearer [token] header for all QR API calls until it expires; after that, authenticate again.

Creating a payment (mandatory step)
Call the POST /pos/qr-api/payment method and pass the mandatory data: merchantId, terminalId, amount (in minor units), currency and method; optionally refId and created. If the request is correct, the API returns a unique transaction identifier transId and paymentData for rendering the QR code. Save the transId, it is key for all further operations with this payment.

Determining the payment status (optional step)
Repeatedly call the GET /pos/qr-api/payment/{transId} method until the status changes from 'PENDING' to a final value. Possible final states are:

  • PAID – payment was successful,
  • CANCELLED – payment was cancelled, rejected, not completed correctly or timed out.
Test payments are completed automatically approximately 10 seconds after creation based on the amount: up to 2 000 CZK / 80 EUR (inclusive) the payment ends as 'PAID', a higher amount as 'CANCELLED'. Refunds of test payments are completed the same way: an amount of 0.01 (1 in minor units) ends as 'CANCELLED', any other amount as 'REFUNDED'.

Cancel payment (optional step)
If you need to cancel a payment that has not yet reached a final state, call the POST /pos/qr-api/payment/{transId}/cancel method. The response contains the resulting status ('CANCELLED').

QR API Flow

Security and authorization

To ensure the integrity and confidentiality of transmitted data, all communication takes place exclusively over the encrypted HTTPS protocol and the data format is JSON. Every QR API request must contain the authorization header Authorization: Bearer [token] with a valid JWT token obtained from the Auth API. The token has a limited validity (expiry); after it expires, obtain a new one via POST /pos/auth-api/authenticate.

Auth API

Obtain access token

Verifies HTTP Basic credentials and returns a JWT Bearer token used to authorize the QR API. Pass credentials in the Authorization: Basic [base64_encode(user:password)] header. A merchant identifier mid is REQUIRED in the JSON body (400 without it) — it is baked into the token and all subsequent QR API operations are restricted to that merchant (requests for another merchant or payments of another merchant return 403).

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

Merchant identifier baked into the token (MID scoping).

Responses

Response Schema: application/json
token
string

JWT Bearer token.

expiry
string

Token expiration (ISO 8601).

Response Schema: application/json
errorMessage
string

Error message.

Response Schema: application/json
errorMessage
string

Error message.

Response Schema: application/json
errorMessage
string

Error message.

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

Liveness probe of the Auth API. Returns HTTP 200 with an empty body.

Responses

Request samples 

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

QR API

Health check

Liveness probe of the QR API. Returns HTTP 200 with an empty body.

Responses

Request samples 

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

Available payment methods

Returns the QR payment methods available for the given terminal and currency (bank-specific QR methods and the generic QR transfer), including bank names and logos. For EUR the offer follows the merchant's establishment country (SK → the SK QR method, otherwise the EU QR method); with bothEurQr both SK and EU QR methods are returned. Methods are also filtered by supported amount and instant-payment limits based on the mandatory amount.

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

Merchant identifier.

terminalId
required
string

Terminal identifier.

currency
required
string

ISO 4217 currency code (CZK or EUR).

amount
required
integer >= 1

Amount in minor units (e.g. hellers/cents) — filters methods by supported amount and instant-payment limits.

bothEurQr
boolean

Optional; for EUR returns both SK and EU QR methods regardless of the establishment country.

lang
string

Optional language of method names (cs/sk/en, default cs).

Responses

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

Method identifier — pass as method when creating a payment.

name
string

Localized method name.

logo
string

Method/bank logo URL. Use the value from the response — the file name does not follow the method identifier (the same bank logo is shared with the payment gateway).

logoSvg
string or null

Vector variant of the same logo, or null when we do not have one for the method. It is offered ALONGSIDE logo, not instead of it, so that clients which can only decode a raster keep working - logo stays a PNG. WARN: the aspect ratio differs from the raster (PNG 120x32, i.e. 3.75:1; vectors are 2:1, BANK_CZ_T_PB is 2.70:1), so switching to it means recomputing the box you draw into.

Response Schema: application/json
errorMessage
string

Error message.

Response Schema: application/json
errorMessage
string

Error message.

Response Schema: application/json
errorMessage
string

Error message.

Request samples

Content type
application/json
{
  • "merchantId": "MERCH001",
  • "terminalId": "TERM001",
  • "currency": "CZK",
  • "amount": 12500,
  • "bothEurQr": false,
  • "lang": "cs"
}

Response samples

Content type
application/json
{}

Create payment

Creates a new QR payment. On success it returns the transaction identifier transId and the payment data needed to render the QR code.

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

Merchant identifier.

terminalId
required
string

Terminal identifier.

refId
string

Optional merchant payment reference. It appears on the merchant's settlement statement (the Client ID column) unless variableSymbol is filled - then the symbol takes that place and the reference is kept alongside the payment. Our responses return it unchanged either way.

amount
required
integer >= 1

Amount in minor units (e.g. hellers/cents).

currency
required
string

ISO 4217 currency code.

method
required
string

Payment method, e.g. BANK_CZ_T_OTHER.

created
string

Optional payment creation timestamp (ISO 8601).

variableSymbol
string <= 128 characters

Optional variable symbol entered by the operator - the merchant's own reference stored with the payment. Any text up to 128 bytes; longer values or NUL return 400. When it is filled it is the value that appears on the merchant's settlement statement (the Client ID column) and refId is kept alongside the payment; when it is empty, refId goes on the statement instead. Either way refId comes back unchanged in our responses. A value of at most 10 digits is additionally stored in the payment's own variable symbol column. It does NOT go into the QR code - the payment generates its own variable symbol for matching incoming money.

Responses

Response Schema: application/json
transId
string

Transaction identifier.

refId
string

Merchant payment reference (echo of the request).

status
string

Payment status; right after creation it is PENDING.

paymentData
string

Payment QR code data; the format follows the method: SPAYD for CZ methods, PAY by square for BANK_SK_T_OTHER, EPC QR (SEPA) for BANK_EUR_T_OTHER. Not present for a CANCELLED payment.

paymentRejectedReason
string

Reason for rejection; present only for a CANCELLED payment.

Response Schema: application/json
errorMessage
string

Error message.

Response Schema: application/json
errorMessage
string

Error message.

Response Schema: application/json
errorMessage
string

Error message.

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

Payment status

Returns the current state of the payment. Poll until status reaches a final value (PAID / CANCELLED).

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

Transaction identifier.

Responses

Response Schema: application/json
transId
string

Transaction identifier.

refId
string

Merchant payment reference.

status
string

Payment status: PENDING, PAID or CANCELLED.

paymentRejectedReason
string

Reason for rejection; present only for a CANCELLED payment.

Array of objects

Refunds of this payment in chronological order; an empty array if there are none. Use it to recover transRefundId when the response to creating a refund was not delivered to you. It contains the data known at creation time only — get the current refund status from GET /pos/qr-api/payment/{transId}/refund/{transRefundId}.

Response Schema: application/json
errorMessage
string

Error message.

Response Schema: application/json
errorMessage
string

Error message.

Response Schema: application/json
errorMessage
string

Error message.

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

Extend payment expiration

Extends the expiration of an unconfirmed payment to 7 days, for the case where the merchant released the goods even though we have not confirmed the payment. The payment stays pending and matchable, so once the money arrives it flips to paid the usual way. The length is a server-side policy and cannot be chosen by the caller. The call is idempotent and never shortens the expiration. A paid payment returns 200 unchanged (the money arrived in the meantime); a cancelled one returns 400 — it is not resurrected, and late money goes through the standard refund process.

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

Transaction identifier.

Request Body schema: application/json
optional
note
string

Optional merchant note kept with the payment, e.g. a customer contact for later follow-up.

Responses

Response Schema: application/json
transId
string

Transaction identifier.

refId
string

Merchant payment reference.

status
string

Payment status.

expiration
string

New payment expiration (ISO 8601).

Response Schema: application/json
errorMessage
string

Error message.

Response Schema: application/json
errorMessage
string

Error message.

Response Schema: application/json
errorMessage
string

Error message.

Response Schema: application/json
errorMessage
string

Error message.

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

Cancel payment

Cancels the payment. The response contains the resulting state (CANCELLED).

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

Transaction identifier.

Responses

Response Schema: application/json
transId
string

Transaction identifier.

status
string

Payment status.

paymentRejectedReason
string

Reason for rejection; present only if the payment was rejected.

Response Schema: application/json
errorMessage
string

Error message.

Response Schema: application/json
errorMessage
string

Error message.

Response Schema: application/json
errorMessage
string

Error message.

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

Create refund

Creates a refund request for the payment. Only a paid (PAID) payment can be refunded. Both partial and full refunds are possible; the total of all refunds must not exceed the payment amount. The request is processed asynchronously — track the result via GET /pos/qr-api/payment/{transId}/refund/{transRefundId}.

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

Transaction identifier.

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

Refund amount in minor units.

created
required
string

Refund creation timestamp (ISO 8601).

refId
string

Optional merchant refund reference — the refund is tied to the payment by transId in the URL.

Responses

Response Schema: application/json
transRefundId
string

Refund identifier.

status
string

Refund status; right after creation it is PENDING.

transId
string

Transaction identifier.

refId
string

Merchant refund reference (echo of the request).

Response Schema: application/json
errorMessage
string

Error message.

Response Schema: application/json
errorMessage
string

Error message.

Response Schema: application/json
errorMessage
string

Error message.

Response Schema: application/json
errorMessage
string

Error message.

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

Refund status

Returns the refund status. Possible states: PENDING (in processing), REFUNDED (money sent back), CANCELLED (refund rejected/cancelled).

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

Transaction identifier.

transRefundId
required
string
Example: 123456

Refund identifier.

Responses

Response Schema: application/json
transRefundId
string

Refund identifier.

status
string

Refund status: PENDING / REFUNDED / CANCELLED.

transId
string

Transaction identifier.

refId
string

Merchant refund reference.

Response Schema: application/json
errorMessage
string

Error message.

Response Schema: application/json
errorMessage
string

Error message.

Response Schema: application/json
errorMessage
string

Error message.

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