Skip to main content
API docs by Redocly

Terminal REST API Methods – CloudPOS (2.0)

The terminal REST API is used to connect a cash register or other business system to a payment terminal from Comgate over the Internet. It allows you to remotely enter instructions to the terminal, typically to initiate a payment and subsequently determine its result. In the terminal REST API, we only support the JSON data format. The process of processing one transaction usually consists of the following steps:

Creating a payment (mandatory step)
The cash register system calls the POST /v2.0/terminalPayment.json method and passes it the mandatory data: amount (price), currency (curr), or it is possible to add a payment reference/variable symbol (refId). If the request is correct, the API returns a unique transaction identifier transId. Save this code in your cash register system, it is key for all further operations with this payment.

Determining the payment status (optional step)
The cash register system can check the payment result. Repeatedly call the GET /v2.0/terminalPayment/transId/{transId}.json method until the status changes from 'PENDING' to the final value. Possible final states are:

  • PAID – payment was successful,
  • CANCELLED – payment was canceled, rejected, not completed correctly or timed out.
Cancel payment (optional step)
If you need to cancel a transaction that has already been paid (e.g. when returning goods immediately), you can use the DELETE /v2.0/terminalPayment/transId/{transId}.json method. Cancellation can only be made for payments in the 'PAID' status and only until the 'closing' is performed.

CloudPOS Terminal Flow

Additional methods

Terminal status
You can verify whether the terminal is online by calling the GET /v2.0/terminal.json method.

Closing
The POST /v2.0/terminalClosing.json method is used to perform a closing, which returns summary information about transactions made since the previous closing and clears the transaction history in the terminal.

Security and authorization

To ensure the integrity and confidentiality of transmitted data, all communication takes place exclusively via the encrypted HTTPS protocol. Access to all API methods can only be allowed from pre-approved IP addresses. In this case, requests from other IP addresses will be rejected. Each request must also contain an authorization header in the format: Authorization: Basic [base64_encode(merchant:secret)]. The 'merchant' parameter is your terminal login identifier and 'secret' is your password. You can find this information, along with the options for setting allowed IP addresses for API access, in the Client Portal in the Integration – Shops Settings – Terminals section.

ATTENTION

We are currently preparing additional methods for working with preauthorizations and MOTO payments.

New payment

header Parameters
authorization
required
string

Authorization header is added in the form: Authorization: Basic [base64_encode(merchant:secret)]. Merchant is the Login identifier in the ComGate system - you can find it in the Client Portal in the section Integration - Shop settings - Terminals. Secret is the password.

Request Body schema: application/json

Create new payment.

price
required
integer <int32>

Price for a product in cents or pennies. For example, for a payment of 10 EUR, the value '1000' should be used.
Must be in minimum of 1 CZK; 0,1 EUR.
Maximum 1 000 000 CZK; 40 000 EUR.

curr
required
string

Currency code according to ISO 4217. Available currencies: CZK, EUR.

refId
string

Parameter suitable for entering a variable symbol or order number on the Client's side (it does not have to be unique, ie it is possible to create more payments with the same refId). In the Client Portal and daily csv the parameter is marked as Client ID.

Responses

Response Schema: application/json
code
required
integer

Method return code and error (value of message) description:
0 OK
1100 unknown error
1107 payment price not supported
1200 database error
1301 unknown terminal
1309 wrong amount
1310 unknown currency
1399 unexpected result from database
1400 bad request
1500 unexpected error

message
required
string
transId
string

Unique alphanumeric identifier (code) of the transaction.

Request samples

Content type
application/json
{
  • "price": 1000,
  • "curr": "CZK",
  • "refId": "2010102600"
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "OK",
  • "transId": "AB12-CD34-EF56"
}

Payment status

Getting payment status, possibly with detailed transaction data (if available).

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

Unique alphanumeric identifier (code) of the transaction (transactionId).

header Parameters
authorization
required
string

