API Payment Methods (1.0)

create

Access is protected by IP address validation and the integrity of transmitted data is ensured using the HTTPS protocol. The step of creating payments is optional, but it is advisable to implement it in case you require the certainty of secure payment creation. It is possible to skip the implementation of this step if you do not need to identify individual payments in the system, but only require information that someone has paid you a certain amount. This is suitable, for example, when implementing donations or recharging funds to a customer's virtual account, where you are only interested in who recharged what amount, but you do not need to differentiate individual recharges or limit recharges to a minimum amount. However, for a classic e-shop, where you pay for specific goods, it is inappropriate to skip this step. The merchant uses HTTP requests to create payment transaction. Payment attributes including unique payment reference numbers are sent as POST parameters via HTTP protocol. Communication is only between the Merchant’s server and the payment gateway server. It is invisible to payer and the payer cannot change the payment parameters. The payment gateway server responds by sending a unique payment transaction identifier – transaction ID (Comgate system identifier) and URL to which to redirect the payer

The payment gateway server responds only if the payment is created in a background. All parameters are urlencoded, as in the case of an HTTP request. If the payment is created through redirection (the prepareOnly parameter is 'false'), then the payment gateway server directly redirects the Payer to the appropriate URL or displays an error message.

Choice of payment method
Within the shopping process on the e-shop, it's possible to display a selection of payment methods to the payer, and based on their selection, initiate a payment with a specific method. When the payer is presented with the payment gateway, the pre-selected payment method will be automatically displayed. Setting the chosen payment method is possible by filling in the 'method' parameter. Through this parameter, payment methods can also be filtered differently.
More here: https://apidoc.comgate.cz/en/metody-platebni-brany

Pre-authorization
The payment gateway allows to enter, confirm and cancel pre-authorizations of card payments. The payment is created in the standard way, it is only necessary to specify the parameter preauth = true. After Payer enters data at the payment gateway, the corresponding amount is reserved on his payment card. Depending on the result of this operation, it goes either to the special AUTHORIZED state or, in the case of rejection, to the CANCELLED state. This result is reported in the background according to the usual procedure described above.
In order for the money to be actually withdrawn, the e-shop calls the function to confirm the pre-authorization. If the money is to be released (eg it is not possible to meet the conditions of the purchase contract), the e-shop calls the function to cancel the pre-authorization.

ATTENTION

The URL and structure of the payment code may change. Always use the address returned by the API and do not tamper with it. If you want to save the payment code, use the transId parameter. Never parse data from specific positions in the text, they can also change.

All values containing special characters must be in UTF-8.

Request Body schema: application/x-www-form-urlencoded

Create new payment

