Skip to main content
API docs by Redocly

Terminal REST API Methods (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. You must save this code, it is key for all further operations with this payment.

Determining the payment status (optional step)
The cash register system can determine how the payment went on the terminal. 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.

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, refunds, 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 paymentVytv * orenie novej platby

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

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

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

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