Authorization header is added in the form: Authorization: Basic [base64_encode(merchant:secret)]. Merchant is the Login identifier in the ComGate system - you can find it in the Client Portal in the section Integration - Shop settings - Terminals. Secret is the password.

Responses

Response Schema: application/json
code
required
integer

Method return code.

message
required
string

Method return code and error description:
0 OK
1100 unknown error
1200 database error
1400 wrong query
1500 unexpected error

in the case of code = 0, the following parameters are in the response

price
required
string

Price of the product in cents or pennies. For example, for a payment of 10 EUR, the value '1000' will be returned.

curr
required
string

Currency code according to ISO 4217.

refId
required
string

Payment references (variable symbol).

transId
required
string

Unique alphanumeric identifier (code) of the transaction (transactionId).

status
required
string

Current transaction status, values:
'PENDING' – the payment is created, the final result is not known
'PAID' – payment was successfully paid
'CANCELLED' – the payment was not completed correctly and is cancelled
'AUTHORIZED' – the requested pre-authorization was successful

fee
string

The calculated transaction fee in cents or pennies, or may contain the value 'unknown'. Payment fees are available in the response the next day at the earliest based on payment processor reports.

cardValid
string

Payer's card expiration date in MM/YY format (if the card was used). For example: '04/28'.

cardNumber
string

Partial payer card number (if the card was used).

paymentErrorReason
string

Reason for payment rejection (if available).

reversed
required
boolean

Flag indicating whether the payment was reversed (cancelled).

amountRefunded
string

Refunded amount in cents or pennies.

Request samples 

# You can also use wget
curl -X GET https://payments.comgate.cz/v2.0/terminalPayment/transId/{transId}.json \
-H 'Authorization: Basic MTIzNDU2Omd4NHE4T1YzVEp0Nm5vSm5maGpxSkt5WDNaNlljaDB5'

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "OK",
  • "price": "1000",
  • "curr": "CZK",
  • "refId": "2010102600",
  • "transId": "AB12-CD34-EF56",
  • "status": "PAID",
  • "fee": "string",
  • "cardValid": "04/28",
  • "cardNumber": "string",
  • "paymentErrorReason": "string",
  • "reversed": true,
  • "amountRefunded": "string"
}

Cancel of payment

Cancel of payment
The payment can be cancelled until 'closing' is triggered on terminal. The payment must be sucessfully finished (in the 'PAID' state).
If 'closing' was already triggered on terminal, an error will be displayed and the 'refund' method must be used instead (if possible). 'code' = 0 in the response indicates successful reversal creation. You can verify the cancellation by calling the Payment status endpoint.

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

Unique alphanumeric identifier (code) of the transaction (transactionId).

header Parameters
authorization
required
string

Authorization header is added in the form: Authorization: Basic [base64_encode(merchant:secret)]. Merchant is the Login identifier in the ComGate system - you can find it in the Client Portal in the section Integration - Shop settings - Terminals. Secret is the password.

Responses

Response Schema: application/json
code
required
integer

Method return code and error description:
0 OK
1400 the payment cannot be changed to cancelled status (payment not found, payment is not in paid state, unauthorized access)

message
required
string

Request samples 

# You can also use wget
curl -X DELETE https://payments.comgate.cz/v2.0/terminalPayment/transId/{transId}.json \
-H 'Authorization: Basic MTIzNDU2Omd4NHE4T1YzVEp0Nm5vSm5maGpxSkt5WDNaNlljaDB5'

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "OK"
}

Terminal status

Check terminal status.

header Parameters
authorization
required
string

Authorization header is added in the form: Authorization: Basic [base64_encode(merchant:secret)]. Merchant is the Login identifier in the ComGate system - you can find it in the Client Portal in the section Integration - Shop settings - Terminals. Secret is the password.

Responses

Response Schema: application/json
status
required
string

Status of the connection test to the authorization server.
'ONLINE' – terminal is connected to the authorization server
'OFFLINE' – terminal is not connected to the authorization server
'BUSY' – terminal is processing some transaction
'UNKNOWN' – status of the connection cannot be checked or the terminal is unavailable

