ComGate payments API protocol 

HTTP POST protokol specification

The connection between the online shop and the ComGate payment gateway is implemented by redirecting the Payer from online shop to the payment gateway. After making the payment, the Payer is redirected back to the online shop. At the same time, communication between the online shop server and the payment gateway server (server – server) takes place in the background. A detailed description of the communication protocol can be found below on this page. Further related information can be found on the pages that describe the payment process from the user’s  and online shop’s point of view, initial settings in the client portal, the recommended way to test payment gateway integration or a detailed description of EET connections. 

Sample implementation in PHP can be downloaded here.  

Payment process

Payment creation – optional

This step is optional but it is recommended to implement it in every case you need to be sure that the payment is created secure way and without possible Payer intervention. It also ensure unique linkage of payment to order. Omitting this step is applicable only if e-shop do not need a system to identify each payment, but just needs an information that anyone paid any amount. For classic online shop, where you pay for a specific good is skipping this step inappropriate .

Merchant uses HTTP request to create payment transaction. Payment attributes including unique payment reference number are sent as POST parameters by HTTP protocol. Communication is only between Merchant’s server and server of ComGate Payments and is invisible to Payer. So Payer is not able to change payment parameters. ComGate Payments server responds by sending unique payment transaction identifier – Transaction ID (ComGate Payments identifier) and URL to redirect Payer to.

Example of payment transaction creation on background – HTTP request:

POST /v1.0/create HTTP/1.1
Host: payments.comgate.cz
Content-Type: application/x-www-form-urlencoded; charset=utf-8

merchant=merchant_com&price=10000&curr=CZK&label=Beatles%20-0%Help!&refId=2010102600&cat=DIGITAL&method=ALL&prepareOnly=true&secret=ZXhhbXBsZS5jb206QUJDeHl6

Example of payment transaction creation on background – HTTP response:

HTTP/1.1 200 OK
Content-Type: application/x-www-form-urlencoded; charset=utf-8

code=0&message=OK&transId=AB12-EF34-IJ56&redirect=https%3A%2F%2Fpayments.comgate.cz%2Fclient%2Finstructions%2F%3Fid%3DABCDEFGHIJ

Communication between Merchant’s system and system ComGate Payments is secured using password and IP whitelist (access is allowed from predefined Merchants IP’s only). It is strongly suggested to use HTTPS protocol that is safe to not reveal password even if communication is intercepted. Password is sent as HTTP POST parameter (not GET parameter) for not to be stored in communication logs of webservers.

Redirection to ComGate Payments webserver

If previous optional, but more securing step is used and payment transaction is already created that way, it’s Merchant’s webserver task to redirect Payer to URL address that was returned in ComGate Payments system’s HTTP response.

HTTP response 302

HTTP/1.1 302 Found
Location: https://payments.comgate.cz/client/instructions?id=ABCDEFGHIJ

If the first optional step is omitted, payment transaction is created after Payer is redirected from Merchant’s server to ComGate Payments server or by posting web form from Merchant’s website to ComGate Payments server. Payment attributes, including unique payment reference number are sent using HTTP protocol as POST or GET parameters.

Example of Payment transaction creation by redirect (web form submit) – HTTP request:

POST /v1.0/create HTTP/1.1
Host: payments.comgate.cz
Content-Type: application/x-www-form-urlencoded; charset=utf-8

merchant=merchant_com&price=10000&curr=CZK&label=Beatles%20-20Help!&refId=2010102600&cat=DIGITAL&method=ALL

This communication is not secured so it is possible for Payer to change payment parameters if you nacces the first optional step.

Payment transaction status handover on background – required

Implementing this part ensures automatic transmission of status of each payment transaction directly to your server at the moment the final status is known.

Payment status is delivered to Merchant using HTTP request from ComGate Payments system directly to Merchant’s server. Identifiers and payment status are sent as POST parameters using HTTP protocol. This is background communication.

Payer is redirected back to Merchant’s website while payment transaction identifiers are sent as GET parameters of HTTP protocol. Any goods or service providing must be based on the background payment status handover. It is not safe to rely on the Merchant’s website URL to which the Payer is redirected because it is really easy to fraud.

Example of payment transaction status handover on background – HTTP request

POST /handler.php HTTP/1.1
Host: eshop.com
Content-Type: application/x-www-form-urlencoded; charset=utf-8

merchant=merchant_com&test=false&price=10000&curr=CZK&label=Beatles%20-%20Help!&refId=2010102600&method=CARD&email=info%40customer.com&phone=%2B420123456789&transId=AB12-EF34-IJ56&secret=ZXhhbXBsZS5jb206QUJDeHl6&status=PAID

Example of payment transaction status handover on background – HTTP response

HTTP/1.1 200 OK
Content-Type: application/x-www-form-urlencoded; charset=utf-8

code=0&message=OK

Communication between Merchant’s system and system ComGate Payments is secured using password and IP whitelist. Access has to be allowed from range of ComGate Payments IP addresses only. This range is defined as 89.185.236.55/32. It is strongly suggested to use HTTPS protocol that is safe to not reveal password even if communication is intercepted. Password is sent as HTTP POST parameter (not GET parameter) for not to be stored in communication logs of webservers. 

Merchant assures that the goods (service) provided in the scope of payment transaction (identified by unique transaction ID) is provided only once. Even in case of multiple background calls with the same transaction ID. It’s Merchant’s own responsibility to somehow register, using his system (database), that the goods (service) were already provided. Merchant is also responsible for providing right goods (service) only to Payer who made the payment. It means that Merchant registers linkage between transaction ID and Payer ID in his system (database) after authentication of Payer on Merchant’s website. Another way is storing any unique identifier in session (cookie) of Payer’s browser and pairing this identifier to right transaction ID.

Redirection of Payer to Merchant’s website

Based on payment transaction status, Payer is redirected to one of the tree URLs. The URLs are defined by Merchant on service activation. Payment transaction identifiers are sent as GET parameters by HTTP protocol. Merchant’s system must be able to deal with two basic situations:

  • The result of payment is not yet known at the time of redirection of Payer back to Merchant’s website. Payment is at the PENDING status. This is the common situation and Merchant can’t present this status as a failure. System is either waiting for crediting payment to bank account or to confirmation from Payment provider, ie. bank or mobile operator. Final payment result is communicated to Merchant later. It is done either by sending result of payment by background server communication or by sending him email. Next source of payment status information is ComGate Payments website.
  • If the ComGate Payments system knows the result of payment instantly, Payer is redirected to the URL (PAID or CANCELLED). If Merchant implemented handover of payment transaction on background, redirection to Merchant’s website is made after the successful handover of payment transaction result on background. It is not possible to provide ordered goods or service to Payer just based on URL to which is returned. It is easy to fraud payment transaction result this way by making browser to request to changed URL. Merchant have to implement receive payment transaction result on background or manually check at ComGate Payments website that the payment was really made.
Example of redirection of Payer to Merchant’s website – HTTP request

GET /result_ok.php?refId=2010102600&transId=AB12-EF34-IJ56 HTTP/1.1
Host: eshop.com

Payment states

  • PENDING – Payment transaction was created, final result of payment is not yet known.
  • PAID – Payer successfully realized payment – it is possible to deliver goods, provide service.
  • CANCELLED – Payment was not realized, goods or service is not provided. At exceptional cases it is possible for this state to turn to PAID state.