merchant required	string E-shop identifier in the Comgate system - you can find it in the Client Portal in the section e-shop settings - e-shop connection
test	boolean Default: true A value of 'true' means that the payment will be created as a test, a value of 'false' means a production version. If the parameter is missing, the payment is created as production.
country	string Possible values: ALL, AT, BE, CY, CZ, DE, EE, EL, ES, FI, FR, GB, HR, HU, IE, IT, LT, LU, LV, MT, NL, NO, PL, PT, RO, SI, SK, SE, US. If the parameter is missing, 'CZ' is used automatically. The parameter is used to limit the selection of payment methods at the payment gateway. It is necessary to select the correct combination of 'country' and 'curr' parameters for the given region. For example, to display Czech buttons and pay by card in CZK, choose the combination country = CZ and curr = CZK. For Slovak bank buttons and card payments in EUR, select country = SK and curr = EUR. For Polish bank buttons and card payment in PLN, select country = PL and curr = PLN. For other foreign currencies, you can use the country = ALL parameter or another country code that the payment gateway accepts.
price required	integer <int32> Price for a product in cents or pennies. For currency HUF, you cannot enter the price with decimal places. In this case, the price must always end with 00. Must be in minimum of 1 CZK; 0,1 EUR; 1 PLN; 100 HUF; 1 USD; 1 GBP; 5 RON; 1 HRK; 0,5 NOK; 0,5 SEK. Maximum 1 000 000 CZK; 40 000 EUR; 170 000 PLN; 12 500 000 HUF; 45 000 USD; 35 000 GBP; 190 000 RON; 400 000 NOK; 390 000 SEK.
curr required	string Currency code according to ISO 4217. Available currencies: CZK, EUR, PLN, HUF, USD, GBP, RON, HRK, NOK, SEK.
label required	string Short description of the product (1-16 characters) - this item enable to filter payments in the Client Portal.
refId required	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.
method required	string Payment method from the payment methods table, the value 'ALL' in case the payer should choose the method, or a simple expression with the selection of methods. More here: https://apidoc.comgate.cz/en/metody-platebni-brany
account	string Identifier of the Client's bank account to which Comgate will transfer money. If you do not fill in the parameter, the default Client account will be used. You can find a list of the Client's accounts at https://portal.comgate.cz/.
email required	string Payer's contact email. Only one piece of information is required, either an email address or a phone number.
phone required	string Payer's phone number in international format +420777112233. Only one piece of information is required, either an email address or a phone number.
fullName required	string The payer's full name, e.g., Josef Novák.
billingAddrCity	string Billing address - city. (e.g., Hradec Králové).
billingAddrStreet	string Billing address - street. (e.g., Jiráskova 115).
billingAddrPostalCode	string Billing address - postal code. (e.g., 50304).
billingAddrCountry	string Billing address - country, in ISO 3166 alpha-2 format (e.g., CZ, SK, US, GB).
delivery	string Delivery method - one of the available options: HOME_DELIVERY, PICKUP, ELECTRONIC_DELIVERY. The PICKUP option encompasses all pickup locations, pickup boxes, etc.
homeDeliveryCity	string Delivery address - city. Only filled in if delivery=HOME_DELIVERY (e.g., Hradec Králové).
homeDeliveryStreet	string Delivery address - street. Only filled in if delivery=HOME_DELIVERY (e.g., Štefanikova 421).
homeDeliveryPostalCode	string Delivery address - postal code. Only filled in if delivery=HOME_DELIVERY (e.g., 50341).
homeDeliveryCountry	string Delivery address - country, in ISO 3166 alpha-2 format. Only filled in if delivery=HOME_DELIVERY (e.g., CZ, SK, US, GB).
category	string Product category in the basket - one of the available options that best describes the basket: PHYSICAL_GOODS_ONLY, OTHER. The OTHER option includes gift cards, vouchers, or services.
name	string Product identifier - this item is located in the client's daily csv under the name Product.
lang	string Language code (ISO 639-1) in which the Payer will be shown instructions for completing the payment, default allowed values ('bg', 'cs', 'da', 'de', 'el', 'en', 'es', 'et', 'fi', 'fr', 'hr', 'hu', 'it', 'lt', 'lv', 'nl', 'no', 'pl', 'pt', 'ro', 'si', 'sk', 'sv', 'vi'), if the parameter is missing, 'cs' will be used, in case of request for another language, contact platby-podpora@comgate.cz.
prepareOnly required	boolean Default: false In the case of creating payment in the background fill in 'true'. When creating a payment by redirection, fill in either 'false' or do not use the parameter. You can find which payment method is setted up as allowed in the Client Portal in the Integration section - connection of e-shop.
secret required	string If you create a background payment, fill in the password for background communication. When creating a payment by redirection, leave the parameter blank or do not use it.
preauth	boolean In the case of a request to pre-authorize credit card payments set to 'true'. In the case of a normal payment, fill in 'false' or do not use the parameter. Only for card payments.
initRecurring	boolean Parameter for creating an initial transaction for recurring payments. Only for Clients who have the service enabled.
verification	boolean Verification payment parameter, in case of a request to create a verification payment (value 'true') it is not necessary to send the initRecurring parameter.
expirationTime	string If you want to change the expiration date of an individual payment, you can do so by entering this parameter. The allowed value is between 30 minutes and 7 days. The default value is according to the settings in the Client Portal. The value is in the format: ^[1-9][0-9]*(m\|h\|d)$. For example,: 30m, 3h, 250m, 1d, 5d.
dynamicExpiration	boolean Enable or disable dynamic expiration. The default state is according to the settings in the Client Portal.
url_paid	string Custom settings for single payment. E.g.: 'https://www.example.com/result.php?id=${id}&refId=${refId}'
url_cancelled	string Custom settings for single payment. E.g.: 'https://www.example.com/result.php?id=${id}&refId=${refId}'
url_pending	string Custom settings for single payment. E.g.: 'https://www.example.com/result.php?id=${id}&refId=${refId}'

