Protocol API - ENG

Protocol API - ENG


HTTP POST specification

The connection between the e-shop and the Comgate payment gateway is realized by redirecting the payer from the e-shop to the payment gateway. After the paymentis done, the payer is redirected back to the e-shop. At the same time, communication between the e-shop server and the payment gateway server (server - server) takes place in the background. A detailed description of the communication protocol available below on this page. Further related information describing payment process from the user's and e-shop point of view, initial settings in the client portal, 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

The step of creating a payment is optional, but it is advisable to implement it in case you require the certainty of a secure creation of a payment. It is possible to skip the implementation of this step if you do not need to identify individual payments in the system, but you only need information that someone has paid you a certain amount. This is suitable, for example, when implementing donations or recharging funds to the customer's virtual account, where you are only interested in who recharged and 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.

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 creating a payment - 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&method=ALL&prepareOnly=true&secret=ZXhhbXBsZS5jb206QUJDeHl6 

Example of creating a payment - 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 the Clients system and the payment gateway is secured by password and IP whitelist (access is allowed only from IP addresses of clients system). It is necessary to use secure HTTPS protocol, which prevents the disclosure of the password when eavesdropping on communications. The password is passed as a POST parameter (not a GET parameter) so it would not be stored in the web server communication log.

Redirect to the payment gateway

Eshop should call create paymentAfter creating a payment in the background, the e-shop will receive a payment URL for redirect to the payment gateway. The payment gateway can be displayed in two ways. The first way is to redirect the payer to the address received by the e-shop in the HTTP response. Redirection is usually done by sending an HTTP response 302:

HTTP answer 302

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

The second option is to display the payment gateway directly on the e-shop page using an iframe. For this variant, it is necessary to generate a payment URL in the standard way, but instead of redirecting the customer to the gateway,iframe will be displayed on the e-shop page with the payment URL.

If the first step of creating a background payment is omitted, the payment is established only after the Payer is redirected from the Client's website to the payment gateway server or by sending a web form from the Client's website to the payment gateway server. Payment parameters, including the unique payment reference number, are passed as GET or POST parameters of HTTP protocol.

Example of creating a payment by redirection (sending a web form) - 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&method=ALL 

Handing result of payment in the background

Implementation of this part will enable you automatically pass information about the status of every payment translation directly to your server at the moment when the status of the payment is known. Passing result of the payment on the background is mandatory.

The result of the payment is passed to the client by an HTTP request from the payment gateway server to the Client server. Identifiers and payment results are passed as POST parameters of the HTTP protocol. This communication runs at the background.

The payer is redirected to the Client's website and the payment identifiers are passed as GET parameters of the HTTP protocol. The sending of goods or services to the Payer must be bound to the transfer of the result of the payment in the background, not to the resulting redirection of the Payer to the Client's website, because the information provided by the redirection can Payer easily falsify

Example of passing the result of a payment in the 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 passing the result of a payment in the background - HTTP response

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

Communication between the Client's system and the payment gateway server is secured by a password and an IP whitelist. Access must be allowed only from the IP address of the payment gateway server. The ranges of IP addresses are defined in the Security section. It is mandatory to use the HTTPS protocol, which prevents the disclosure of the password in the case of  eavesdropping on communications. The password is passed as a POST parameter (not a GET parameter) so that it is not stored in the web server communication log. 

The e-shop, on its part, ensures that the goods (service) provided within the paid transaction (identified by a unique transaction ID) will be issued to the Payer only once (even if the result of the same payment is repeatedly passed to the Client's server).

Redirection of the Payer to the Client's website

Based on the payment status, the payer is redirected to one of the three URLs that the eshop chose when activated the service.. Payment identifiers are passed as GET parameters of the HTTP protocol. The client system must be able to handle two basic situations:

  • When redirecting the Payer to the Client's website, the result of the payment is not yet known. Payment is in PENDING state. This situation is completely normal and the e-shop must not present it to the Payer as an error. The system is waiting either for the payment to be credited to the bank account or for confirmation from the Payment Provider. The e-shop will find out the final result of the payment later either by submitting the result of the payment in the background, or by email, or in the client portal. 
  • If the payment gateway finds out the result of the payment immediately after the payment is made by the Payer, then the Payer is redirected to the respective URL (PAID or CANCELED). If the e-shop has implemented the transfer of the result of the payment in the background, then the redirection to the Client's website will take place after the successful transfer of the result of the payment in the background. The Client cannot send the goods or service to the Payer only based on the URL used for the redirect, as the Payer could fake the result of the payment by changing the URL in the web browser.

Example of redirecting the Payer to the Client's website - HTTP request

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

Payment gateway in the e-shop (iframe)

Payment gateway enables display optimized for iframe. This functionality is suitable if you do not want to redirect the payer to the payment gateway, but display it within your system. In order for the payment gateway to be displayed in the iframe, the embedded = true parameter must be used when creating the payment. The payment URL is generated in the standard way, but instead of redirecting the customer to the gateway, it will appear  iframe  with the payment URL on the-shop page. Getting a payment URL can be found here. There are two options for display. First, it is possible to display the payment gateway directly in the cart or using a pop-up window above your website. Implementing an iframe requires knowledge of web technologies. The iframe can only be used for card payment. For other payment methods, the payer will always be redirected to a new page.

To properly display the payment gateway in the iframe on the website, we recommend that you make the following modifications to your website.

Payment gateway display settings

HTML code

<div id="comgate-container">
    <iframe id='comgate-iframe' src ="[platební URL]" frameborder="0px"></iframe>
</div> 

CSS style

#comgate-container {
   display: none;
   position:absolute;
   z-index: 9999;
   left: 50%;
   top: 30px;
   overflow: auto;
   margin-left: -250px;
 }
 #comgate-iframe {
   width: 504px;
   height: 679px;
 }
 @media (max-height: 700px) {
   #comgate-iframe {;
     top: 0px;
   }
  } 