Request samples 

# You can also use wget
curl -X GET https://payments.comgate.cz/v2.0/terminal.json \
-H 'Authorization: Basic MTIzNDU2Omd4NHE4T1YzVEp0Nm5vSm5maGpxSkt5WDNaNlljaDB5'

Response samples

Content type
application/json
{
  • "status": "ONLINE"
}

Batch closing

Performs a batch closing on the terminal. Closing will clear the transaction history in the terminal.

header Parameters
authorization
required
string

Authorization header is added in the form: Authorization: Basic [base64_encode(merchant:secret)]. Merchant is the Login identifier in the ComGate system - you can find it in the Client Portal in the section Integration - Shop settings - Terminals. Secret is the password.

Responses

Response Schema: application/json
code
required
integer

0 - OK, otherwise see 'message' param for details.

message
required
string

OK or text description of the batch closing result.

batchNumber
integer

Number of batch closing.

Array of objects

List of batch totals per currency.

Request samples 

# You can also use wget
curl -X POST https://payments.comgate.cz/v2.0/terminalClosing.json \
-H 'Authorization: Basic MTIzNDU2Omd4NHE4T1YzVEp0Nm5vSm5maGpxSkt5WDNaNlljaDB5' \
-H 'Content-Type: application/json'

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "OK",
  • "batchNumber": 1,
  • "batchData": [
    ]
}

New refund

header Parameters
authorization
required
string

Authorization header is added in the form: Authorization: Basic [base64_encode(merchant:secret)]. Merchant is the Login identifier in the ComGate system - you can find it in the Client Portal in the section Integration - Shop settings - Terminals. Secret is the password.

Request Body schema: application/json

Create new refund.

price
required
integer <int32>

Refund amount in cents or pennies. For example, for a refund of 10 EUR, the value '1000' should be used.
Must be in minimum of 1 CZK; 0,1 EUR.
Maximum 1 000 000 CZK; 40 000 EUR.

curr
required
string

Currency code according to ISO 4217. Available currencies: CZK, EUR.

refId
string

Parameter suitable for entering a variable symbol or order number on the Client's side (it does not have to be unique, ie it is possible to create more refunds with the same refId). In the Client Portal and daily csv the parameter is marked as Client ID.

Responses

Response Schema: application/json
code
required
integer

Method return code and error (value of message) description:
0 OK
1100 unknown error
1107 refund price not supported
1200 database error
1301 unknown terminal
1309 wrong amount
1310 unknown currency
1399 unexpected result from database
1400 bad request
1500 unexpected error

message
required
string
transId
string

Unique alphanumeric identifier (code) of the transaction.

Request samples

Content type
application/json
{
  • "price": 1000,
  • "curr": "CZK",
  • "refId": "2010102600"
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "OK",
  • "transId": "AB-CD123-EF456"
}

Refund status

Getting refund status, possibly with detailed transaction data (if available).

path Parameters
transId
required
string
Example: AA-BBBBB-CCCCC

Unique alphanumeric identifier (code) of the transaction (transactionId).

header Parameters
authorization
required
string

Authorization header is added in the form: Authorization: Basic [base64_encode(merchant:secret)]. Merchant is the Login identifier in the ComGate system - you can find it in the Client Portal in the section Integration - Shop settings - Terminals. Secret is the password.

Responses

Response Schema: application/json
code
required
integer

Method return code.

message
required
string

Method return code and error description:
0 OK
1100 unknown error
1200 database error
1400 wrong query
1500 unexpected error

in the case of code = 0, the following parameters are in the response

price
required
string

Price of refund in cents or pennies. For example, for a refund of 10 EUR, the value '1000' will be returned.

curr
required
string

Currency code according to ISO 4217.

refId
required
string

Refund reference.

transId
required
string

Unique alphanumeric identifier (code) of the transaction (transactionId).

status
required
string

Current refund status, values:
'PENDING' – the refund is created, the final result is not known
'PAID' – refund was successfully paid
'CANCELLED' – the refund was not completed correctly and is cancelled