Responses

Response Schema: application/x-www-form-urlencoded

code required	integer Method return code and error (value of message) description: 0 OK 1100 unknown error 1102 specified language is not supported 1103 method incorrectly specified 1104 unable to load payment 1107 payment price not supported 1200 database error 1301 unknown e-shop 1303 missing link or language 1304 invalid category 1305 product description missing 1306 choose the correct method 1308 chosen payment method is not allowed 1309 wrong amount 1310 unknown currency 1311 Invalid Client's bank account identifier 1316 e-shop does not allow recurring payments 1317 invalid method - does not support recurring payments 1319 payment cannot be set up, problem on the bank's side 1399 unexpected result from database 1400 bad request 1500 unexpected error
message required	string
transId	string Unique alphanumeric identifier (code) of the transaction, which will be displayed to the Payer at various stages of payment.
redirect	string URL of the page where the Payer is to be redirected to make the payment.

Request samples

cURL
PHP
Java
Python
C#

# You can also use wget
curl -X POST https://payments.comgate.cz/v1.0/create \
--data "&merchant=123456&test=1&price=1000&curr=CZK&label=Product 123&refId=order445566&method=ALL&email=platce@email.com&fullName=Jan Novák&delivery=HOME_DELIVERY&category=PHYSICAL_GOODS_ONLY&prepareOnly=1&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y" \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Accept: application/x-www-form-urlencoded'

cancel

Storno of payment
If the order in the e-shop has been cancelled and the transaction is not to be completed by the payer, it is possible to use the storno of payment. Unlike a refund, the payment must be in the pending state.
Due to the speed of payment, the payment may already be paid, in which case an error will be displayed and the refund method must be used.

Request Body schema: application/x-www-form-urlencoded

Cancel payment

merchant required	string e-shop identifier in the Comgate system
transId required	string unique alphanumeric identifier (code) of the transaction (transactionId)
secret required	string password for background communication

Responses

Response Schema: application/x-www-form-urlencoded

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 PENDING status, unauthorized access)
message required	string

Request samples

cURL
PHP
Java
Python
C#

# You can also use wget
curl -X POST https://payments.comgate.cz/v1.0/cancel \
--data "&merchant=123456&transId=AB12-CD34-EF56&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y" \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Accept: application/x-www-form-urlencoded'

recurring

Recurring payments, remembering card details
The payment gateway allows you to enter recurring payments, that is, one-click payments. The first (initial) payment takes place through a standard process with redirection to the payment gateway, subsequent payments already take place completely in the background. The system thus allows the payer to pay within a few seconds without having to fill in information about the payment card.
This functionality is available on request. In the case of recurring payments at the beginning, we create an initial payment, which is created as a regular payment, only the request contains an additional parameter initRecurring - method create. Subsequent recurring payments are already created using the recurring method and are linked to the Comgate ID of the initiating transaction. This ID must be tied to a specific Payer in the Client's system.
After creating a recurring payment, the Payer is not redirected to the payment gateway, because the whole process takes place in the background, the Client is only given the status of the payment, and he then displays this status to the Payer.

Subsequent recurring payments
Creating a second and subsequent recurring payment to the payment gateway is only possible in the case of accepting cards for e-shops that have the service enabled.The first (initial) payment is made in the standard way (see Creating a payment). The process of creating a second and each subsequent payment takes place completely in the background, these payments are tied to the initiator via the Comgate ID of the initiation payment. This ID must be in the request in the initRecurringId parameter. The payer is shown the payment status in the e-shop system as a result.

All parameters are urlencoded, as in the case of an HTTP request to create a standard payment. The answer contains the code parameter, according to which the e-shop determines what result the payer will display. code = 0 means success, the payment was created and paid, any other code means an error and therefore no payment was created.