Javascript code

// funkce pro otevření iframu s bránou
function comgateOpen() {
    var comgate_container = document.getElementById("comgate-container");
    comgate_container.style.display = "block";
}
// funkce pro zavření iframu s bránou
function comgateClose() {
    var comgate_container = document.getElementById("comgate-container");
    comgate_container.style.display = "none";
}

To display the iframe, you need to call the comgateOpen () function. For example, by following a user action (clicking on a button, etc.). The comgateClose () function is then used to hide the ifram if necessary.

Example of calling the ifram display function by clicking on the "Pay" button:

HTML code

<button id="comgate-open" onclick="comgateOpen()">Zaplatit</button>

Redirection of customer after the payment is completed

After the payment is completed by the customer, it is redirected to the e-shop to the URL that you set in the client portal. We recommend that you make one of the following adjustments to ensure that the customer is redirected directly to the return URL so that it does not remain inside the iframe. 

The first option is to redirect the external page to the URL you specify. This will refresh the entire page.

Javascript code for the inner page

window.top.location = window.self.location

The second option is to send a message from the page inside the iframe to the outside page and process the action on the outside page.Therefore, the entire page don't have to be refreshed

Please note that the actual payment result must be obtained in the background in the standard way. For security reasons, it is not possible to rely on the result transmitted by the iframe message. How to get the background payment result is described here.

Javascript code for the inside page, which sends a message to the outside page with the payment ID and payment status, eg for a paid payment:

window.parent.postMessage('[id platby]|PAID, '*');

Javascript code for an external page that processes an incoming message from an iframe:

// odchycení zprávy poslané z iframu pomocí postMessage
    if (window.addEventListener ){
        window.addEventListener('message', function (e) {
            // přijde mi id a výsledek platby, oddělovač je “roura”
            let message = e.data.split('|', 2);
            let message_id =  message[0];
            let message_result =  message[1];
            let result = '';
            if (message_result === 'PAID') {
    // obsloužení stavu PAID
    [...]
            } else {
    // obsloužení dalších stavů, atd ...
    [...]
            }
        }, false);

Payment gateway in iframe from the payer's point of viewIframe

The Comgate payment gateway allows users to retry a payment if they have failed to complete a payment for the first time. The display of the payment gateway in the iframe to the user depends on the selected payment method and also whether the selection of payment methods is on the e-shop side or on the Comgate side. If the selection of payment methods is on the e-shop side and the payment is already established with the payment method, the card payment method must be selected to display the iframe. If the user was unable to complete the payment for the first time, only the card payment method is displayed again for the next attempt. This version is recommended.

If the e-shop does not create a payment with an already selected payment method, the user is shown a selection of payment methods in the iframe. Here it is then necessary to choose payment by card. If the user has not been able to complete the payment, he is again shown a selection of payment methods in the iframe for the next attempt.

If a method other than card payment is selected at any step of the payment process, the payer will be redirected to a new page. The user will not return to the iframe.

Statuses of payments

  • PENDING - The payment has been established, the final result of the payment is not yet known.
  • PAID - The payer has successfully completed the payment - it is possible to issue the goods, respectively. make the service available.
  • CANCELED - Payment has not been paid, the goods will not be issued, resp. the service will not be provided.

The payment can only be considered as paid in the PAID state. The PENDING state is not final and may be followed by a CANCELED state.

Stavy plateb

API protocol - Comgate payment gateway

Security

Communication between the Comgate payment system and the e-shop takes place in three ways.

  • As a client, the server part of the e-shop solution 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.
  • As a client, the server part of the payment gateway connects to the server part of the e-shop solution and calls the method for transmitting the payment result in the background.
  • The payer's (user's) browser is redirected from the e-shop to the payment gateway and then from the payment gateway back to the e-shop.

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 a password (secret) and IP whitelist. Settings of these parameters can be set in the client portal environment.

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.

Payment gateway methods

Payment buttons

We provide accelerated bank transfers (payment buttons) from all major banks in the Czech Republic, Poland and Slovakia. You can find a list of available banks in the code lists. In the case of payment buttons, it is possible to use functionalities such as refunds and cancellations.

The payment button cannot be displayed directly in the e-shop (iframe). The payer is always redirected to the bank.

Credit card payment

The payment gateway accepts payments by VISA, VISA Electron, Mastercard, Maestro. Payments are available in CZK, EUR, PLN, HUF, USD, GBP, RON, NOK and SEK. It is available in 12 languages - Czech, Slovak, English, German, French, Polish, Hungarian, Croatian, Slovenian, Romanian, Norwegian and Swedish.

Many functionalities can be used for card payments. These include refunds, cancellations of unfinished payments, repeting payments (for example, for subscriptions with a regular deduction from the payer's card) or pre-authorization. Payment by card can also be viewed directly in the e-shop (iframe).

Apple Pay

Apple Pay is part of the Comgate payment gateway. To view the service to the customer, all you need to do is enable the CARD_CZ_CSOB_2 card payment method.

Within the service, it is not possible to use the recurring payment functionality because of the Apple Pay security principle and so-called card tokenization. Other functionalities are available.

Display of the Apple Pay service

The display of the Apple Pay service depends on whether the selection of payment methods is in the e-shop basket or the e-shop uses the selection of methods from Comgate. Furthermore, it is necessary to distinguish whether the payer should be redirected to the card gateway or Apple Pay will be displayed directly in the e-shop cart environment. So we distinguish three options for displaying Apple Pay:

1. Apple Pay button in the card gateway

If the selection of payment methods is on the Comgate side, no adjustments are required to display the service. All you have to do is enable the CARD_CZ_CSOB_2 card payment method. After selecting the method by the payer, the payment takes place in a standard process with redirection to the payment gateway. The service is displayed automatically on the card gateway. Here, the payer is also allowed to enter the card number manually. If the payer reaches the gateway from a device or browser that does not allow Apple Pay, he will be able to make payment by credit card.

2. Apple Pay button in e-shop cart with payer redirection to card gateway

If the selection of payment methods is on the e-shop side, the payment is established as a regular payment (more in the creation of the payment), but the APPLEPAY_REDIRECT method must be called in the request. Subsequently, the payer will be redirected to the payment gateway using the obtained payment link. The Apple Pay button will then appear on the card gateway automatically. The payment process from the payer's point of view is then identical to the first option.

Recommendations for when to display Apple Pay in the e-shop cart

Apple Pay is only available to users who have a Safari web browser and their own Apple device that has a Touch ID or Face ID. These devices include the iPhone, iPad, Apple Watch, and Mac. For this reason, we recommend that the service be displayed in the order only to clients who can pay with Apple Pay. Instructions can be found directly on the Apple developer website.

Recommendations on how to display Apple Pay correctly

For the correct use of Apple Pay logs and names, see the Apple Pay Marketing Guide. To view the Apple Pay button, visit the Buttons and Marks website. We also recommend reading the guide to using the CSS styles available in Safari.

3. Apple Pay button included in the e-shop cart, without redirection to the card gateway

This section will be available soon.

Deferred payment

Deferred payment allows e-shop customers to defer payment of the purchase for up to several days. But the e-shop will receive its money in the standard time.

To display the method to the payer (e-shop customer), it is necessary to call the payment method LATER_ALL when creating a payment. If the selection of payment methods is on the Comgate site, the payer is shown all available methods of deferred payment. If the e-shop has a selection of payment methods in the basket, we recommend that you enter the following text as the method name for the payer: "Deferred payment". The text of the payment method label is "Buy now, pay later."

This method is only available for CZK and citizens of the Czech Republic.

Description of API methods

Creating a payment

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

Call parameters

Parametr

Type

Mandatry

Description

merchant

string

Yes

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

Yes

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

No

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, SL, SK, SV, 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

integer

Yes

Price for a product in cents or pennies 

Must be in minimum of 1 CZK; 0,1 EUR; 1 PLN; 100 HUF; 1 USD; 1 GBP; 5 RON; 0,5 NOK; 0,5 SEK. 

Maximum is not limited.

curr

string

Yes

Currency code according to ISO 4217. Available currencies: CZK, EUR, PLN, HUF, USD, GBP, RON, NOK, SEK.

label

string

Yes

Short description of the product (1-16 characters) - this item enable to filter payments in the Client Portal.

refId

string

Yes

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

string

Yes

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

No

Identifier of the Client's bank account to which Comgate Payments 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

string

Yes

Contact email on the Payer (for the purposes of a possible complaint)

phone

string

No

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

name

string

No

Product identifier - this item is located in the client's daily csv under the name Product.

lang

string

No

Language code (ISO 639-1) in which the Payer will be shown instructions for completing the payment, default allowed values ("cs", "sk", "en", "es", "it", "pl", "fr", "ro", "de" , "hu", "si", "hr"), if the parameter is missing, "cs" will be used, in case of request for another language, contact platby-podpora@comgate.cz.

prepareOnly

boolean

Yes

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

string

No

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

No

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

No

Parameter for creating an initial transaction for recurring payments. Only for Clients who have the service enabled.

verification

boolean

No

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

No

Parameter of sending data to EET. If filled in, it overloads the EET settings in the store configuration in the Client Portal.

eetData

JSON

No

Structure with data for registration of payment to EET. settings from the configuration in the Client Portal.

embeddedstringNoIf you use the standard redirection of the payer to the payment gateway, do not fill in the parameter or enter the value "false". The parameter is used only if you have implemented the display of the Comgate payment gateway in the iframe in your e-shop. A value of "true" ensures that the gateway is displayed correctly in the iframe. This can only be used for card payments. You can find more detailed information in the Payment Gateway section in the e-shop (iframe). 

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.

Response parameters

parametr

typ

mandatory

description

code

integer

Yes

Method return code and error description:
0 OK
1100 unknown error
1102 the specified language is not supported
1103 method incorrectly specified
1104 unable to load payment
1107 payment price is not supported
1200 database error
1301 unknown e-shop
1303 the link or language is missing
1304 invalid category
1305 product description is missing
1306 select the correct method
1308 the 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, a problem on the part of the bank
1399 unexpected result from database
1400 wrong query
1500 unexpected error

message

string

Yes

transId

string

No

Unique alphanumeric identifier (code) of the transaction, which will be displayed to the Payer at various stages of payment.

redirect

string

No

URL of the page where the Payer is to be redirected to make the payment.

Example of creating a payment by redirection (sending a web form) - 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&method=ALL 

Example of creating a payment in the 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&method=ALL&prepareOnly=true&secret=ZXhhbXBsZS5jb206QUJDeHl6 

Example of creating a payment in the 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%3DABCDEFGHI 

Choice of payment method

We recommend to display selection of payment methods to Payer during the purchase process and, based on his  choice, create the payment with the method parameter on one specific value (eg payment by card or payment by bank transfer, etc.). Then, the page of the specific payment provider (bank) will be displayed directly. 

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 e-shop has enabled.

Allowed method identifier delimiters are "+" for method addition and "-" for method subtraction from / to selection.

Example:

The payment gateway allows the Payer to have one specific payment method pre-selected when selecting a payment method in the Comgate gateway environment. In this case Payer only needs to be redirected to the payment gateway using the obtained payment link with the added parameter "method" with the selected method.

The payment link can therefore look like this:

https://payments.comgate.cz/client/instructions/index?id=ABCDEFGHIJ&method=CARD_CZ_CS

After getting at the payment gateway, the Payer will already have the CARD_CZ_CS method checked, but the selection of the method will remain on the Payer.

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


Proces předautorizace

Confirmation of pre-authorization

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

Call parameters

parametr

type

mandatory

description

merchant

string

Yes

e-shop identifier in the Comgate system

transId

string

Yes

unique alphanumeric identifier (code) of the transaction (transactionId)

secret

string

Yes

password for background communication

amountstringNothe amount of pre-authorization to be deducted from the card - it can be in full or partial amount of the transaction

Response parameters

parametr

typ

mandatory

description

code

integer

Yes


message

string

Yes

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

Example of pre-authorization confirmation - 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 pre-authorization confirmation - HTTP response:

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

code=0&message=OK 

Cancelation of  pre-authorization

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 the e-spop indicates that the money that was blocked during pre-authorization does not want to collect and the money can be released on the card again. Calls can only be used for payments for which AUTHORIZED status has been reported. Method URL: https://payments.comgate.cz/v1.0/cancelPreauth

Call parameters

parametr

typ

mandatory

description

merchant

string

Yes

e-shop identifier in the Comgate system

transId

string

Yes

unique alphanumeric identifier (code) of the transaction (transactionId)

secret

string

Yes

password for background communication

parametr

typ

mandatory

description

code

integer

Yes


message

string

Yes

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

Example of cancel of pre-authorization - 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 cancel of pre-authorization - HTTP request:

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


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

Call parameters

parametr

type

mandatory

description

merchant

string

Yes

e-shop identifier in the Comgate system

country

string

No

country code ("CZ", "SK", "PL", "ALL"), if the parameter is missing, "CZ" is used

test

boolean

No

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

integer

Yes

Price per product in cents or pennies. Must be min. 10 CZK (incl.), Max. Unlimited.

curr

string

Yes

Currency code according to ISO 4217, standard "CZK".

label

string

Yes

short product description (1-16 characters)

refId

string

Yes

Payment reference in the e-shop system (it does not have to be unique, ie it is possible to create more payments with the same refId).

account

string

No

The identifier of the e-shop bank account to which Comgate will transfer the money. If you do not fill in the parameter, the default e-shop account will be used. You can find a list of e-shop accounts at https://portal.comgate.cz/.

email

string

Yes

contact email at the Payer (for the purposes of a possible complaint)

phone

string

No

contact telephone number on the Payer (for the purposes of a possible complaint)

name

string

No

Product identifier - according to this item it is then possible to find your way in the payment statistics of the Comgate payment system.

prepareOnly

boolean

Yes

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

secret

string

Yes

password for background communication

initRecurringId

string

Yes

Comgate ID of the initial payment

eetReport

boolean

No

Parameter of sending data to EET. If filled in, it overloads the EET settings in the store configuration in the Client Portal.

eetData

JSON

No

Structure with data for registration of payment to EET. Corresponds to parameters from the EET protocol specification. If the e-shop is set to send 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 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, any other code means an error and therefore no payment was created.

Response parameters

parametr

type

mandatory

popis

code

integer

A

method return code and error description:
0 OK
1100 unknown error
1102 the specified language is not supported
1103 method incorrectly specified
1104 unable to load payment
1200 database error
1301 unknown e-shop
1303 the link or language is missing
1304 invalid category
1305 product description is missing
1308 the 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, a problem on the part of the bank
1399 unexpected result from database
1400 wrong query
1500 unexpected error

message

string

Yes

transId

string

No

a unique alphanumeric identifier (code) of the transaction that will be displayed to the Payer at various stages of the payment

Example of creating a payment in the 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 creating a payment in the 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 

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

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. Method URL: 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 storno method.

Call parameters

parametr

type

mandatory

description

merchant

string

Yes

e-shop identifier in the Comgate system

transId

string

Yes

unique alphanumeric identifier (code) of the transaction (transactionId)

secret

string

Yes

password for background communication

amount

string

Yes

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

curr

string

No

refund currency, if not filled in, "CZK" will be used

test

string

No

A value of "true" means that the refund will be cretaed as a test. Refunds and payments will be verified in the standard way, only the original payment will not be refunded.

If "false" is filled in or the parameter is empty, an official refund is created.

Test transactions can only be refunded by a test refund.

refIdstringNoparameter suitable for entering the refund identification number on the Client's side (it does not have to be unique, ie it is possible to create more refunds with the same refId); in the Client Portal 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 created payment will be displayed for the payment.

Response parameters

parametrtypemandatorydescription
codeintegerYes
messagestringYes

method return code and error description:
0 OK
1100 unknown error
1200 database error
1400 wrong query
1401 the refunded payment is in the CANCELED state
1402 refund amount higher than allowed
1500 unexpected error

Example of creating a refund - 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 establishment - HTTP response:

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

Storno of payment

If the order in the e-shop has been canceled 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. Method URL: 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.

Call parameters

parametr

type

mandatory

description

merchant

string

Yes

e-shop identifier in the Comgate system

transId

string

Yes

unique alphanumeric identifier (code) of the transaction (transactionId)

secret

string

Yes

password for background communication

Response parameters

element

type

mandatory

description

code

integer

Yes


message

string

Yes

method return code and error description:
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 request:

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

Transmission of the payment result in the background

The payment gateway passes the final status of the payment via HTTP request to the e-shop server. The parameters of this call specify the detail of the completed payment.

Method URL: https: // your-e-shop-address / absdefg - the method is called on the e-shop server

Call parameters

parametr

type

mandatory

description

merchant

string

Yes

e-shop identifier in the Comgate system

test

boolean

Yes

a value of "true" means that the payment was created as a test, a value of "false" means a production version.

price

integer

Yes

price for product in cents or pennies

curr

string

Yes

currency code according to ISO 4217

label

string

Yes

short product description (1-16 characters)

refId

string

Yes

payment reference (variable symbol, order number) in the e-shop system

payerId

string

No

payer identifier in the e-shop system

payerNamestringNohanding over the name of the account belonging to the Payer
payerAccstring
handing over the Payer's account number

method

string

No

the payment method used, from the table of payment methods

account

string

No

the identifier of the e-shop bank account to which Comgate Payments will transfer the money

email

string

Yes

contact email on the Payer

phone

string

No

contact phone on the Payer

name

string

No

product identifier - according to this item it is possible to search in the payment statistics of the Comgate payment system.

transId

string

Yes

unique alphanumeric identifier (code) of the transaction (transactionId)

secret

string

Yes

password for background communication

status

string

Yes

current transaction status, values

"PAID" - payment was successfully paid

"CANCELED" - the payment was not completed correctly and is canceled

"AUTHORIZED" - the requested pre-authorization was successful

fee

string

No

if the e-shop has set up automatic deduction of the payment fee, the transaction fee will be calculated in this field, otherwise the field will take the value "unknown"

eetData

JSON

No

structure with data after registration of the payment in EET

Response parameters

parametr

rype

mandatory

description

code

integer

Yes

Method return code and error description:

the system expects a return HTTP code 200 if the payment result has been received correctly.

Example of passing the result of a payment in the 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 passing the result of a payment in the background - HTTP response

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

Description of JSON structure with EET data (eetData):

parametr

type

mandatory

description

fik

string

No

fiscal identification code of the taxpayer

bkp

string

Yes

taxpayer's security code

pkp

string

No

taxpayer signature code encoded in base64

celk_trzba

integer

Yes

total amount of sales

poradove_cislo

integer

Yes

serial number of the receipt

zakl_nepodl_dph

integer

No

total amount of transactions exempt from VAT, other transactions

zakl_dan1

integer

No

the total tax base with the basic VAT rate

dan1

integer

No

total VAT with basic rate

zakl_dan2

integer

No

the total tax base with the first reduced VAT rate

dan2

integer

No

total VAT with the first reduced rate

zakl_dan3

integer

No

the total tax base with the second reduced VAT rate

dan3

integer

No

the total VAT with the second reduced rate

cest_sluz

integer

No

the total amount in the VAT scheme for the travel service

pouzit_zboz1

integer

No

the total amount in the VAT regime for the sale of second-hand goods at the basic rate

pouzit_zboz2

integer

No

the total amount under VAT for the sale of second-hand goods at the first reduced rate

pouzit_zboz3

integer

No

the total amount in the VAT regime for the sale of second-hand goods with the second reduced rate

urceno_cerp_zuct

integer

No

the total amount of payments to be subsequently drawn or settled

cerp_zuct

integer

No

the total amount of payments that are subsequent drawdowns or settlements

datum_trzby

string

Yes

sales date in the format YYYY-MM-DD HH24: MI: SS

ic_poplatnika

string

No

taxpayer's ID number

dic_poplatnika

string

Yes

VAT number of the taxpayer

id_provozovny

string

Yes

designation of shop

id_pokladny

string

Yescash register designation

adresa_poplatnika

string

No

taxpayer's address

rezim_trzby

string

Yes

the regime in which the sale took place

Example of EET structure:

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

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

Call parameters

parametr

type

mandatory

descriptiom

merchant

string

Yes

e-shop identifier in the Comgate system

transId

string

Yes

unique alphanumeric identifier (code) of the transaction (transactionId)

secret

string

Yes

password for background communication

Parametry odpovědí

parametr

typ

povinný

popis

code

integer

Yes

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 answer

message

string

Yes

merchant

string

Yes

e-shop identifier in the Comgate system

test

boolean

Yes

A value of "true" means that the payment was created as a test, a value of "false" means a production version.

price

integer

Yes

price for product in cents or pennies

curr

string

Yes

currency code according to ISO 4217

label

string

Yes

short product description (1-16 characters)

refId

string

Yes

payment references in the e-shop system

payerId

string

No

payer identifier in the e-shop system

method

string

No

the payment method used, from the table of payment methods

account

string

No

the identifier of the e-shop bank account to which Comgate Payments will transfer the money

email

string

Yes

contact email on the Payer

phone

string

No

contact phone on the Payer

name

string

No

product identifier - according to this item it is then possible to find your way in the payment statistics of the Comgate payment system

transId

string

Yes

unique alphanumeric identifier (code) of the transaction (transactionId)

secret

string

Yes

password for background communication

status

string

Yes

current transaction status, values

"PENDING" - the payment is created, the final result is not known

"PAID" - payment was successfully paid

"CANCELED" - the payment was not completed correctly and is canceled

"AUTHORIZED" - the requested pre-authorization was successfu

payerName

stringNohanding over the name of the account belonging to the Payer
payerAccstringNohanding over the Payer's account number

fee

string

No

if the e-shop has set up automatic deduction of the payment fee, the transaction fee will be calculated in this field, otherwise the field will take the value "unknown"

eetData

JSON

No

Structure with data after registration of payment in EET. Same structure as

Example of obtaining 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 obtaining 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 

Obtaining allowed methods

Method for obtaining the settings that the e-shop has enabled in the Comgate Payments Payment System. This method can be used to obtain a list of available payment methods for making payments. Method URL: https://payments.comgate.cz/v1.0/methods

Calling parameters

parametr

type

mandatory

description

merchant

string

Yes

e-shop identifier in the Comgate system

secret

string

Yes

password for background communication

type

string

No

Format of returned data ("xml" or "json"). If not filled in, "xml" will be used.

lang

string

No

Select the language in which the method descriptions will be. Allowed values are "cs", "en", "pl". If not filled in, "cs" will be used.

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

The response contains XML or JSON, depending on the selected parameter. Both formats have the same level of immersion.

Response parameters

element

type

mandatory

description

/methods/method/id

string

Yes

available payment method

/methods/method/name

string

Yes

the name of the method, in the selected language

/methods/method/description

string

Yes

longer description of the method, in the selected language

/methods/method/logo

string

Yes

HTTP link to method logo

In case of an error, the data has the following form.

Response parameters

element

type

mandatory

description

/error/code

string

Yes

method return code and error description

/error/message

string

Yes

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

/error/extraMessage

string

Yes

specification of the error message

Example of obtaining allowed 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 obtaining allowed payment methods - HTTP response:

HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8
<?xml version="1.0" encoding="UTF-8"?>
<methods>
<methods>
<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>
<methods>
<methods>

<id>BANK_CZ_FB_P</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>
<methods>
<methods>
HTTP/1.1 200 OK

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

"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 obtaining allowed 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!"
} 
} 