Only the payment transaction at state PAID can be considered as really paid. PENDING state is not final and it is possible to switch to state CANCELLED.

API protokol payment states

Payment states

Security

Communication between the ComGate payment system and Merchant’s system takes place in three ways.

  • The server part of Merchant’s system connects to the server part of the payment gateway and calls methods for creating a payment, obtaining the payment status in the background, confirming pre-authorization, canceling pre-authorization and obtaining a list of payment methods.
  • The server part of the payment gateway connects to the server part of Merchant’s system and calls the method for transmitting the payment result in the background.
  • The browser of the Payer (user) is redirected from the Merchant’s website to the payment gateway and then from the payment gateway back to the Merchant’s website.

In all three cases, it is necessary to use the encrypted HTTPS protocol. The payment gateway only supports secure TLS / SSL protocol settings with the following ciphers enabled: https://github.com/cloudflare/sslconfig/blob/master/conf

In the case of server – server communication, the communication is secured by means of a password (secret) and IP whitelist settings. These parameters can be set in the client portal.

Creating a payment is preceded by the Cloudflare service. You can find a list of allowed Cloudflare IP addresses here: https://www.cloudflare.com/ips-v4

The range of IP addresses used by ComGate is defined as 89.185.236.55/32. This range is only used to pass the result of the payment in the background.

Other types of card transactions

Preauthorization

ComGate Payments payment system allows creating, submitting and canceling preauthorization of card payments.

Payment creation has standard process, only parameter preauth=true must be specified. After that, payer passes the same process as in case of normal payment. After entering card detail to the payment gateway, relevant amount is blocked on his credit card. Depending on result of this operation, payment passes either to special state AUTHORIZED, or in case of rejection to state CANCELLED. This state is reported in background by usual process described above.

To actually deduct the money, the Merchant’s website calls function for submitting preauthorization. If money are supposed to be released (eg. it is not possible to fulfill conditions of purchase contract), the Merchant’s website calls function for cancelling preauthorization.

Obrázek API protokol - Potvrzení platby- platební brána ComGate

API protokol - ComGate payment gateway

Recurring payments (card-on-file)

ComGate Payments system also allows entering recurring payments. Recurring payments allow Payer to make quick payments with one click. First (initial) payment is a standard process with redirection to the payment gateway; the following payments are being done completely on background. The system allows Payer to pay within seconds without need to fill in his credit card information.

This functionality is available on request. In case of recurring payments, it is necessary to establish initial payment at first. This payment is a standard payment with initRecurring parameter set to “true”. Subsequent recurring payments are established with new method and are bound to initial payment by ComGate ID. This ID must be tied to a particular Payer in Merchant’s system!

After establishing recurring payment, Payer is not redirected to payment gateway, because the whole process runs in background. Payment’s state is passed to Merchant’s system and then shown to Payer.

Verification transactions

If the Merchant wants to use recurring payments in the future, but wants Payer to „register“ now, he can use verification transaction. If parameter “verification” is set to “true”, standard initial transaction is established, but is automatically refunded after being paid.

In terms of recurring payments, this transaction appears to be standard initial transaction; subsequent payments are bound to verification transaction. Notice! Because of bank limitations, it is not possible to combine preauthorization and recurring payments.

Pre-filled card details

The payment gateway enables the Payer's card data to be memorized in such a way that the card number and validity data will be automatically pre-filled during the subsequent payment at the payment gateway. To complete the payment, he simply enters the CVV code. In this case, the Payer is redirected to the payment gateway's website, unlike the functionality of recurring payments, where the subsequent payment can take place fully in the background, without the Payer's participation.

This functionality is available on request. To use it, it is necessary to fill in the PayerId parameter when creating a payment. The Merchant must ensure verification and registration of the Payer within the Merchant’s website.

Description of API methods

Payment creation

Access is protected by IP address validation and the integrity of transmitted data is ensured using the HTTPS protocol. URL metods: https://payments.comgate.cz/v1.0/create

Request parameters

parametr

type

required

description

merchant

string

Y

online shop identifier in the ComGate system – you can find it in the client portal in the section Shop settings – Shop connection.

test

boolean

N

A value of "true" means that the payment will be established as a test, a value of "false" means a production version. If the parameter is missing, the payment is created as production.

country

string

N

The country code ("CZ", "SK", "PL", "ALL") is used to restrict the selection of payment methods at the payment gateway. The correct combination of "country" and "curr" parameters needs to be selected for the region. For example, to display the 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, use country = ALL.
If the parameter is missing, "CZ" is used.

price

integer

Y

Price per product in cents or pennies.

Must be min. 1 CZK; 0,1 EUR; 1 PLN; 100 HUF; 1 USD; 1 GBP, 5 RON, 1 HRK 
Max. unlimited.

curr

string

Y

Currency code according to ISO 4217, default is "CZK".

label

string

Y

Short description of the product (1-16 characters) – according to this item it is possible to filter payments in the client portal.

refId

string

Y

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

payerId

string

N

Payer identifier in the Merchant's system. The identifier must be verified, for example, by the Payer's login to the Merchant's system using a password, if it is not, then do not fill in the parameter. It is used when paying by card, where the payment gateway stores the card numbers of the Payers, so that the Payer does not have to enter the card number again during the next payment. This function must be enabled for a specific Merchant in the card processor system.

method

string

Y

The method of payment from the table of payment methods, the value "ALL" if the method is to be chosen by the Payer, or a simple expression with the choice of methods (described below).

account

string

N

Identifier of the Merchant's bank account to which ComGate Payments will transfer money. If you do not fill in the parameter, the default Merchant account will be used.

email

string

Y

Contact e-mail to the Payer (for the purposes of a possible complaint)

phone

string

N

Contact telephone number to the Payer (for the purposes of a possible complaint)

name

string

N

Product identifier – this item is located in daily csv. named Product.

lang

string

N

Language code (ISO 639-1) in which the Payer will be shown instructions for completing the payment, default values ("cs", "sk", "en", "pl", "fr", "ro", "de", "hu", "si", "hr"), if the parameter is missing, "cs" is used.

prepareOnly

boolean

Y

Fill in "true" if you have a background payment. When creating a payment by redirection, fill in either "false" or do not use the parameter. If you need to find out which method of setting up your payment you have set up, take a look at the client's portal in the Integration - Business Link section.

secret

string

N

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 N If you require pre-authorization of a card payment, set it to "true". In the case of a normal payment, fill in "false" or do not use the parameter. Only for card payments.

initRecurring

boolean

N

Designation for the establishment of an initial transaction for recurring payments. Only for Merchants who have the service enabled.

verification

boolean

N

Verification payment parameter, in case of a request to create a verification payment (value "true") it is not necessary to send the initRecurring parameter.

eetReport

boolean

N

Indication of sending data to EET. If filled in, it overloads the EET settings in the store configuration in the client portal.

eetData

JSON

N

Structure with data for registration of payment to EET. Corresponds to parameters from the EET protocol specification. If the Merchant's website has set up sending sales to EET and the parameter is not filled in, the default settings from the configuration in the client portal will be used.

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

Response parameters