Recurring payments
Recurring payments with a predefined amount and period (eg monthly, weekly, etc.) can be made using the Recurring Payments service, which is described in the previous paragraphs.
Test recurring payments created with the e-mail 'recurring.cancelled@comgate.cz' will have all subsequent payments (apart from the initial one) tagged as CANCELLED (unpaid)

Request Body schema: application/x-www-form-urlencoded

merchant required	string e-shop identifier in the Comgate system
test	boolean A value of 'true' means that the payment will be created as a test, a value of 'false' means a production version. If the parameter is missing, the payment is created as production.
price required	string Price of the product in cents or pennies. Must be min. 10 CZK (incl.), Max. unlimited.
curr required	string Currency code according to ISO 4217, standard 'CZK'.
label required	string short product description (1-16 characters)
refId required	string Payment reference in the e-shop system (it does not have to be unique, i.e. it is possible to create multiple payments with the same refId).
account	string The identifier of the e-shop bank account to which Comgate will transfer the money. If you do not complete the parameter, the default e-shop account will be used. You can find a list of e-shop accounts at https://portal.comgate.cz/.
name	string Product identifier - this item allows you to navigate to the payment statistics of the Comgate payment system.
secret required	string password for background communication
initRecurringId required	string Comgate ID of the initial payment

Responses

Response Schema: application/x-www-form-urlencoded

code required	integer method return code and error description: 0 OK 1100 unknown error 1102 specified language is not supported 1103 method incorrectly specified 1104 unable to load payment 1200 database error 1301 unknown e-shop 1303 missing link or language 1304 invalid category 1305 product description missing 1308 selected payment method is not allowed 1309 incorrect amount 1310 unknown currency 1311 invalid e-shop bank account identifier 1316 e-shop does not allow recurring payments 1317 invalid method - does not support recurring payments 1318 initial payment not found 1319 can not create a payment, problem with the bank 1320 invalid email for recurring 1399 unexpected result from database 1400 wrong query 1500 unexpected error
message required	string
transId	string a unique alphanumeric transaction identifier (code) that will be displayed to the payer at various stages of payment

Request samples

cURL
PHP
Java
Python
C#

# You can also use wget
curl -X POST https://payments.comgate.cz/v1.0/recurring \
--data "&merchant=123456&test=1&price=10000&curr=CZK&refId=2010102600&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y&initRecurringId=AB12-CD34-EF56" \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Accept: application/x-www-form-urlencoded'

refund

Payment refund
The refund method is intended for payments already created and paid. Payment status must be paid. It is possible to make both a partial (refunded amount is lower than the payment amount) and a full refund (the refund amount is equal to the payment amount). The amount will be transferred back to the payer's account.
If the payment has not been completed and is in a pending state, it is possible to use the payment storno method.

Request Body schema: application/x-www-form-urlencoded

Payment refund

merchant required	string e-shop identifier in the Comgate system
transId required	string unique alphanumeric transaction identifier (code) (transactionId)
secret required	string password for background communication
amount required	string refund amount - can be the full or partial amount of the transaction. The refund amount is entered in cents or pennies. For the currency HUF, it is not possible to enter an amount with decimal places. In this case, the amount must always end with 00.
test	string A value of 'true' means that the refund will be created as a test. Refunds and payments will be verified in the standard manner, only the original payment will not be refunded. If 'false' is completed or the parameter is empty, an official refund is created. Test transactions can only be refunded by a test refund.
refId	string parameter suitable for entering the refund identification number on the customer's side (it does not have to be unique, i.e. it is possible to create multiple refunds with the same refId); in the Client Portal under refund section and the daily csv for the refund, the parameter is marked as the Client ID. If this parameter is not attached to the refund, the original refId of the created payment will be displayed for the payment.

Responses

Response Schema: application/x-www-form-urlencoded

code required	integer method return code and error description: 0 OK 1100 unknown error 1200 database error 1400 wrong query 1401 refunded payment is in CANCELLED status 1402 refund amount higher than allowed 1500 unexpected error
message required	string

Request samples