Sending sales to EET

The merchant must record every payment made by card or in cash in the EET system. Taxpayers must send the tax detail, non-VAT payers only the total amount. More information is included in the EET solution.

The merchant must first register with EET and download a certificate for secure communication. The merchant then configures the connection to the EET in the client portal interface.

If the EET is set up correctly in the client portal, then it is possible to proceed to the creation of the payment. There are two regimes for EET payments:

  1. The automatic (default) mode allows the merchant to send payments to EET without having to implement anything extra in the Comgate payment gateway communication protocol. This mode is used for non-VAT payers and VAT payers who sell goods at only one tax rate corresponding to the settings in the client portal. If the payment is made in a foreign currency, it will be registered in EET in CZK and the exchange rate of the given currency announced by the CNB from the previous day will be used as the conversion rate.
  2. The extended mode brings the need to modify the communication protocol of the Comgate payment gateway. The tmerchant will send the complete breakdown of the amount for EET in the eetData parameter to the log (see the example below, the parameter names are according to the EET specification). This regime is necessary for all those who sell goods at multiple VAT rates, travel services, sell and redeem vouchers or sell used goods. The data is transmitted in JSON format, the amounts are given in pennies.


Description of JSON structure with EET data (eetData):

parametr

type

mandatory

description

celk_trzba

