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.

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:

Example of creating a payment - HTTP response:

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

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

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

Example of passing the result of a payment in the background - HTTP response

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

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

CSS style

Javascript code

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

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

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:

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

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

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.

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

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

Example of creating a payment by redirection (sending a web form) - HTTP request

Example of creating a payment in the background - HTTP request

Example of creating a payment in the background - HTTP response

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:

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.

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

Response parameters

Example of pre-authorization confirmation - HTTP request:

Example of pre-authorization confirmation - HTTP response:

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

Example of cancel of pre-authorization - HTTP request:

Example of cancel of pre-authorization - HTTP request:

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

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

Example of creating a payment in the background - HTTP request

Example of creating a payment in the background - HTTP response

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

Response parameters

Example of creating a refund - HTTP request:

Example of refund establishment - HTTP response:

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

Response parameters

Example of payment cancellation - HTTP request:

Example of payment cancellation - HTTP request:

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

Response parameters

Example of passing the result of a payment in the background - HTTP request

Example of passing the result of a payment in the background - HTTP response

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

Parametry odpovědí

Example of obtaining payment status - HTTP request

Example of obtaining payment status - HTTP response

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

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

Response parameters

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

Response parameters

Example of obtaining allowed payment methods - HTTP request:

Example of obtaining allowed payment methods - HTTP response:

Example of obtaining allowed payment methods - HTTP response in case of error:

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

Example of obtaining a list of transfers within a day - HTTP request

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

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

Example of obtaining detail for a specific bank. transfer - HTTP request

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

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

Example of downloading a statement in csv format for a specific bank transfer - HTTP request

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

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

Example of downloading the ABO schedule for a specific bank transfer - HTTP request

Example of downloading the ABO schedule for a specific bank transfer - HTTP response

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

Example of downloading csv for transfers within a day - HTTP request

Example of downloading csv for transfers within a day - HTTP 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

Example of ABO download for intra-day transfers - HTTP request

Example of ABO download for intra-day transfers - HTTP response

Code lists

State of transactions

Payment methods