cURL
PHP
Java
Python
C#

# You can also use wget
curl -X POST https://payments.comgate.cz/v1.0/refund \
--data "&merchant=123456&transId=AB12-CD34-EF56&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y&amount=10000&test=1" \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Accept: application/x-www-form-urlencoded'

refundPos

Terminal payment refund
The refund method is intended for terminal payments already created and paid. Payment status must be paid. It is possible to make both a partial (refunded amount is lower than the payment amount) and a full refund (the refund amount is equal to the payment amount). The amount will be transferred back to the payer's account.
If the payment has not been completed and is in a pending state, it is possible to use the payment storno method.The server API may not have a payment record immediately available. Therefore, it is advisable to first call for a refund from the cash desk at the terminal. And the API call can be used if the refund cannot be called from the cash register on the terminal.
To use this method, it is necessary to first set the allowed IP addresses for the given terminal in the section Store settings - Terminals in the Client Portal, from which refunds will be made.

Request Body schema: application/x-www-form-urlencoded

Terminal payment refund

merchant required	string e-shop identifier in the Comgate system - can be found in the Client Portal in the Shop Settings - Terminals section
secret required	string password for background communication
vs required	string variable payment symbol
amount required	string refund amount - can be the full or partial amount of the transaction
date required	string date of execution of the transaction

Responses

Response Schema: application/x-www-form-urlencoded

code required	integer method return code and error description: 0 OK 1100 unknown error 1200 database error 1400 wrong query 1401 refunded payment is in CANCELLED status 1402 refund amount higher than allowed 1500 unexpected error
message required	string

Request samples

cURL
PHP
Java
Python
C#

# You can also use wget
curl -X POST https://payments.comgate.cz/v1.0/refundPos \
--data "&merchant=123456&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y&vs=7654321&amount=10000&date=2000-02-22" \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Accept: application/x-www-form-urlencoded'

capturePreauth

If the e-shop has created a payment with a request to pre-authorize the card payment (using the parameter preauth = true), calling this function will request the debiting of the money that was blocked through pre-authorization. It is possible to perform both the partial debiting of the transaction (the pre-authorized amount is lower than the payment amount) and full debiting (the debited amount is equal to the payment amount). Calls can only be used for payments for which AUTHORIZED status has been reported.

Request Body schema: application/x-www-form-urlencoded

Confirmation of pre-authorization

merchant required	string e-shop identifier in the Comgate system
transId required	string unique alphanumeric identifier (code) of the transaction (transactionId)
secret required	string password for background communication
amount	string the amount of pre-authorization to be debitd from the card - it can be in the full or partial amount of the transaction

Responses

Response Schema: application/x-www-form-urlencoded

code required	integer method return code and error description: 0 OK 1100 unknown error 1104 unable to load payment 1200 database error 1301 unknown e-shop 1303 missing link or language 1399 unexpected result from database 1400 wrong query 1500 unexpected error
message required	string

Request samples

cURL
PHP
Java
Python
C#

# You can also use wget
curl -X POST https://payments.comgate.cz/v1.0/capturePreauth \
--data "&merchant=123456&transId=AB12-CD34-EF56&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y" \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Accept: application/x-www-form-urlencoded'

cancelPreauth

If the e-shop has created a payment with a request to pre-authorize the card payment (using the parameter preauth = true), by calling this function the e-shop indicates that it does not want to collect the money that was blocked during pre-authorization and the money can be released to the card again. Calls can only be used for payments for which AUTHORIZED status has been reported.

Request Body schema: application/x-www-form-urlencoded

Cancelling pre-authorization

merchant required	string e-shop identifier in the Comgate system
transId required	string unique alphanumeric identifier (code) of the transaction (transactionId)
secret required	string password for background communication

Responses

Response Schema: application/x-www-form-urlencoded

code required	integer method return code and error description: 0 OK 1100 unknow error 1104 unable to load payment 1200 database error 1301 unknown e-shop 1303 missing link or language 1399 unexpected result from database 1400 wrong query 1500 unexpected error
message required	string

Request samples

cURL
PHP
Java
Python
C#