parametr

type

required

description

code

integer

Y

Return code of method and error description: 
0 OK
1100 unknown error
1102 requested language is not supported
1103 unexpected count of specified methods
1104 cannot find payment update
1107 payment price is not supported
1200 DB error
1301 unknown merchant
1303 interface URLs or language is missing
1304 invalid category specified
1305 product label is missing
1306 no valid method specified
1308 specified payment option is not enabled for you
1309 invalid payment amount
1310 unknown currency of payment price
1311 invalid bank account identifier
1316 recurring payments are not enabled for Merchant
1317 invalid method – does not support recurring payments
1319 can’t settle payment, provider error
1399 unexpected result from DB method
1400 request error
1500 unexpected error

message

string

Y

transId

string

N

Alphanumerical unique identifier of transaction - transaction Id. Will be shown to Payer while making payment.

redirect

string

N

URL to redirect Payer to start payment.

Example of Payment transaction creation by redirect (web form submit) – HTTP request

POST /v1.0/create HTTP/1.1
Host: payments.comgate.cz
Content-Type: application/x-www-form-urlencoded; charset=utf-8

merchant=merchant_com&price=10000&curr=CZK&label=Beatles%20-%20Help!&refId=2010102600&cat=DIGITAL&method=ALL

Example of Payment transaction creation on background – HTTP request

POST /v1.0/create HTTP/1.1
Host: payments.comgate.cz
Content-Type: application/x-www-form-urlencoded; charset=utf-8

merchant=merchant_com&price=10000&curr=CZK&label=Beatles%20-%20Help!&refId=2010102600&cat=DIGITAL&method=ALL&prepareOnly=true&secret=ZXhhbXBsZS5jb206QUJDeHl6


Example of Payment transaction creation on background – HTTP response

HTTP/1.1 200 OK
Content-Type: application/x-www-form-urlencoded; charset=utf-8

code=0&message=OK&transId=AB12-EF34-IJ56&redirect= https%3A%2F%2Fpayments.comgate.cz%2Fclient%2Finstructions%2Findex%3Fid%3DABCDEFGHIJ

Self-selection of methods

ComGate Payment Gateway allows Payer’s own choice of payment methods through a simple expression sent in “method” parameter. This expression is always evaluated on the basis of Payer’s allowed methods.

If the method parameter is not filled in with one specific value, the offer of payment methods will be displayed on the payment gateway. The offer of payment methods can be specified by a simple expression, which is entered in the method parameter. The expression is always evaluated on the basis of the methods that the online shop has enabled.

Permitted method identifier delimiters are “+” for imputation method and “-“ for subtraction method to/from selection.

Example:

BANK_ALL + CARD_CZ_CS – BANK_CZ_KB = all bank methods with card payments without ePlatba+ for Komerční banka clients.

BANK_CZ_CS_P + BANK_CZ_KB + BANK_CZ_RB = only ePlatba+ from Česká spořitelna, Komerční banka and Reiffeisen Bank clients (only these 3 as opposite for BANK_ALL, that would select all bank methods from Merchant’s methods)

ComGate Payment Gateway allows Payer to have pre-selected one method when accessing gateway. The only thing to achieve this behavior is to redirect Payer to gateway with received redirect URL that in addition contains parameter “method” with selected method.

Redirect URL could look like this example
https://payments.comgate.cz/client/instructions/index?id=ABCDEFGHIJ&method=CARD_CZ_CS

After redirecting to gateway, Payer would have already checked method CARD_CZ_CS, although he can still choose another method. This function is useful only for payments created with methods BANK, BANK_ALL or with own methods selection.

Recurring payments

If the online shop fills in the initRecurring parameter, an initiating transaction will be created for recurring payments. It is then possible to base recurring payments on the ComGate ID of this transaction. The response parameters do not change in this case. Creating an initial payment is only possible for online shops that have the service enabled and when using a card payment.

Verification payments

When the verification parameter is set to "true", a verification transaction is created. Once the Payer has made the payment, it will be automatically refunded, so it is not necessary to refund the payment manually. The authentication transaction otherwise works in the same way as the initial transaction, ie. it is possible to create recurring payments using its ComGate ID.

Zasílání tržby do EET

Do systému EET musí obchodník evidovat každou platbu provedenou kartou nebo v hotovosti. Daňoví plátci musí posílat detail daně, neplátci DPH pouze celkovou částku. Další informace jsou obsaženy v EET řešení.

Nejprve se obchodník musí zaregistrovat do EET a stáhnout si certifikát pro zabezpečenou komunikaci. Následně obchodník provede konfiguraci propojení s EET v rozhraní klientského portálu.

Pokud je EET správně nastaveno v klientském portálu, pak je možné přejít k založení platby. V rámci plateb EET se rozlišují dva režimy:

  1. Automatický (výchozí) režim umožňuje obchodníkovi posílat platby do EET, aniž by musel implementovat něco navíc do komunikačního protokolu platební brány ComGate. Tento režim slouží neplátcům DPH a plátcům DPH, kteří prodávají zboží pouze v jedné daňové sazbě odpovídající nastavení v klientském portálu. Pokud je platba provedena v zahraniční měně, bude do EET zaevidovaná v Kč a jako kurz pro přepočet se použije kurz dané měny vyhlášený ČNB z předchozího dne.
  2. Rozšířený režim přináší nutnost upravit komunikační protokol platební brány ComGate. Do protokolu bude obchodník posílat kompletní rozpad částky pro EET v parametru eetData (viz příklad níže, názvy parametrů jsou dle specifikace EET). Tento režim je nutný pro všechny, kdo prodávají zboží ve více sazbách DPH, cestovní služby, prodávají a uplatňují vouchery nebo prodávají použité zboží. Data se předávají ve formátu JSON, částky jsou uváděny v haléřích.
Popis JSON struktury s daty EET (eetData):

Parametr

typ

povinný

Popis

celk_trzba

integer

A

celková částka tržby

zakl_nepodl_dph

integer

N

celková částka plnění osvobozených od DPH, ostatních plnění

zakl_dan1

integer

N

celkový základ daně se základní sazbou DPH

dan1

integer

N

celková DPH se základní sazbou

zakl_dan2

integer

N

celkový základ daně s první sníženou sazbou DPH

dan2

integer

N

celková DPH s první sníženou sazbou

zakl_dan3

integer

N

celkový základ daně s druhou sníženou sazbou DPH

dan3

integer

N

celková DPH s druhou sníženou sazbou

cest_sluz

integer

N

celková částka v režimu DPH pro cestovní službu

pouzit_zboz1

integer

N

celková částka v režimu DPH pro prodej použitého zboží se základní sazbou

pouzit_zboz2

integer

N

celková částka v režimu DPH pro prodej použitého zboží s první sníženou sazbou

pouzit_zboz3

integer

N

celková částka v režimu DPH pro prodej použitého zboží s druhou sníženou

urceno_cerp_zuct

integer

N

celková částka plateb určená k následnému čerpání nebo zúčtování

cerp_zuct

integer

N

celková částka plateb, které jsou následným čerpáním nebo zúčtováním

Příklad struktury EET:

1. Zákaznice zakoupila obnošenou bundu za 330 Kč, nové nenošené punčocháče za 50 Kč a potraviny za 115 Kč.