integer

Yes

total amount of sales

zakl_nepodl_dph

integer

No

total amount of transactions exempt from VAT, other transactions

zakl_dan1

integer

No

the total tax base with the basic VAT rate

dan1

integer

No

total VAT with basic rate

zakl_dan2

integer

No

the total tax base with the first reduced VAT rate

dan2

integer

No

total VAT with the first reduced rate

zakl_dan3

integer

No

the total tax base with the second reduced VAT rate

dan3

integer

No

the total VAT with the second reduced rate

cest_sluz

integer

No

the total amount in the VAT scheme for the travel service

pouzit_zboz1

integer

No

the total amount in the VAT regime for the sale of second-hand goods at the basic rate

pouzit_zboz2

integer

No

the total amount under VAT for the sale of second-hand goods at the first reduced rate

pouzit_zboz3

integer

No

the total amount in the VAT regime for the sale of second-hand goods with the second reduced

urceno_cerp_zuct

integer

No

the total amount of payments to be subsequently drawn or settled

cerp_zuct

integer

No

the total amount of payments that are subsequent drawdowns or settlements

Example of EET structure:

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

Verification, verification payments

If the e-shop wants to use recurring payments in the future and wants to "register" the Payer now, it can use verification transactions. When the verification parameter is set to "true", a verification transaction is created. As soon as the Payer pays the payment, it will be automatically refunded, so it is not necessary to subsequently refund the payment manually. The authentication transaction than works the same as the initial transaction, ie it is possible to create recurring payments using its Comgate ID. Due to bank limitations, it is not possible to combine recurring payments and pre-authorizations.