# You can also use wget
curl -X POST https://payments.comgate.cz/v1.0/cancelPreauth \
--data "&merchant=123456&transId=AB12-CD34-EF56&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y" \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Accept: application/x-www-form-urlencoded'

transferList

The transferList method is used to obtain information about which transfers were made within a given day.

Request Body schema: application/x-www-form-urlencoded

merchant required	string e-shop identifier in the Comgate system
secret required	string password for background communication
date required	string indicate the transfer date
test	boolean Default: false if the value is 'true', the method returns predefined sample transfer

Responses

Response Schema: application/json

Array

transferId	integer
transferDate	string <date>
accountCounterparty	string
accountOutgoing	string
variableSymbol	string

Request samples

cURL
PHP
Java
Python
C#

# You can also use wget
curl -X POST https://payments.comgate.cz/v1.0/transferList \
--data "&merchant=123456&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y&date=2023-03-22" \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Accept: application/x-www-form-urlencoded'

Response samples

Content type

application/json

[{"transferId": 1234567,
"transferDate": "2023-01-25",
"accountCounterparty": "0/0000",
"accountOutgoing": "123456789/0000",
"variableSymbol": "12345678"
}
]

singleTransfer

The singleTransfer method displays detailed information for a specific bank transfer.
The mandatory transferId parameter merchant obtained by using ttransferList method.

Request Body schema: application/x-www-form-urlencoded

merchant required	string e-shop identifier in the Comgate system
secret required	string password for background communication
transferId required	string mandatory parameter obtained using the transferList method
test	boolean Default: false suitable for testing - returns details to predefined sample transfers

Responses

Response Schema: application/json

Array

transferId	integer
transferDate	string <date>
accountCounterparty	string
accountOutgoing	string
variableSymbol	string

Request samples

cURL
PHP
Java
Python
C#

# You can also use wget
curl -X POST https://payments.comgate.cz/v1.0/singleTransfer \
--data "&merchant=123456&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y&transferId=1234567" \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Accept: application/x-www-form-urlencoded'

Response samples

Content type

application/json

[{"transferId": 1234567,
"transferDate": "2023-01-25",
"accountCounterparty": "0/0000",
"accountOutgoing": "123456789/0000",
"variableSymbol": "12345678"
}
]

csvSingleTransfer

Thanks to the csvSingleTransfer method, you can download the daily statement in CSV format for a specific bank transfer.

Request Body schema: application/x-www-form-urlencoded

merchant required	string e-shop identifier in the Comgate system
secret required	string password for background communication
transferId required	string details for a specific bank transfer
download	string If not filled in or false, it returns data: file name and its contents; if true, it returns the CSV file directly.
test	boolean Default: false returns a sample CSV file for testing purposes

Responses

Response Schema: application/json

nazev	string File name for the downloaded CSV file
csv	string Base64-encoded CSV file

Request samples

cURL
PHP
Java
Python
C#

# You can also use wget
curl -X POST https://payments.comgate.cz/v1.0/csvSingleTransfer \
--data "&merchant=123456&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y&transferId=5217530&download=false" \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Accept: application/x-www-form-urlencoded'

Response samples

Content type

application/json

{"nazev": "vypis-YYYY-MM-DD.csv",
"csv": "base64 encoded csv"
}

aboSingleTransfer

Thanks to the aboSingleTransfer method, you can download a daily statement in ABO format.

Request Body schema: application/x-www-form-urlencoded

merchant required	string e-shop identifier in the Comgate system
secret required	string password for background communication
transferId required	string details for a specific bank transfer
download	string If not filled in or false, it returns data: file name and its contents; if true, it returns the ABO file directly.
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 Default: "utf8" The character encoding can be utf8 or win1250. If the value is not filled in, the parameter value defaults to utf8.
test	boolean Default: false Returns a sample ABO file for testing purposes.

Responses

Response Schema: application/json

nazev	string file name
abo	string base64 encoded abo/gpc file

Request samples

cURL
PHP
Java
Python
C#

# You can also use wget
curl -X POST https://payments.comgate.cz/v1.0/aboSingleTransfer \
--data "&merchant=123456&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y&transferId=transfer_id&download=true&type=v1" \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Accept: application/x-www-form-urlencoded'