cardNumber
string

Partial payer card number (if the card was used).

reversed
required
boolean

Flag indicating whether the refund was reversed (cancelled).

Request samples 

# You can also use wget
curl -X GET https://payments.comgate.cz/v2.0/terminalRefund/transId/{transId}.json \
-H 'Authorization: Basic MTIzNDU2Omd4NHE4T1YzVEp0Nm5vSm5maGpxSkt5WDNaNlljaDB5'

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "OK",
  • "price": "1000",
  • "curr": "CZK",
  • "refId": "2010102600",
  • "transId": "AB-CD123-EF456",
  • "status": "PAID",
  • "cardNumber": "string",
  • "reversed": true
}

Cancel of refund

Cancel of refund
The refund can be cancelled only on the same day. The refund must be sucessfully finished (in the 'PAID' state).
'code' = 0 in the response indicates successful reversal creation. You can verify the cancellation by calling the Refund status endpoint.

path Parameters
transId
required
string
Example: AA-BBBBB-CCCCC

Unique alphanumeric identifier (code) of the transaction (transactionId).

header Parameters
authorization
required
string

Authorization header is added in the form: Authorization: Basic [base64_encode(merchant:secret)]. Merchant is the Login identifier in the ComGate system - you can find it in the Client Portal in the section Integration - Shop settings - Terminals. Secret is the password.

Responses

Response Schema: application/json
code
required
integer

Method return code and error description:
0 OK
1400 the refund cannot be changed to cancelled status (refund not found, refund is not in paid state, unauthorized access)

message
required
string

Request samples 

# You can also use wget
curl -X DELETE https://payments.comgate.cz/v2.0/terminalRefund/transId/{transId}.json \
-H 'Authorization: Basic MTIzNDU2Omd4NHE4T1YzVEp0Nm5vSm5maGpxSkt5WDNaNlljaDB5'

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "OK"
}

Bank transfers list

The transferList method is used to obtain information about which transfers were made within a given day. Information about the bank transfer (sent on the previous business day) is available in the morning of the following day.
Transfers and statements are generated only for paid and transferred production payments. For all other payments, including test payments, transfers and statements are not generated.

path Parameters
date
required
string
Example: 2025-04-25

Indicate the transfer date.

query Parameters
test
boolean
Example: test=false

If the value is 'true', the method returns predefined sample transfer.

header Parameters
authorization
required
string

Authorization header is added in the form: Authorization: Basic [base64_encode(merchant:secret)]. Merchant is the Login identifier in the ComGate system - you can find it in the Client Portal in the section Integration - Shop settings - Terminals. Secret is the password.

Responses

Response Schema: application/json
Array
transferId
integer

Transfers that were made during the given day.

transferDate
string <date>

The date and transferDate parameters are interpreted in the Europe/Prague time zone (CET/CEST depending on the date).

accountCounterparty
string

Account number of the counterparty.

accountOutgoing
string

Outgoing account number.

variableSymbol
string

Payment identifier (variable symbol).

Request samples 

# You can also use wget
curl -X GET https://payments.comgate.cz/v2.0/transferList/date/{date}.json \
-H 'Authorization: Basic MTIzNDU2Omd4NHE4T1YzVEp0Nm5vSm5maGpxSkt5WDNaNlljaDB5'

Response samples

Content type
application/json
[
  • {
    }
]

Bank transfer detail

The singleTransfer method displays detailed information for a specific bank transfer.
Date parameters are interpreted in the Europe/Prague time zone (CET/CEST depending on the date).
Transfers and statements are generated only for paid and transferred production payments. For all other payments, including test payments, transfers and statements are not generated.

path Parameters
transferId
required
string
Example: 1234567

Mandatory parameter obtained using the transferList method.

query Parameters
test
boolean
Example: test=false

Suitable for testing – returns details to predefined sample transfers.

header Parameters
authorization
required
string

