Skip to main content

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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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
[
  • {
    }
]

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
typ
integer
Merchant
string
Datum založení
string
Datum zaplacení
string
Datum převodu
string
Měsíc fakturace
string
ID Comgate
string
Metoda
string
Produkt
string
Popis
string
E-mail plátce
string
Variabilní symbol platby
string
Variabilní symbol převodu
string
ID od klienta
string
Měna
string
Potvrzená částka
string
Převedená částka
string
Poplatek celkem
string
Poplatek mezibankovní
string
Poplatek asociace
string
Poplatek zpracovatel
string
Typ karty
string

Request samples

# 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
[
  • {
    }
]

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

# 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

# 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

# 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

# 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

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

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

# 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'