Response samples

Content type

application/json

{"nazev": "vypis-YYYY-MM-DD.gpc",
"abo": "base64_encoded_abo_file"
}

csvDownload

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.

Request Body schema: application/x-www-form-urlencoded

merchant required	string e-shop identifier in the Comgate system
secret required	string password for background communication
date required	string mandatory for one day only
test	boolean Default: false For testing purposes, it returns a sample CSV file in ZIP format.

Responses

Response Schema: application/zip

string <binary>

Request samples

cURL
PHP
Java
Python
C#

# You can also use wget
curl -X POST https://payments.comgate.cz/v1.0/csvDownload \
--data "&merchant=123456&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y&date=YYYY-MM-DD" \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Accept: application/x-www-form-urlencoded'

aboDownload

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.

Request Body schema: application/x-www-form-urlencoded

merchant required	string e-shop identifier in the Comgate system
secret required	string password for background communication
date required	string mandatory for one day only
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 The character encoding can be utf8 or win1250. If the value is not filled in, the parameter value defaults to utf8.
test	boolean Default: false For testing purposes, it returns a sample CSV file in ZIP format.

Responses

Response Schema: application/zip

string <binary>

Request samples

cURL
PHP
Java
Python
C#

# You can also use wget
curl -X POST https://payments.comgate.cz/v1.0/aboDownload \
--data "&merchant=123456&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y&date=YYYY-MM-DD" \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Accept: application/x-www-form-urlencoded'

methods

Obtaining allowed methods
Method for obtaining the settings that the e-shop has enabled in the Comgate Payment System. This method can be used to obtain a list of available payment methods for making payments.
The response contains XML or JSON, depending on the selected parameter. Both formats have the same level of immersion.

Request Body schema: application/x-www-form-urlencoded

Get payment methods

merchant required	string e-shop identifier in the Comgate system
secret required	string password for background communication
type	string Format of returned data ('xml' or 'json'). If not filled in, 'xml' will be used.
lang	string Select the language in which the method descriptions will be. Allowed values are 'bg', 'cs', 'da', 'de', 'el', 'en', 'es', 'et', 'fi', 'fr', 'hr', 'hu', 'it', 'lt', 'lv', 'nl', 'no', 'pl', 'pt', 'ro', 'si', 'sk', 'sv', 'vi'. If not filled in, 'cs' will be used.
curr	string Filling in the parameter to the values CZK or EUR will return methods that support the specified currency (CZK, EUR, PLN, HUF, USD, GBP, RON, NOK, SEK).
country	string Country code ('AT', 'BE', 'CY', 'CZ', 'DE', 'EE', 'EL', 'ES', 'FI', 'FR', 'GB', 'HR', 'HU', 'IE', 'IT', 'LT', 'LU', 'LV', 'MT', 'NL', 'NO', 'PL', 'PT', 'RO', 'SL', 'SK', 'SE', 'US'), the parameter is used to limit the selection of payment methods for the specified country.
price	integer <int32> Price for a product in cents or pennies. For currency HUF, you cannot enter the price with decimal places. In this case, the price must always end with 00. Must be in minimum of 1 CZK; 0,1 EUR; 1 PLN; 100 HUF; 1 USD; 1 GBP; 5 RON; 1 HRK; 0,5 NOK; 0,5 SEK. Maximum 1 000 000 CZK; 40 000 EUR; 170 000 PLN; 12 500 000 HUF; 45 000 USD; 35 000 GBP; 190 000 RON; 400 000 NOK; 390 000 SEK.
initRecurring	boolean Default: false Parameter for an initial transaction for recurring payments. Only for Clients who have the service enabled.
verification	boolean Default: false Parameter for creating an initial transaction for recurring payments. Only for Clients who have the service enabled.
preauth	boolean Default: false In the case of a request to pre-authorize credit card payments set to ‘true’. In the case of a normal payment, fill in ‘false’ or do not use the parameter. Only for card payments.
expirationTime	string Length of payment expiration. The allowed value is an integer followed by the letter of the selected time unit: 'm' (minutes), 'h' (hours) or 'd' (days). For example '30m' (30 minutes) or '10h' (10 hours) or '2d' (2 days). Units cannot be combined. The resulting length must be between 30 minutes and 7 days.
embedded	boolean The 'embedded' parameter is used to filter methods in case the gateway will be displayed in an iframe. Payment methods that cannot be displayed on the payment gateway in the iframe will be filtered out. If you are displaying the payment gateway in an iframe, use 'embedded=true'.
userAgent	string The 'userAgent' parameter is used to identify the customer's web browser. Filters out payment methods incompatible with the given device.