{
"celk_trzba": "49500",
"zakl_nepodl_dph": "0",
"zakl_dan1": "4132",
"dan1": "868",
"zakl_dan2": "10000",
"dan2": "1500",
"zakl_dan3": "0",
"dan3": "0",
"cest_sluz": "0",
"pouzit_zboz1": "33000",
"pouzit_zboz2": "0",
"pouzit_zboz3": "0",
"urceno_cerp_zuct": "0",
"cerp_zuct": "0"
}

2. Zákazník vložil celou částku 500 Kč do své elektronické peněženky a zároveň z této peněženky
uhradil nákup zboží v ceně 200 Kč včetně DPH.

{
"celk_trzba": "50000",
"zakl_nepodl_dph": "0",
"zakl_dan1": "16528",
"dan1": "3472",
"zakl_dan2": "0",
"dan2": "0",
"zakl_dan3": "0",
"dan3": "0",
"cest_sluz": "0",
"pouzit_zboz1": "0",
"pouzit_zboz2": "0",
"pouzit_zboz3": "0",
"urceno_cerp_zuct": "50000",
"cerp_zuct": "20000"
}

3. Zákazník zaplatil celkem 18 000 Kč, z této částky zakoupil zájezd v ceně 17 500 Kč, za 200 Kč nakoupil zboží a 300 Kč přibylo na jeho zákaznickém účtu
pro následné čerpání (nabíjení „kreditu“).

{
"celk_trzba": "1800000",
"zakl_nepodl_dph": "0",
"zakl_dan1": "16528",
"dan1": "3472",
"zakl_dan2": "0",
"dan2": "0",
"zakl_dan3": "0",
"dan3": "0",
"cest_sluz": "1750000",
"pouzit_zboz1": "0";
"pouzit_zboz2": "0",
"pouzit_zboz3": "0",
"urceno_cerp_zuct": "30000",
"cerp_zuct": "0"
}

Forward payment result (push)

The payment gateway passes the final status of the payment via HTTP request to the Merchant’s server. The parameters of this call specify the detail of the just completed payment.

URL metods: https://adresa-vaseho-e-shopu/absdefg - the method is called on the Merchant’s server

Parametry volání

parameter

type

required

description

merchant

string

Y

Merchant identifier

test

boolean

Y

The „true“ means payment was created as testing one, „false“ means payment was created as production one.

price

integer

Y

Product price in cents or pennies

curr

string

Y

Currency code - ISO 4217

label

string

Y

Short description of product displayed to Payer (1-16 characters)

refId

string

Y

Referral payment ID from Merchant’s system.

payerId

string

N

The Payer identifier from Merchant’s system.

payerName string N The Payer’s name from Merchant’s system.
payerAcc string N The Payer’s account from Merchant’s system.

method

string

N

Payment method used. It is one from the list of payment methods.

account

string

N

Identifier of Merchant’s bank account.

email

string

Y

Payer’s e-mail

phone

string

N

Payer’s mobile number

name

string

N

Product identifier – attribute is helpful for search in ComGate Payments – statistics of payments page

transId

string

Y

Alphanumerical unique identifier of transaction – transaction Id

secret

string

Y

Password for background communication

status string Y Actual transaction state, values: „PAID“ – payment was successfully paid „CANCELLED“ – payment was not finished correctly and was cancelled „AUTHORIZED” – requested preauthorization was successful

fee

string

N

In case that Merchant has automatic charging enabled, this field will contain transaction fee, otherwise will contain value „unknown”

eetData

JSON

N

Structure with data after registration of the payment in EET

Response parameters

parameter

type

required

description

code

integer

Y

Return code of method and error
description:
In case of result was received successfully, our system expects the return code 0 and description „OK”

Example of payment transaction status handover on background – HTTP request

POST /handler.php HTTP/1.1
Host: eshop.com
Content-Type: application/x-www-form-urlencoded; charset=utf-8

merchant=merchant_com&test=false&price=10000&curr=CZK&label=Beatles%20-%20Help!&refId=2010102600&cat=DIGITAL&method=CARD&email=info%40customer.com&phone=%2B420123456789&transId=AB12-EF34-IJ56&secret=ZXhhbXBsZS5jb206QUJDeHl6&status=PAID

Example of payment transaction status handover on background – HTTP response

HTTP/1.1 200 OK
Content-Type: application/x-www-form-urlencoded; charset=utf-8code=0&message=OK

Popis JSON struktury s daty EET (eetData):

parametr

typ

povinný

Popis

fik

string

N

fiskální identifikační kód poplatníka

bkp

string

A

bezpečnostní kód poplatníka

pkp

string

N

podpisový kód poplatníka zakódovaný v base64

celk_trzba

integer

A

celková částka tržby

poradove_cislo

integer

A

pořadové číslo účtenky

zakl_nepodl_dph

integer

N

celková částka plnění osvobozených od DPH, ostatních plnění

zakl_dan1

integer

N

celkový základ daně se základní sazbou DPH

dan1

integer

N

celková DPH se základní sazbou

zakl_dan2

integer

N

celkový základ daně s první sníženou sazbou DPH

dan2

integer

N

celková DPH s první sníženou sazbou

zakl_dan3

integer

N

celkový základ daně s druhou sníženou sazbou DPH

dan3

integer

N

celková DPH s druhou sníženou sazbou

cest_sluz

integer

N

celková částka v režimu DPH pro cestovní službu

pouzit_zboz1

integer

N

celková částka v režimu DPH pro prodej použitého zboží se základní sazbou

pouzit_zboz2

integer

N

celková částka v režimu DPH pro prodej použitého zboží s první sníženou sazbou

pouzit_zboz3

integer

N

celková částka v režimu DPH pro prodej použitého zboží s druhou sníženou

urceno_cerp_zuct

integer

N

celková částka plateb určená k následnému čerpání nebo zúčtování

cerp_zuct

integer

N

celková částka plateb, které jsou následným čerpáním nebo zúčtováním

datum_trzby

string

A

datum tržby ve formátu YYYY-MM-DD HH24:MI:SS

ic_poplatnika

string

N

IČ poplatníka

dic_poplatnika

string

A

DIČ poplatníka

id_provozovny

string

A

označení provozovny

id_pokladny

string

A

označení pokladního zařízení

adresa_poplatnika

string

N

adresa poplatníka

rezim_trzby

string

A

režim, ve kterém byla tržba uskutečněna

Příklad struktury EET:

