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

Authorizations:
basicAuth

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.

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

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 \

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.

amount
required
integer

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

currency
required
string

ISO 4217 currency code.

method
required
string

Payment method, e.g. QR_T_CZ_OTHER.

created
string

Optional payment creation timestamp (ISO 8601).

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 in SPAYD format. 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.

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

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.

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

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.

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