Responses

Response Schema: application/json

required

Array of objects

Available methods

Array

id	string ID of the method
group	string Group of the method
groupLabel	string Label of the method group
name	string Name of the method
name_short	string The short name of the method
description	string Description of the method
logo	string Logo of the method
logo_240	string 240px logo of the method
cblogo	string Centered bigger logo of the method
clogo	string Centered logo of the method
sblogo	string Squared bigger logo of the method
slogo	string Squared logo of the method

Response Schema: application/json

required

Array of objects

Error

Array

code	string
message	string method return code and error description: 0 OK 1100 unknown error 1200 database error 1400 wrong query 1500 unexpected error
extraMessage	string specification of the error message

Request samples

cURL
PHP
Java
Python
C#

# You can also use wget
curl -X POST https://payments.comgate.cz/v1.0/methods \
--data "&merchant=123456&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y&type=json" \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Accept: application/x-www-form-urlencoded'

Response samples

Content type

application/json

{"methods": [{"id": "string",
"group": "string",
"groupLabel": "string",
"name": "string",
"name_short": "string",
"description": "string",
"logo": "string",
"logo_240": "string",
"cblogo": "string",
"clogo": "string",
"sblogo": "string",
"slogo": "string"
}
]
}

status

Getting payment status in the background
Analogous function for transmitting the result of payment in the background, only initiated by the Store. However, it does not replace the transfer of the status of the payment in the background, its implementation is still mandatory.

Request Body schema: application/x-www-form-urlencoded

Get payment status

merchant required	string e-shop identifier in the Comgate system
transId required	string unique alphanumeric identifier (code) of the transaction (transactionId)
secret required	string password for background communication

Responses

Response Schema: application/x-www-form-urlencoded

code required	string 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
merchant required	string e-shop identifier in the Comgate system
test required	string A value of 'true' means that the payment was created as a test, a value of 'false' means a production version.
price required	string price of the product in cents or pennies
curr required	string currency code according to ISO 4217
label required	string short product description (1-16 characters)
refId required	string payment references in the e-shop system
payerId	string payer identifier in the e-shop system
method	string payment method used, from the table of payment methods
account	string identifier of the e-shop bank account to which Comgate will transfer the money
email required	string payer's contact e-mail
name	string product identifier - this item allows you to navigate to the payment statistics of the Comgate payment system
transId required	string unique alphanumeric transaction identifier (code) (transactionId)
secret required	string password for background communication
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
payerName	string transmission of the name of the account belonging to the payer
payerAcc	string transmission of the payer's account number
fee	string if the e-shop has set up automatic deduction of the payment fee, the transaction fee will be calculated in this field in cents or pennies, otherwise the field will take the value 'unknown'
vs	string variable payment symbol (may not always be available)
cardValid	string expiration of the payer's card available for repeated initiation payments
cardNumber	string partial payer card number available for recurring initiation payments
appliedFee	integer The surcharge amount applied for unregulated card types.
appliedFeeType	string The type of surcharge applied for unregulated card types, such as 'EU_UNREGULATED', 'NON_EU_BUSINESS', 'NON_EU_CONSUMER', or non-surcharge 'EU_CONSUMER'.

Request samples

cURL
PHP
Java
Python
C#

# You can also use wget
curl -X POST https://payments.comgate.cz/v1.0/status \
--data "&merchant=123456&transId=AB12-CD34-EF56&secret=gx4q8OV3TJt6noJnfhjqJKyX3Z6Ych0y" \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Accept: application/x-www-form-urlencoded'