{
"fik": "b3a09b52-7c87-4014-a496-4c7a53cf9125-03",
"bkp": "03ec1d0e-6d9f77fb-1d798ccb-f4739666-a4069bc3",
"pkp": "Ca8sTbURReQjjgcy/znXBKjPOnZof3AxWK5WySpyMrUXF0o7cz1BP6adQzktODKh2d8s
oAhn1R/S07lVDTa/6r9xTuI3NBH/+7YfYz/t92eb5Y6aNvLm6tXfOdE3C94EqmT0SEEz
9rInGXXP1whIKYX7K0HgVrxjdxCFkZF8Lt12XbahhAzJ47LcPxuBZZp6U6wJ2sWI5os3
KY9u/ZchzAUaCec7H56QwkMnu3U3Ftwi/YrxSzQZTmPTpFYKXnYanrFaLDJm+1/yg+VQ
ntoByBM+HeDXigBK+Shaxx+Nd0sSmm1Im4v685BRVdUId+4CobcnSQ3CBsjAhqmIrtWT
GQ==",
"poradove_cislo": "999",
"celk_trzba": "100000",
"zakl_nepodl_dph": "20000",
"zakl_dan1": "83500",
"dan1": "16500",
"zakl_dan2": "200000",
"dan2": "30000",
"zakl_dan3": "400000",
"dan3": "20000",
"cest_sluz": "50000",
"pouzit_zboz1": "10000",
"pouzit_zboz2": "20000",
"pouzit_zboz3": "30000",
"urceno_cerp_zuct": "60000",
"cerp_zuct": "70000",
"datum_trzby": "2017-03-01 15:00:00",
"dic_poplatnika": "CZ12345678",
"id_provozovny": "11",
"id_pokladny": "eshop",
"rezim_trzby": "běžný"
}

Get background payment status

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 payment status in the background, its implementation is still mandatory. URL metods: https://payments.comgate.cz/v1.0/status

Request parameters

parameter

type

required

description

merchant

string

Y

Merchant identifier

transId

string

Y

Alphanumerical unique identifier of transaction - transaction Id

secret

string

Y

Password for background communication

Response parameters

parameter

type

required

description

code

integer

Y

return code of method and error
description:
0 OK
1100 unknown error
1200 database error
1400 wrong request
1500 unexpected error
In the case of code = 0, the following parameters are in response:

message

string

Y

merchant

string

Y

Merchant identifier

test

boolean

Y

The „true“ means to create payment as testing, „false“ means create payment transaction as production one.

price

integer

Y

Product price in cents or pennies

curr

string

Y

Currency code - ISO 4217

label

string

Y

Short description of product displayed to Payer (1-16 characters)

refId

string

Y

Referral payment ID from Merchant’s system.

payerId

string

N

The Payer identifier from Merchant’s system.

method

string

N

Payment method used. It is one from the list of payment methods.

account

string

N

Identifier of Merchant’s bank account.

email

string

Y

Payer’s e-mail

phone

string

N

Payer’s mobile number

name

string

N

Product identifier – attribute is helpful for search in ComGate Payments – statistics of payments page

transId

string

Y

Alphanumerical unique identifier of transaction - transaction Id

secret

string

Y

Password for background communication

status

string

Y

Actual transaction state, values:
„PENDING“ – the payment is based, the final result is not known
„PAID“ – payment was successfully paid
„CANCELLED“ – payment was not finished correctly and was cancelled
„AUTHORIZED” – requested preauthorization was successful

fee

string

N

In case that Merchant has automatic charging enabled, this field will contain transaction fee, otherwise will contain value „unknown”

eetData

JSON

N

Structure with data after registration of payment in EET.

Example of getting payment status – HTTP request

POST /v1.0/status HTTP/1.1
Host: payments.comgate.cz
Content-Type: application/x-www-form-urlencoded; charset=utf-8

merchant=merchant_com&transId=XA52-3R2M-EB9C&secret=ZXhhbXBsZS5jb206QUJDeHl6

Example of getting payment status – HTTP response

HTTP/1.1 200 OK
Content-Type: application/x-www-form-urlencoded; charset=utf-8

code=0&message=OK&merchant=merchant_com&test=false&price=10000&curr=CZK&label=Beatles%20-%20Help!&refId=2010102600&method=CARD&email=info%40customer.com&phone=%2B420123456789&transId=AB12-EF34-IJ56&secret=ZXhhbXBsZS5jb206QUJDeHl6&status=PAID

Payment refund - only with permission

The refund method is intended for payments already made 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. URL metods: https://payments.comgate.cz/v1.0/refund
If the payment has not been completed and is in a pending state, it is possible to use the payment cancellation method.

Request parameters

parameter

type

requiered

description

merchant

string

Y

Merchant identifier

transId

string

Y

Alphanumerical unique identifier of transaction – transaction Id

secret

string

Y

Password for background communication

amount

string

Y

Refund amount - can be in full or partial amount of the transaction

curr

string

N

Currency of refund, if not present, “CZK” will be used

test

string

N

Value “true” means, that refund will be set as testing. Refund and payment will be checked as usual, but initial payment won’t be refunded. If empty or “false”, refund will be set as production. Testing payments can only be refunded with testing refunds.

refId string N

Parameter suitable for entering the refund identification number on the Merchant'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 in the 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 based payment will be displayed for the payment.

Response parameters
parameter type required description
code integer Y Return code of method and error description:
message string Y

0 OK
1100 unknow error
1200 database error
1400 wrong request
1401 refunded payment is not PAID
1500 unexpected error

Example of refund creation – HTTP request:

POST /v1.0/refund HTTP/1.1
Host: payments.comgate.cz
Content-Type: application/x-www-form-urlencoded; charset=utf-8

merchant=merchant_com&transId=XA52-3R2M-EB9C&secret=ZXhhbXBsZS5jb206QUJDeHl6amount=100

Example of refund creation – HTTP response:

HTTP/1.1 200 OK
Content-Type: application/x-www-form-urlencoded; charset=utf-8

code=0&message=OK

Payment cancellation

If the order in the online shop has been canceled and the transaction is not to be completed by the Payer, it is possible to use the cancellation payment. Unlike a refund, the payment must be in the PENDING state. URL metod: https://payments.comgate.cz/v1.0/cancel
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 parameters

parameter

type

required

description

merchant

string

Y

Merchant identifier

transId

string

Y

Alphanumerical unique identifier of transaction – transaction Id

secret

string

Y

Password for background communication

Response parameters

parameter

type

required

description

code

integer

Y

return code of method and error description:

message

string

Y

0 OK
1400 it is not possible to switch the payment to the cancel state (payment not found, the payment is not in the pending state, unauthorized access)

Example of payment cancellation – HTTP request:

POST /v1.0/cancel
Host: payments.comgate.cz
Content-Type: application/x-www-form-urlencoded; charset=utf-8

merchant=123456&transId=XA52-3R2M-EB9C&secret=ZXhhbXBsZS5jb206QUJDe12sg

Example of payment cancellation – HTTP response:

HTTP/1.1 200 OK
Content-Type: application/x-www-form-urlencoded; charset=utf-8

code=0&message=OK

Getting enabled payment methods

Method for merchant used for determining his current allowed options in ComGate Payments system. This can be used for getting the list of available methods. These methods can be used for payment creation afterwards. URL metod: https://payments.comgate.cz/v1.0/methods

Request parameters

parameter

type

required

description

merchant

string

Y

Merchant identifier

secret

string

Y

Password for background communication

type

string

N

Format of response (“xml” or “json”). If not present, “xml” will be used.

lang

string

N

Language of method description. Valid valies are “cs”, “en”, “pl”. If not present, “cs” will be used.

curr string N Filling in the parameter to the values CZK or EUR will return methods that support the specified currency.
country string N Country code ("CZ", "SK"), the parameter is used to limit the selection of payment methods for the specified country.

XML or JSON is present in response, according to parameter „type“. Both formats have same nesting level.

Response parameters

element

type

required

description

/methods/method/id

string

Y