API for downloading files

List of transfers within the day

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

Method URL: https://payments.comgate.cz/v1.0/transferList

Call parameters

parametrtypemandatorydescription
merchantstringYese-shop identifier in the Comgate system
secretstringYes

password for background communication

datestringYesthe method returns transfers in one day
testbooleanNoreturns a predefined sample transfer

Example of obtaining a list of transfers within 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-2 

Example of obtaining a list of transfers within 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"}] 

Detail of bank transfer

The singleTransfer method displays detailed information for a specific bank transfer.

The mandatory transferId parameter merchant  obtained by using ttransferList method. Method URL: https://payments.comgate.cz/v1.0/singleTransfer

Call parameters

parametrtypemandatorydescription
merchantstringYese-shop identifier in the Comgate system
secretstringYes

password for background communication

transferIdstringYes

details for a specific bank transfer

testbooleanNosuitable for testing - returns details to predefined sample transfers

Example of obtaining detail 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 obtaining detail for a specific bank. transfer - HTTP response

1 = payment

2 = refund

3 = monthly fee

4 = other fees, chargebacks and manual 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 to the selected transfer

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

Method URL: https://payments.comgate.cz/v1.0/csvSingleTransfer

Call parameters

parametrtypemandatorydescription
merchantstringYese-shop identifier in the Comgate system
secretstringYes