Authorization header is added in the form: Authorization: Basic [base64_encode(merchant:secret)]. Merchant is the Login identifier in the ComGate system - you can find it in the Client Portal in the section Integration - Shop settings - Terminals. Secret is the password.

Responses

Response Schema: application/json
Array
typ
integer

Parameter indicates the type of transfer.

Merchant
string

Shop identifier in the Comgate system.

Datum založení
string

Date when the transaction was created.

Datum zaplacení
string

Date when the transaction was paid.

Datum převodu
string

Date of payout for the bulk transfer of transactions.

Měsíc fakturace
integer

Billing month related to the payment.

ID Comgate
string

Comgate payment ID, a unique 12-character code.

Metoda
string

Payment method used.

Produkt
string

Product identifier passed at payment creation under parameter 'name'.

Popis
string

Short product description (1–16 characters) passed during payment creation under parameter 'label'.

E-mail plátce
string

Payer's email address.

Variabilní symbol plátce
string

Variable symbol assigned to the payment.

Variabilní symbol převodu
string

Variable symbol of the bulk transfer.

ID od klienta
string

Client's matching ID used to identify goods and customer (e.g., order or customer number). It corresponds to the RefId parameter in the API protocol.

Měna
string

Currency of the payment. The value is in ISO 4217 format.

Potvrzená částka
string

Confirmed transaction amount (customer order value).

Převedená částka
string

Amount usually sent to the shop's bank account (reduced by transaction fee).

Poplatek celkem
string

Total fee for the payment, according to the price list. Total fee = interbank fee + association fee + processor fee.

Poplatek mezibankovní
string

Fee received by the card issuer.

Poplatek asociace
string

Fee received by the card association.

Poplatek zpracovatel
string

Fee charged by the transaction processor.

Typ karty
string

Type of card used for card payment.

Request samples 

# You can also use wget
curl -X GET https://payments.comgate.cz/v2.0/singleTransfer/transferId/{transferId}.json \
-H 'Authorization: Basic MTIzNDU2Omd4NHE4T1YzVEp0Nm5vSm5maGpxSkt5WDNaNlljaDB5'

Response samples

Content type
application/json
[
  • {
    }
]

CSV daily statement

Thanks to the csvSingleTransfer method, you can download the daily statement in CSV format for a specific bank transfer.
Transfers and statements are generated only for paid and transferred production payments. For all other payments, including test payments, transfers and statements are not generated.

path Parameters
transferId
required
string
Example: 1234567

Details for a specific bank transfer obtained using the transferList method.

query Parameters
download
boolean
Example: download=false

If not filled in or false, it returns data: file name and its contents; if true, it returns the CSV file directly.

test
boolean
Example: test=false

returns a sample CSV file for testing purposes

header Parameters
authorization
required
string

Authorization header is added in the form: Authorization: Basic [base64_encode(merchant:secret)]. Merchant is the Login identifier in the ComGate system - you can find it in the Client Portal in the section Integration - Shop settings - Terminals. Secret is the password.

Responses

Response Schema: application/json
nazev
string

File name for the downloaded CSV file

csv
string

Base64-encoded CSV file

Request samples 

# You can also use wget
curl -X GET https://payments.comgate.cz/v2.0/csvSingleTransfer/transferId/{transferId}.json \
-H 'Authorization: Basic MTIzNDU2Omd4NHE4T1YzVEp0Nm5vSm5maGpxSkt5WDNaNlljaDB5'

Response samples

Content type
application/json
{
  • "nazev": "vypis-YYYY-MM-DD.csv",
  • "csv": "base64 encoded csv"
}

ABO daily statement

Thanks to the aboSingleTransfer method, you can download a daily statement in ABO format.
Transfers and statements are generated only for paid and transferred production payments. For all other payments, including test payments, transfers and statements are not generated.

path Parameters
transferId
required
string
Example: 1234567

Details for a specific bank transfer obtained using the transferList method.

query Parameters
download
boolean
Example: download=true

If not filled in or false, it returns data: file name and its contents; if true, it returns the ABO file directly.