available payment method id

/methods/method/name

string

Y

method name, in chosen language

/methods/method/description

string

Y

longer method description, in chosen language

/methods/method/logo

string

Y

HTTP link pointing to method logo image

In case of error, response has following format:

Response parameters

element

typ

povinný

popis

/error/code

string

Y

result code and error description:

/error/message

string

Y

0 OK
1100 unknown error
1200 db error
1300 merchant has no enabled method
1400 request error
1500 unexpected error

/error/extraMessage

string

N

longer error message

Example of getting enabled payment methods – HTTP request:

POST /v1.0/methods HTTP/1.1
Host: payments.comgate.cz
Content-Type: application/x-www-form-urlencoded; charset=utf-8

merchant=merchant_com&secret=ZXhhbXBsZS5jb206QUJDeHl6&type=xml&lang=cs

Example of getting enabled payment methods – HTTP response:

HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8

<?xml version="1.0" encoding="UTF-8"?>
<methods>
<method>
<id>BANK_CZ_AB</id>
<name>Air Bank</name>
<description>Bankovní převod pro majitele účtu u Air Bank.</description>
<logo>https://payments.comgate.cz/assets/images/logos/BANK_CZ_AB.png</logo>
</method>
<method>
<id>BANK_CZ_CTB</id>
<name>Citibank</name>
<description>Bankovní převod pro majitele účtu u Citibank.</description>
<logo>https://payments.comgate.cz/assets/images/logos/BANK_CZ_CTB.png</logo>
</method>
<method>
<id>BANK_CZ_CS_P</id>
<name>Česká spořitelna - PLATBA 24</name>
<description>On-line platba pro majitele účtu u České spořitelny.</description>
<logo>https://payments.comgate.cz/assets/images/logos/BANK_CZ_CS_P.png</logo>
</method>
<method>
<id>BANK_CZ_FB</id>
<name>Fio banka - PayMyway</name>
<description>On-line platba pro majitele účtu u Fio banky.</description>
<logo>https://payments.comgate.cz/assets/images/logos/BANK_CZ_FB.png</logo>
</method>
</methods>

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"methods": [
{
"id": "BANK_CZ_AB",
"name": "Air Bank",
"description": "Bankovní převod pro majitele účtu u Air Bank.",
"logo": "https://payments.comgate.cz/assets/images/logos/BANK_CZ_AB.png"
},
{
"id": "BANK_CZ_CTB",
"name": "Citibank",
"description": "Bankovní převod pro majitele účtu u Citibank.",
"logo": "https://payments.comgate.cz/assets/images/logos/BANK_CZ_CTB.png"
},
{
"id": "BANK_CZ_CS_P",
"name": "Česká spořitelna - PLATBA 24",
"description": "On-line platba pro majitele účtu u České spořitelny.",
"logo": "https://payments.comgate.cz/assets/images/logos/BANK_CZ_CS_P.png"
},
{
"id": "BANK_CZ_FB",
"name": "Fio banka - PayMyway",
"description": "On-line platba pro majitele účtu u Fio banky.",
"logo": "https://payments.comgate.cz/assets/images/logos/BANK_CZ_FB.png"
}
]
}

Example of getting enabled payment methods – HTTP response in case of error:

HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8

<?xml version="1.0" encoding="UTF-8"?>
<error>
<code>1400</code>
<message>Unauthorized access!</message>
</error>

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
"error": {
"code": 1400,
"message": "Unauthorized access!"
}
}

Recurring payments – creation of second and subsequent payments

Creation of recurring payments to ComGate Payments system is only possible when accepting card payments via provider Česká spořitelna or ČSOB and Clients, who have this functionality enabled. First (initial) payment is made the standard way (see Payment transaction creation). Process of setting second and subsequent payment runs completely on background, these payments are tied to initial through ComGate ID of initial payment. This ID must be in request parameter initRecurringId. Status of payment is shown to payer in client system as result of the process.

Request parameters

parametr

type

required

description

merchant

string

Y

Merchant identifier

country

string

N

Country code (“CZ”, “SK”, “PL”, “ALL”), default value is “CZ”

test

boolean

N

The „true“ means to create payment as testing, „false“ means create payment transaction as production one. If missing, payment transaction is set as production.

price

integer

Y

Product price in cents or pennies. Must be min. 10 CZK (including), 1 EUR, MIN. 10 PLN, 100 HUF, 1 USD, 1 GBP 
max. unlimited

curr

string

Y

Currency code – ISO 4217. Usually „CZK“

label string Y Short description of product displayed to Payer (1-16 characters)

refId

string

Y

Referral payment ID from Merchant’s system (uniqueness is not required, it’s possible to create more payment transactions with the same “refId”)

payerId

string

N

The Payer identifier from Merchant’s system. The identifier must be verified for example by Payer logging to the Merchant’s system using a password, otherwise leave the parameter blank. It is used when paying with ČS card, where ČS payment gateway stores the card numbers, so the next payment Payer need not reenter the card number. This feature must be enabled for a particular Merchant in the ČS system.

account string N Identifier of Merchant’s bank account to which ComGate Payments transfers the money. If the parameter is empty, the default Merchant’s account will be used. List of accounts is on https://data.comgate.cz/

email

string

Y

Payer’s e-mail (for reclamation purposes)

phone

string

N, Y/N

Payer’s mobile number (for reclamation purposes)

name

string

N

Product identifier – attribute is helpful for search in ComGate Payments – statistics of payments page

prepareOnly

boolean

Y

The parameter must be set to "true". Recurring payments cannot be created by redirection.

secret

string

Y

Password for background communication

initRecurringId

string

Y

ComGate ID of initial payment

eetReport

boolean

N

Indication of sending data to EET. If filled in, it overloads the EET settings in the store configuration in the client portal.

eetData

JSON

N

Structure with data for registration of payment to EET. Corresponds to parameters from the EET protocol specification. If the Merchant's website has set up sending sales to EET and the parameter is not filled in, the default settings from the configuration in the client portal will be used.

All parameters are urlencoded, as in case of HTTP request for Payment transaction creation. Response has parameter code, under which client determines what result he displays to payer. Code = 0 means success and payment was created, any other code indicates error and therefore payment was not created.

Response parameters

parameter

type

required

description

code

integer

Y

return code of method and error description:
0 OK
1100 Unknown error
1102 Requested language is not supported
1103 Unexpected count of specified methods
1104 Cannot find payment update
1200 DB error
1301 Unknown Merchant
1303 Interface URLs or language is missing
1304 Invalid category specified
1305 Product label is missing
1308 Specified payment option is not enabled for you
1309 Invalid payment amount
1310 Unknown currency of payment price
1311 Invalid bank account identifier
1316 Merchant does not have recurring payments enabled
1317 Invalid method – does not support recurring payments
1318 Initial payment was not found
1319 Unable to establish payment, problem on the part of the bank
1399 Unexpected result from DB method
1400 Request error
1500 Unexpected error

message

string

Y

transId

string

N

Alphanumerical unique identifier of transaction - transaction Id. Will be shown to Payer while making payment.

Example of Payment transaction creation on background – HTTP request

POST /v1.0/recurring HTTP/1.1
Host: payments.comgate.cz
Content-Type: application/x-www-form-urlencoded; charset=utf-8