password for background communication

transferIdstringYes

details for a specific bank transfer

downloadstringNoIf not filled in or false, it returns data: file name and its contents; if true, it returns a CSV file directly.
testbooleanNoreturns a sample CSV file for testing purposes

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 for the selected transfer

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

Method URL: https://payments.comgate.cz/v1.0/aboSingleTransfer

Call parameters

parametrtypemandatorydescription
merchantstringYese-shop identifier in the Comgate system
secretstringYes

password for background communication

transferIdstringYes

details for a specific bank transfer

downloadstringNoIf not filled in or false, it returns data: file name and its contents; if true, it returns an ABO file directly.
typestringNothe "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".
testbooleanNoPro účely testování vrátí ukázkový ABO soubor. Returns a sample ABO file for testing purposes.

Example of downloading the ABO schedule 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&type=v1 

Example of downloading the ABO schedule 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
}
 

CSV for transfers during the day

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.

Method URL: https://payments.comgate.cz/v1.0/csvDownload

Call parameters

parametrtypemandatorydescription
merchantstringYese-shop identifier in the Comgate system
secretstringYes

password for background communication

datestringYes

mandatory for one day only

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

Example of downloading csv for transfers within a day - 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 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í CSV k převodům za den v parametru ke stažení jako response

ABO for  transfers within the day

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.