type
string
Example: type=v1

The 'type' parameter can take the values 'v1' and 'v2'. Under 'v1' you get the ABO version with the fees listed separately for each payment, under 'v2' you get the ABO with the total fee in one line. If the parameter is not filled in, you will automatically receive the type 'v1'.

encoding
string
Example: encoding=utf8

The character encoding can be utf8 or win1250. If the value is not filled in, the parameter value defaults to utf8.

test
boolean
Example: test=false

Returns a sample ABO file for testing purposes.

header Parameters
authorization
required
string

Authorization header is added in the form: Authorization: Basic [base64_encode(merchant:secret)]. Merchant is the Login identifier in the ComGate system - you can find it in the Client Portal in the section Integration - Shop settings - Terminals. Secret is the password.

Responses

Response Schema: application/json
nazev
string

File name.

abo
string

Base64 encoded abo/gpc file.

Request samples 

# You can also use wget
curl -X GET https://payments.comgate.cz/v2.0/aboSingleTransfer/transferId/{transferId}.json \
-H 'Authorization: Basic MTIzNDU2Omd4NHE4T1YzVEp0Nm5vSm5maGpxSkt5WDNaNlljaDB5'

Response samples

Content type
application/json
{
  • "nazev": "vypis-YYYY-MM-DD.gpc",
  • "abo": "base64_encoded_abo_file"
}

CSV files download

Direct download of CSV files for a specific day using the csvDowload method. The downloaded ZIP file will contain one or more CSV files if there are multiple transactions within a day. It can be used, for example, for calls using wget.
Transfers and statements are generated only for paid and transferred production payments. For all other payments, including test payments, transfers and statements are not generated.

path Parameters
date
required
string
Example: 2025-04-25

Mandatory for one day only.

query Parameters
test
boolean
Example: test=false

For testing purposes, it returns a sample CSV file in ZIP format.

header Parameters
authorization
required
string

Authorization header is added in the form: Authorization: Basic [base64_encode(merchant:secret)]. Merchant is the Login identifier in the ComGate system - you can find it in the Client Portal in the section Integration - Shop settings - Terminals. Secret is the password.

Responses

Response Schema: application/zip
string <binary>

Request samples 

# You can also use wget
curl -X GET https://payments.comgate.cz/v2.0/csvDownload/date/{date} \
-H 'Authorization: Basic MTIzNDU2Omd4NHE4T1YzVEp0Nm5vSm5maGpxSkt5WDNaNlljaDB5'

ABO files download

Direct download of ABO files for a specific day using the aboDowload method. The downloaded ZIP file will contain one or more ABO files. It can be used, for example, for calls using wget.
Transfers and statements are generated only for paid and transferred production payments. For all other payments, including test payments, transfers and statements are not generated.

path Parameters
date
required
string
Example: 2025-04-25

Mandatory for one day only.

query Parameters
type
string

The 'type' parameter can take the values 'v1' and 'v2'. Under 'v1' you get the ABO version with the fees listed separately for each payment, under 'v2' you get the ABO with the total fee in one line. If the parameter is not filled in, you will automatically receive the type 'v1'.

encoding
string
Example: encoding=utf8

The character encoding can be utf8 or win1250. If the value is not filled in, the parameter value defaults to utf8.

test
boolean
Example: test=false

For testing purposes, it returns a sample CSV file in ZIP format.

header Parameters
authorization
required
string

Authorization header is added in the form: Authorization: Basic [base64_encode(merchant:secret)]. Merchant is the Login identifier in the ComGate system - you can find it in the Client Portal in the section Integration - Shop settings - Terminals. Secret is the password.

Responses

Response Schema: application/zip
string <binary>

Request samples 

# You can also use wget
curl -X GET https://payments.comgate.cz/v2.0/aboDownload/date/{date} \
-H 'Authorization: Basic MTIzNDU2Omd4NHE4T1YzVEp0Nm5vSm5maGpxSkt5WDNaNlljaDB5'