merchant=merchant_com&price=10000&curr=CZK&label=Beatles%20-%20Help!&email= email%40platce.cz&refId=2010102600&prepareOnly=true&secret=ZXhhbXBsZS5jb206QUJDeHl6&initRecurringId=AB12-EF34-IJ56

Example of Payment transaction creation on background – HTTP response

HTTP/1.1 200 OK
Content-Type: application/x-www-form-urlencoded; charset=utf-8

code=0&message=OK&transId=AB34-EF56-XY78

Preauthorization submit

In case that Merchant created payment with requirement to preauthorize credit card payment (using the parameter preauth=true), calling this function will require the deduction of money that were blocked within the preauthorization. Calling can only be used for payments that were announced with AUTHORIZED state. URL metod: https://payments.comgate.cz/v1.0/capturePreauth

Request parameters

parameter

type

required

description

merchant

string

Y

Merchant identificator

transId

string

Y

Unique alphanumeric ID (code) of transaction (transactionId)

secret

string

Y

Password for background communication

Response parameters

parameter

type

required

description

code

integer

Y

Return code of method and error description:

message

string

Y

0 OK
1100 Unknown error
1104 Cannot retrieve payment
1200 Database error
1301 Unknown Merchant
1303 Missing links or language
1399 Unexpected result from the database
1400 Wrong request
1500 Unexpected error

Example of preauthorization submit – HTTP request:

POST /v1.0/capturePreauth HTTP/1.1
Host: payments.comgate.cz
Content-Type: application/x-www-form-urlencoded; charset=utf-8

merchant=merchant_com&transId=XA52-3R2M-EB9C&secret=ZXhhbXBsZS5jb206QUJDeHl6

Example of preauthorization submit – HTTP response:

HTTP/1.1 200 OK
Content-Type: application/x-www-form-urlencoded; charset=utf-8

code=0&message=OK

Preauthorization cancel

In case that Client created payment with requirement to preauthorize credit card payment (using the parameter preauth=true), by calling this function says he will not encash the money that were blocked within the preauthorization and thus can be released. Calling can only be used for payments that were announced with AUTHORIZED state. URL metod: https://payments.comgate.cz/v1.0/cancelPreauth

Request parameters

parameter

type

required

description

merchant

string

Y

Merchant identificator

transId

string

Y

Unique alphanumeric ID (code) of transaction (transactionId)

secret

string

Y

Password for background communication

Response parameters

parameter

type

required

description

code

integer

Y

Return code of method and error description:

message

string

Y

0 OK
1100 Unknown error
1104 Cannot retrieve payment
1200 Database error
1301 Unknown Merchant
1303 Missing links or language
1399 Unexpected result from the database
1400 Wrong request
1500 Unexpected error

Example of preauthorization cancel – HTTP request:

POST /v1.0/cancelPreauth HTTP/1.1
Host: payments.comgate.cz
Content-Type: application/x-www-form-urlencoded; charset=utf-8

merchant=merchant_com&transId=XA52-3R2M-EB9C&secret=ZXhhbXBsZS5jb206QUJDeHl6

Example of preauthorization cancel – HTTP response:

HTTP/1.1 200 OK
Content-Type: application/x-www-form-urlencoded; charset=utf-8

code=0&message=OK

Code lists

Payment transaction states

state

description

PENDING

Payment transaction was created, final result of payment is not yet known.

PAID

Payer successfully realized payment – it is possible to provide goods, service.

CANCELLED

Payment was not realized, goods is not delivered, service is not provided. At exceptional cases it is possible for this state to change to PAID state.

AUTHORIZED