Method URL: https://payments.comgate.cz/v1.0/aboDownload

Call parameters

parametrtypemandatorydescription
merchantstringYese-shop identifier in the Comgate system
secretstringYes

password for background communication

datestringYes

mandatory for one day only

type stringNothe "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".
testbooleanNoFor testing purposes, the sample ABO returns a ZIP file.

Example of ABO download for intra-day transfers - 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&type=v2 

Example of ABO download for intra-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í ABO k převodům za den v parametru ke stažení jako response

Code lists

State of transactions

state

description

PENDING

The payment has been created, the final result of the payment is not yet known.

PAID

The payer successfully paid the payment - it is possible to issue the goods, respectively. make the service available.

CANCELLED

Payment has not been paid, the goods will not be issued, resp. the service will not be provided. In exceptional cases, this state may change to a 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

identificator


the Payer chooses the payment method in the signpost.

ALL

Credit card

provider automatically

CARD_ALL (nebo CARD)

Deferred payment
provider automticallyLATER_ALL
deferred payment from Equa bankLATER_PLATIMPAK
deferred payment from Skip Pay (formerly mallpay)
LATER_MALLPAY

Bank payments

the Payer select Bank in the Comgate Payments signpost

BANK_ALL

bank transfer Equa Bank

BANK_CZ_EB

bank transfer of other banks

BANK_CZ_OTHER

Raiffeisen Bank button

BANK_CZ_RB

Komerční Bank button

BANK_CZ_KB

FIO Bank button

BANK_CZ_FB

Česká spořitelna Bank button

BANK_CZ_CS_P

mBank Bank button

BANK_CZ_MB_P

ČSOB Bank button

BANK_CZ_CSOB_P

Era Bank button

BANK_CZ_PS_P

UniCredit Bank button

BANK_CZ_UC

Slovenská spořiteľňa Bank Button

BANK_SK_SP

VÚB Bank button

BANK_SK_VUB

Tatra Bank button

BANK_SK_TB

bank transfer of other banks
BANK_SK_OTHER
Alior Bank buttonBANK_PL_ALR
BGŻ BNP Paribas Polska Bank buttonBANK_PL_BGZ
Blik Bank buttonBANK_PL_BL
Bank Millennium Bank buttonBANK_PL_BM
Bank Ochrony Środowiska Bank buttonBANK_PL_BOS
Bank Pocztowy Bank buttonBANK_PL_BP
BPS Bank buttonBANK_PL_BPS
Banki Spółdzielcze Bank buttonBANK_PL_BSP
BZ WBK Bank buttonBANK_PL_BZ
Credit Agricole Bank buttonBANK_PL_CA
Citi Handlowy Bank buttonBANK_PL_CH
Deutsche Bank buttonBANK_PL_DB
Eurobank Bank buttonBANK_PL_EB
GetIn Online Bank buttonBANK_PL_GO
Idea Bank buttonBANK_PL_IDB
ING Bank Śląski Bank buttonBANK_PL_ING
Inteligo Bank button BANK_PL_INT
mBank Bank button BANK_PL_MB
Nest Bank buttonBANK_PL_NEB
Noble Bank buttonBANK_PL_NOB
Plus Bank buttonBANK_PL_PB
Bank Pekao Bank buttonBANK_PL_PEK
PKO BP Bank button BANK_PL_PKO
Raiffeisen Polbank Bank button BANK_PL_RB
T-Mobile Usługi Bankowe Bank button BANK_PL_TM
Toyota Bank buttonBANK_PL_TOB
Volkswagen Bank button

BANK_PL_VWB



Byl tento článek užitečný?