The pre-authorization of the payment was successful (the money on the Payer's card was blocked). We are waiting for another request to be confirmed or canceled.

Payment methods

type

description

identifier

The Payer chooses the payment method in the signpost.

ALL

Credit or debit card

Provider automatically (recomended)

CARD_ALL (or CARD)

Bank transfer

The Payer's bank is selected in the ComGate Payments signpost.

BANK_ALL

ePayment for Air Bank

BANK_CZ_AB

ePayment for ČSOB clients

BANK_CZ_CSOB

ePayment for Equa Bank

BANK_CZ_EB

ePayment for clients of other banks

BANK_CZ_OTHER

ePayment+ for RaiffeisenBank clients

BANK_CZ_RB

ePayment+ for clients of Komerční Banka

BANK_CZ_KB

ePayment+ for GE Money Bank clients

BANK_CZ_GE

ePayment+ for Sberbank CZ clients

BANK_CZ_VB

ePayment+ for clients of FIO Banka

BANK_CZ_FB

ePayment+ for clients of Česká spořitelna

BANK_CZ_CS_P

ePayment+ for mBank clients

BANK_CZ_MB_P

ePayment+ for ČSOB clients

BANK_CZ_CSOB_P

ePayment+ for clients of era

BANK_CZ_PS_P

ePayment+ for UniCredit Bank clients

BANK_CZ_UC

ePayment+ for clients of Slovenská spořiteľňa

BANK_SK_SP

ePayment+ for clients of VÚB Bank

BANK_SK_VUB

ePayment+ for clients of Tatra Bank

BANK_SK_TB

ePayment+ for clients of ČSOB

BANK_SK_CSOB

ePayment+ for clients of Poštová Banka

BANK_SK_PB

ePayment for Prima Bank

BANK_SK_DEXIA

ePayment for Fio Bank

BANK_SK_FB

ePayment for clients of other banks BANK_SK_OTHER
ePayment for Alior Bank BANK_PL_ALR
ePayment for BGŻ BNP Paribas Polska BANK_PL_BGZ
ePayment for Blik BANK_PL_BL
ePayment for Bank Millennium BANK_PL_BM
ePayment for Bank Ochrony Środowiska BANK_PL_BOS
ePayment for Bank Pocztowy BANK_PL_BP
ePayment for BPS BANK_PL_BPS
ePayment for Banki Spółdzielcze BANK_PL_BSP
ePayment for BZ WBK BANK_PL_BZ
ePayment for Credit Agricole BANK_PL_CA
ePayment for Citi Handlowy BANK_PL_CH
ePayment for Deutsche Bank BANK_PL_DB
ePayment for Eurobank BANK_PL_EB
ePayment for GetIn Online BANK_PL_GO
ePayment for Idea Bank BANK_PL_IDB
ePayment for ING Bank Śląski BANK_PL_ING
ePayment for Inteligo BANK_PL_INT
ePayment for mBank BANK_PL_MB
ePayment for Nest Bank BANK_PL_NEB
ePayment for Noble Bank BANK_PL_NOB
ePayment for Plus Bank BANK_PL_PB
ePayment for Bank Pekao BANK_PL_PEK
ePayment for PKO BP BANK_PL_PKO
ePayment for Raiffeisen Polbank BANK_PL_RB
ePayment for T-Mobile Usługi Bankowe BANK_PL_TM
ePayment for Toyota Bank BANK_PL_TOB
ePayment for Volkswagen Bank

BANK_PL_VWB

File Download API protocol

List of transfers of the day

The transferList method is used to obtain information about which transfers were made within a given day.
URL metod: https://payments.comgate.cz/v1.0/transferList

Request parameters
parameter type required description
merchant string Y Merchant identifier
secret string Y

Password for background communication

date string Y The method returns transfers in one day
Example of a list of transfers of a day - HTTP request

POST /v1.0/transferList HTTP/1.1
Host: payments.comgate.cz
Content-Type: application/x-www-form-urlencoded; charset=utf-8

merchant=135258&secret=wi9VplRz0UNqoxFqSM4udyxyA1ia5z32&date=2019-07-25

Example of a list of transfers of a day - HTTP response

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

[{"transferId":5211530,"transferDate":"2019-07-25","accountCounterparty":"0\/0000","accountOutgoing":"281481882\/0300","variableSymbol":"86616655"}]

Details for a specific bank transfer

The singleTransfer method displays detailed information for a specific bank transfer. The mandatory transferId parameter is obtained by the trader using the transferList method.
URL metod: https://payments.comgate.cz/v1.0/singleTransfer

Request parameters
parameter type required description
merchant string Y Merchant identifier
secret string Y

Password for background communication

transferId string Y

Details for a specific bank transfer

Example of details for a specific bank transfer - HTTP request

POST /v1.0/singleTransfer HTTP/1.1
Host: payments.comgate.cz
Content-Type: application/x-www-form-urlencoded; charset=utf-8

merchant=135258&secret=wi9VplRz0UNqoxFqSM4udyxyA1ia5z32&transferId=5211530

Example of details for a specific bank transfer – HTTP response
1 = payment
2 = refund
3 = monthly fee
4 = other fees, chargebacks and movements
5 = summary line

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
[

   {
       "typ": 1,
       "Merchant": "135261",
       "Datum založení": "2019-07-23 11:40:20",
       "Datum zaplacení": "2019-07-23 11:42:02",
       "Datum převodu": "2019-07-25",
       "Měsíc fakturace": null,
       "ID ComGate": "QWDZ-AGRU-1F6L",
       "Metoda": "Platba kartou",
       "Produkt": null,
       "Popis": "ComGate s.r.o.",
       "E-mail plátce": "info@comgate.cz",
       "Variabilní symbol platby": "86230990",
       "Variabilní symbol převodu": "86616655",
       "ID od klienta": "5331940",
       "Měna": "HUF",
       "Potvrzená částka": "12480,00",
       "Převedená částka": "12356,45",
       "Poplatek celkem": "123,55",
       "Poplatek mezibankovní": "24,96",
       "Poplatek asociace": "33,70",
       "Poplatek zpracovatel": "64,89"

   },

   {
       "typ": 5,
       "Merchant": "-",
       "Datum založení": null,
       "Datum zaplacení": null,
       "Datum převodu": "2019-07-25",
       "Měsíc fakturace": null,
       "ID ComGate": null,
       "Metoda": null,
       "Produkt": "suma",
       "Popis": "-",
       "E-mail plátce": "-",
       "Variabilní symbol platby": "-",
       "Variabilní symbol převodu": "86616655",
       "ID od klienta": "-",
       "Měna": "HUF",
       "Potvrzená částka": "54910,00",
       "Převedená částka": "54366,40",
       "Poplatek celkem": "543,60",
       "Poplatek mezibankovní": "109,82",
       "Poplatek asociace": "148,27",
       "Poplatek zpracovatel": "285,51"

   }

]

CSV file for a specific bank transfer

Thanks to the csvSingleTransfer method, you can download a daily statement in CSV format.
URL metody: https://payments.comgate.cz/v1.0/csvSingleTransfer

Request parameters
parameter type required description
merchant string Y Merchant identifier
secret string Y

Password for background communication

transferId string Y

Details for a specific bank transfer

download string N If it is not filled in or is "false", it returns data: the name of the file and its contents. If true, it returns a CSV file directly.
 
Example of downloading a statement in csv format for a specific bank transfer – HTTP request

POST /v1.0/csvSingleTransfer HTTP/1.1
Host: payments.comgate.cz
Content-Type: application/x-www-form-urlencoded; charset=utf-8

merchant=135258&secret=wi9VplRz0UNqoxFqSM4udyxyA1ia5z32&transferId=5211530&download=false

Example of downloading a statement in csv format for a specific bank transfer – HTTP response

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
"nazev": "vypis-2019-07-25.csv",
"csv": base64 encoded csv
}

ABO statement for a specific bank transfer

Thanks to the aboSingleTransfer method, you can download a daily statement in ABO format.
URL metod: https://payments.comgate.cz/v1.0/aboSingleTransfer

Request parameters
parameter type required description
merchant string Y Merchant identifier
secret string Y

Password for background communication

transferId string Y

Details for a specific bank transfer

download string N If it is not filled in or is "false", it returns data: the name of the file and its contents. If true, it returns a ABO file directly.

Example of downloading a statement in ABO format for a specific bank transfer – HTTP request

POST /v1.0/aboSingleTransfer HTTP/1.1
Host: payments.comgate.cz
Content-Type: application/x-www-form-urlencoded; charset=utf-8

merchant=135258&secret=wi9VplRz0UNqoxFqSM4udyxyA1ia5z32&transferId=5211530&download=true

Example of downloading a statement in ABO format for a specific bank transfer  – HTTP response

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
"nazev": "vypis-2019-07-25.gpc",
"abo": base64 encoded abo/gpc file
}

Download CSV files for in-day transfers

Direct download of CSV files for a specific day by using the csvDowload method. The downloaded ZIP file will contain one or more CSV files if there are multiple conversions within a day. It can be used, for example, for calls using wget.
URL metod: https://payments.comgate.cz/v1.0/csvDownload

Request parameters
parameter type required description
merchant string Y Merchant identifier
secret string Y

Password for background communication

date string Y

Required for one day only

Example of downloading csv for in-day transfers – HTTP request

POST /v1.0/csvDownload HTTP/1.1
Host: payments.comgate.cz
Content-Type: application/x-www-form-urlencoded; charset=utf-8

merchant=135258&secret=wi9VplRz0UNqoxFqSM4udyxyA1ia5z32&date=2019-07-25

Example of downloading csv for in-day transfers – HTTP response

HTTP/1.1 200 OK
Content-Type: application/zip
Content-Disposition: attachment; filename="vypis-csv-2019-07-25.zip"
Content-Length: delka souboru

ZIP soubor obsahující CSV k převodům za den v parametru ke stažení jako response

Download ABO files for in-day transfers

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.
URL metod: https://payments.comgate.cz/v1.0/aboDownload

Request parameters
parameter type required description
merchant string Y Merchant identifier
secret string Y

Password for background communication

date string Y

Required for one day only

Example of downloading ABO for transfers within a day – HTTP request

POST /v1.0/aboDownload HTTP/1.1
Host: payments.comgate.cz
Content-Type: application/x-www-form-urlencoded; charset=utf-8

merchant=135258&secret=wi9VplRz0UNqoxFqSM4udyxyA1ia5z32&date=2019-07-25

Example of downloading ABO for transfers within a day – HTTP response

HTTP/1.1 200 OK
Content-Type: application/zip
Content-Disposition: attachment; filename="vypis-csv-2019-07-25.zip"
Content-Length: delka souboru

ZIP soubor obsahující ABO k převodům za den v parametru ke stažení jako response

Přehled starých verzí protokolu je zde.