Comgate payment gateway API protocol

Introduction

Protocol Version: 1.0
Last update: 2017/04/25
All below stated information is considered the copyrighted work of ComGate Payments, a.s., and the business secret of ComGate Payments, a.s. Therefore, thank you for the discreet and correct treatment of the information stated in this document.

Technical contact ComGate Payments

Email: support@comgate.cz
GSM: +420 737 264 610

Glossary
payer End user who visits merchant’s web site, orders goods and/or service and pays for it
Merchant Merchant operates web site where Payers order goods and/or service
Service, Product ePlatba, ePlatba+, CreditCard payment, mPlatba, Premium SMS
Payment provider Mobile operator in case of web billing (mobile payment), bank in case of credit card
Payment method Web billing (mobile payment), credit card, bank payment
ComGate payments Payment solution integrating more payment methods for merchants

Document purpose

ComGate Payments system provides different payment methods to the Merchant. The document shows how to integrate merchant’s web site with ComGate Payments system. The intended audience is software developer.

Functionality

ComGate Payments provides payment solution for Merchants’ websites and business applications. Communication between Merchant and ComGate Payments is based on HTTPS protocol standard. While making payment, Payer is redirected from Merchant’s website to ComGate Payments. After making payment Merchant is (optionaly) informed about payment result and Payer is redirected back to Merchant’s site using standard HTTP redirect.

List of supported TLS ciphers is similar to this one: https://github.com/cloudflare/sslconfig/blob/master/conf

Payer view

The payment process from the Payer’s point of view

  1. Payer chooses goods or service on Merchant’s website
  2. Payer clicks “Pay” button on Merchant’s site
  3. Payer is redirected to ComGate Payments instruction page and fills in remaining required fields. If all required fields were provided by Merchant the ComGate Payments instruction page is skipped.
  4. ComGate Payments redirects Payer’s browser to Payment provider system according to chosen payment method and its parameters (e.g. credit card – bank, web billing – mobile operator etc.) ComGate Payments, a.s. – ComGate Payments HTTP-POST Protocol Specification Page 2 (total 22)
  5. Payer pays required amount using Payment provider’s interface and is redirected back to Merchant’s site. The redirect is made transparently through ComGate Payments system.
  6. If the payment was successful, the Merchant provides the goods/service to the Payer.

You can try ComGate Payments demo that is available at http://demo.comgate.cz

Merchant view

ComGate Payments offer two ways to choose payment methods:

  • a) Payer uses Merchant’s system to choose payment method – e-shop offers available methods
  • b) Payer uses ComGate Payments system to choose payment

Merchant can get payment result information from three sources

  • a) Payment transaction status received on background using communication protocol
  • b) Payment notification that is sent by e-mail
  • c) Using web application at https://portal.comgate.cz/

Payment creation – optional

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

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

Example of payment transaction creation on background – HTTP request:

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

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

Example of payment transaction creation on background – HTTP response:

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

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

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

Redirection to ComGate Payments webserver

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

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

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

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

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

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

3. Payment transaction status handover on background – optional

Implementing this part ensures automatic transmission of status of each payment transaction directly to your server at the moment the final status is known. If you are satisfied with e-mail notifications about payments and possibility to use ComGate Payments website interface to see information about payments, you can skip this step. Payment status is delivered to Merchant using HTTP request from ComGate Payments system directly to Merchant’s server. Identifiers and payment status are sent as POST parameters using HTTP protocol. This is background communication so it is naccessible to Payer which is unable to fraud it. Payer is redirected back to Merchant’s website while Payment transaction identifiers are sent as GET parameters of HTTP protocol. Any Goods or service providing must be based on the background payment status handover. It is not safe to rely on the Merchant’s website URL to which the Client is redirected because it is really easy to fraud.

Example of payment transaction status handover on background – HTTP request

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

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

Example of payment transaction status handover on background – HTTP response

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

code=0&message=OK

Communication between Merchant’s system and system ComGate Payments is secured using password and IP whitelist. Access has to be allowed from range of ComGate Payments IP addresses only. This range is defined as 62.77.114.16/28 and 89.185.236.55/32. It is strongly suggested to use HTTPS protocol that is safe to not reveal password even if communication is intercepted. Password is sent as HTTP POST parameter (not GET parameter) for not to be stored in communication logs of webservers. Merchant assures that the goods (service) provided in the scope of payment transaction (identified by unique transaction ID) is provided only once. Even in case of multiple background calls with the same transaction ID. It’s Merchant’s own responsibility to somehow register, using his system (database), that the goods (service) were already provided. Merchant is also responsible for providing right goods (service) only to Payer who made the payment. It means that Merchant registers linkage between transaction ID and Payer ID in his system (database) after authentication of Payer on Merchant’s website. Another way is storing any unique identifier in session (cookie) of Payer’s browser and pairing this identifier to right transaction ID.

4. Redirection of Payer to Merchant’s website

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

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

Payment states

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

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

Preauthorization

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

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

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

Recurring payments

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

This functionality is available on request for clients when accepting card payments via providers ČSOB pr Česká spořitelna. In case of recurring payments, it is necessary to establish initial payment at first. This payment is a standard payment with initRecurring parameter set to “true”. Subsequent recurring payments are established with new method and are bound to initial payment by ComGate ID.

This ID must be tied to a particular payer in client system!

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

Verification transactions

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

In terms of recurring payments, this transaction appears to be standard initial transaction; subsequent payments are bound to verification transaction.

Notice! Because of bank limitations, it is not possible to combine preauthorization and recurring payments.

Service Activation

Merchant is supposed to implement required functionality at his side (integrates communication with ComGate Payments system to his website). He gets needed access data for ComGate Payments system. He is supposed to tests his implementation using ComGate Payments testing interface and finally confirm to ComGate Payments a.s. that his system is ready. After successful Merchant’s system check his ComGate Payments system account is switched to production mode

Information provided from Merchant

During the integration process Merchant provides:

  • URL address of Merchant’s website (e-shop, service offer…)
  • Chosen variant for basic payment
  • Chosen variant for payment result handover
  • Phone number and E-Mail address of Merchant’s hotline
  • E-mail address for notifications about payments
  • Information (yes/no), if Merchant wants ComGate Payments system to send email notifications about payments to Payers
  • Merchant’s URL address for o redirection in case of successful payment (payment state PAID) o redirection in case of failure (payment state CANCELLED) o redirection in case of unknown result (payment state PENDING)
  • Note: all three URLs can contain string „${id}“, which is replaced by unique identifier (code) of payment in ComGate Payments and string „${refId}“, which is replaced by payment reference in Merchant’s system given at payment transaction creation. o handover of payment transaction result on background (if Merchant’s want to implement it). ComGate Payments, a.s. – ComGate Payments HTTP-POST Protocol Specification Page 7 (total 22)
  • Merchant’s IP addresses that will be used for making connections to ComGate Payments system to create payment transaction on background

Informations provided to Merchant

During the integration process merchant will be provided this data:

  • MerchantID – alphanumeric Merchant identifier
  • Password – used for HTTP communication on background
  • Password – used for access to listings of testing payments
  • List of currencies, categories and methods which are allowed for the merchant

Service URL

https://payments.comgate.cz/v1.0/create

List of supported TLS ciphers is similar to this one:

https://github.com/cloudflare/sslconfig/blob/master/conf

Testing

Testing of implementation is possible by setting parameter „test“ to value „true“ at payment creation. For testing Merchant’s system functionality Payer redirection to bank is switched of. Instead for this purpose we provide virtual provider (bank) where Payer only chooses to pay or not to pay.

List of testing payments, e-shop connection settings and communication logs are available here.

Access data is sent within welcome e-mail.
Merchant is responsible for thorough testing of his system.

Production

Production online statistics, payments listing, hotline is here (available while in production state, access data are sent within welcome e-mail.)

Even if in production it is still possible to utilize testing environment.
Testing and commercial payments are distinguished by parameter “test” at payment creation.

Protocol specification

Payment transaction creation

Payment transaction creation in ComGate Payments system. It is possible to choose payment method by your system or let the Payer to choose one later. It is possible to do it both ways for every single payment transaction. If the payment method or some other parameters are not set by your system, Payer can set such parameters himself. Payer can do it on payment instructions page of ComGate Payments system. If parameter initRecurring is set to true, initial recurring transaction is set. After that it is possible to create recurring payments that will be linked with this initial transaction’s ComGate ID. Response parameters do not change in this case. Creation of initial transaction is possible only for Clients, who have this service enabled and accept card payments via providers ČSOB or Česká spořitelna. Parameter “verification” is related with initial transactions. When set to “true”, verification transaction is established. Once the payment is paid, it will be automatically refunded. It is not necessary to manually refund this payment. Otherwise this verification payments works the same as standard initial payment.

Because of bank limitations, it is not possible to combine preauthorization and recurring payments.
Access is protected by IP addresses validation and integrity of the transmitted data is secured using https protocol.

Required:

  • N – optional parameter
  • Y – required parameter for HTTP request
  • (Y) – required parameter for HTTP request, only for certain payment methods
  • N, Y/N – parameter is optional for HTTP request but require in ComGate Payments which request it from Payer
Request parameters
parameter type required description
merchant string Y Merchant identifier
country sting N The „true“ means to create payment as testing, „false“ means create payment transaction as production one. If missing, payment transaction is set as production.
price integer Y

Product price in cents or pennies. Must be min. 10 CZK (including), max. unlimited, except Payment method MPAY_CZ, where is the limit for the provider:

  • O2: min. 10 CZK (including), max. 1500 CZK (including)
  • T-Mobile: min. 5 CZK (including), max. 1500 CZK (including)
  • Vodafone: min. 1 CZK (including), max. 1200 CZK (including)

For MPAY_PL payment method the list of acceptable price levels is clearly defined and cannot be entered amount of own choice. For more information, contact the ComGate Payments customer service

curr sting Y Currency code – ISO 4217. Usually „CZK“
label string Y Short description of product displayed to Payer (1-16 characters)
refild string Y Referral payment ID from Merchant’s system (uniqueness is not required, it’s possible to create more payment transactions with the same “refId”)
payerld string N The Payer identifier from Merchant’s system. The identifier must ComGate Payments, a.s. – ComGate Payments HTTP-POST Protocol Specification Page 9 (total 22) be verified for example by Payer logging to the Merchant’s system using a password, otherwise leave the parameter blank. It is used when paying with ČS card, where ČS payment gateway stores the card numbers, so the next payment Payer need not re-enter the card number. This feature must be enabled for a particular Merchant in the ČS system
vatPL string (Y) Identifier of VAT rate in Poland for the payment. Parameter is required only for “MPAY_PL” payment method.
cat string (Y) Identifier of payment category. Attribute must have value from list given on integration process. Usually „PHYSICAL“. Parameter is required only for “MPAY_CZ” and “SMS_CZ” payment methods.
method string Y Payment method, must be one from the list of payment methods, value „ALL“ in case it’s up to Payer to choose it or simple expression (example and description following)
account string N Identifier of Merchant’s bank account to which ComGate Payments transfers the money. If the parameter is empty, the default Merchant’s account will be used. List of accounts is on https://portal.comgate.cz/
email string Y Payer’s e-mail (for reclamation purposes)
phone string N, Y/N Payers mobile number (for reclamation purposes)
name string N Product identifier – attribute is helpful for search in ComGate Payments - statistics of payments page
lang string N Language code by (ISO 639-1). ComGate Payments interface will use this language for communication with Payer. Valid values from list (“cs” , “sk“, “en”, “pl”), default value is “cs“
prepareOnly boolean N Set it to „true“ for payment transaction creation on background. For payment creation by redirection or web form post set it to „false“ or not set it at all
secret string N For payment transaction creation on background set this attribute to password for background communication. For payment creation by redirection or web form post leave it empty or not set it at all.
preauth boolean N If you want to preauthorize card payment, set this parameter to “true”. In case of regular payment set to “false” or keep blank. Only for card payments.
initRecurring boolean N Parameter for creating initial transaction for recurring payments. Only for Clients, who have this service enable
embedded boolean N This parameter is used only in combination with method CARD_CZ_CSOB_2. Value “true” ensures that ČSOB payment gateway will be displayed in iframe. To view standard gateway, leave parameter blank or enter value “false”. This functionality is a special permit.

Response parameters
ComGate Payments server responds only in case of payment transaction creation on background. All parameters are urlencoded. It’s the same in case of HTTP request. If the payment transaction is created by redirection or web form post (parameter prepareOnly is “false”) ComGate Payments system redirects the Payer to appropriate URL or displays error message

parametr type required description
code integer Y

return code of method and error description: Result code and error description:
0 OK
1100 Unknown error
1101 Interface URL for pending transactions is missing
1102 Requested language is not supported 1103 Unexpected count of specified methods
1104 Cannot find payment update
1200 DB error
1301 Unknown merchant
1303 Interface URLs or language is missing 1304 Invalid category specified
1305 Product label is missing
1306 No valid method specified
1308 Specified payment option is not enabled for you
1309 Invalid payment amount
1310 Unknown currency of payment price 1311 Invalid bank account identifier
1316 Recurring payments are not enabled for Client
1317 Invalid method – does not support recurring payments
1319 Can’t settle payment, provider error 1399 Unexpected result from DB method 1400 Request error
1500 Unexpected error

message string Y
transld string N Alphanumerical unique identifier of transaction - transaction Id. Will be shown to Payer while making payment
redirect string N URL to redirect Payer to start payment
Example of Payment transaction creation by redirect (web form submit) – HTTP request

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

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

Example of Payment transaction creation on background - HTTP request:

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

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

Example of Payment transaction creation on background - HTTP response:

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

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

Self-selection of methods

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

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

Example:

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

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

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

Redirect URL could look like this example:

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

After redirecting to gateway, Payer would have already checked method CARD_CZ_CS, although he can still choose another method.

This function is useful only for payments created with methods BANK, BANK_ALL or with own methods selection.

ČSOB gateway iframe
ČSOB payment gateway enables optimalization for iframe. This functionality is useful if you don’t want to redirect Payer to payment gateway, but display it in your own system. This functionality is only available for method CARD_CZ_CSOB_2 and Client must apply for permit.

Recurring payments – creation of second and subsequent payments

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

Request parameters
parametr type required description
merchant string Y Merchant identifier
test boolean N The „true“ means to create payment as testing, „false“ means create payment transaction as production one. If missing, payment transaction is set as production.
country string N country code (“CZ”, “SK”, “PL”, “ALL”), default value is “CZ”
price integer Y Product price in cents or pennies. Must be min. 10 CZK (including), max. unlimited.
curr string Y Currency code – ISO 4217. Usually „CZK“
label string Y Short description of product displayed to Payer (1-16 characters)
refld string Y Referral payment ID from Merchant’s system (uniqueness is not required, it’s possible to create more payment transactions with the same “refId”)
payerld string N The Payer identifier from Merchant’s system. The identifier must be verified for example by Payer logging to the Merchant’s system using a password, otherwise leave the parameter blank. It is used when paying with ČS card, where ČS payment gateway stores the card numbers, so the next payment Payer need not reenter the card number. This feature must be enabled for a particular Merchant in the ČS system.
cat string (Y) Identifier of payment category. Attribute must have value from list given on integration process. Usually „PHYSICAL“. Parameter is required only for “MPAY_CZ” and “SMS_CZ” payment methods.
account string N Identifier of Merchant’s bank account to which ComGate Payments transfers the money. If the parameter is empty, the default Merchant’s account will be used. List of accounts is on https://data.comgate.cz/
email string Y Payer’s e-mail (for reclamation purposes)
phone string N, Y/N Payers mobile number (for reclamation purposes)
name string N Product identifier – attribute is helpful for search in ComGate Payments - statistics of payments page
prepareOnly boolean Y Set it to „true“ for payment transaction creation on background. For payment creation by redirection or web form post set it to „false“ or not set it at all.
secret string Y For payment transaction creation on background set this attribute to password for background communication..
initRecurringld string A ComGate ID of initial payment.

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

parametr type required description
code integer Y return code of method and error description: Result code and error description:
0 OK
1100 Unknown error
1102 Requested language is not supported 1103 Unexpected count of specified methods
1104 Cannot find payment update
1200 DB error
1301 Unknown merchant
1303 Interface URLs or language is missing 1304 Invalid category specified
1305 Product label is missing
1308 Specified payment option is not enabled for you
1309 Invalid payment amount
1310 Unknown currency of payment price 1311 Invalid bank account identifier
1316 Client does not have recurring payments enabled
1317 Invalid method – does not support recurring payments
1318 Initial payment was not found
1399 Unexpected result from DB method 1400 Request error
1500 Unexpected error
message string Y
transld string N Alphanumerical unique identifier of transaction - transaction Id. Will be shown to Payer while making payment.
Example of Payment transaction creation on background - HTTP request:

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

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

Example of Payment transaction creation on background - HTTP response:

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

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

Payment transaction handover on background

ComGate Payments system passes the final result of payment transaction using HTTP request to Merchant’s server. Parameters of the request describe the detail of finished payment.

Request parameters
parametr type required description
merchant string Y Merchant identifier
rest boolean Y The „true“ means payment was created as testing one, „false“ means payment was created as production one.
price integer Y Product price in cents or pennies
curr string Y Currency code - ISO 4217. Usually „CZK“
label string Y Short description of product displayed to Payer (1-16 characters)
refld string Y Referral payment ID from Merchant’s system.
payerld string N The Payer identifier from Merchant’s system.
vatPL string (Y) Identifier of VAT rate in Poland.
cat string (Y) Identifier of payment category.
method string N Payment method used. It is one from the list of payment methods.
account string N Identifier of Merchant’s bank account.
email string Y Payer’s e-mail
phone string N Payer’s mobile number
name string N Product identifier – attribute is helpful for search in ComGate Payments - statistics of payments page
transld string Y Alphanumerical unique identifier of transaction - transaction Id
secret string Y Password for background communication
status string Y Actual transaction state, values: „PAID“ – payment was successfully paid „CANCELLED“ – payment was not finished correctly and was cancelled „AUTHORIZED” – requested preauthorization was successful
fee string N In case that Client has automatic charging enabled, this field will contain transaction fee, otherwise will contain value „unknown”
Response parameters
parametr type required description
code integer Y return code of method and error
description:
In case of result was received successfully, our system expects the return code 0 and description „OK”
message string Y
Example of payment transaction status handover on background – HTTP request

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

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

Example of payment transaction status handover on background – HTTP response

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

code=0&message=OK

Preauthorization submit

In case that Client created payment with requirement to preauthorize credit card payment (using the parameter preauth=true), calling this function will require the deduction of money that were blocked within the preauthorization.

Calling can only be used for payments that were announced with AUTHORIZED state.

Request parameters
parameter type required description
merchant string Y Client identificator
transld string Y unique alphanumeric ID (code) of transaction (transactionId)
secret string Y password for background communication
Response parameters
parameter type required description
code integer Y

return code of method and error description:
0 OK
1100 unknown error
1104 cannot retrieve payment
1200 database error
1301 unknown Client
1303 missing links or language
1399 unexpected result from the database 1400 wrong request
1500 unexpected error

message string Y
Example of preauthorization submit – HTTP request:

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

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

Example of preauthorization submit – HTTP response:

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

code=0&message=OK

Preauthorization cancel

In case that Client created payment with requirement to preauthorize credit card payment (using the parameter preauth=true), by calling this function says he will not encash the money that were blocked within the preauthorization and thus can be released.

Calling can only be used for payments that were announced with AUTHORIZED state.

Request parameter
parameter type required description
merchant string Y Client identificator
transld string Y unique alphanumeric ID (code) of transaction (transactionId)
secret string Y

password for background communication

Response parameter
parameter type required description
code integer Y return code of method and error description:
0 OK
1100 unknown error
1104 cannot retrieve payment
1200 database error
1301 unknown Client
1303 missing links or language
1399 unexpected result from the database 1400 wrong request
1500 unexpected error
message string Y
Example of preauthorization cancel – HTTP request:

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

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

Example of preauthorization cancel – HTTP response:

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

code=0&message=OK

Payment refund

Method for refunding paid payments. It is possible to perform both partial (refund amount is less than amount of the payment) and full (refund amount is equal to amount of the payment) refund. That amount will be refunded back to payers account.

Request parameter
parameter type requred description
merchant string A client identificator
transld string A unique alphanumeric ID (code) of transaction (transactionId)
secret string A password for background communication
amount string A refund amount
curr string N currency of refund, if not present, “CZK” will be used
test string N Value “true” means, that refund will be set as testing. Refund and payment will be checked as usual, but initial payment won’t be refunded. If empty or “false”, refund will be set as production. Testing payments can only be refunded with testing refunds.
Response parameter
parameter type required desciption
code integer A return code of method and error description:
0 OK
1100 unknow error
1200 database error
1400 wrong request
1401 refunded payment is not PAID
1500 unexpected error
message string A
Example of refund creation – HTTP request:

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

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

Example of refund creation – HTTP response:

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

code=0&message=OK

Getting enabled payment methods

Method for merchant used for determining his current allowed options in ComGate Payments system. This can be used for getting the list of available methods. These methods can be used for payment creation afterwards.

Request parameter
parameter type required description
merchant string Y Client identificator
secret string Y password for background communication
type string N Format of response (“xml” or “json”). If not present, “xml” will be used.
lang string N Language of method description. Valid valies are “cs”, “en”, “pl”. If not present, “cs” will be used.

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

element type required description
/methods/method/id string A available payment method id
/methods/method/name string A method name, in chosen language
/methods/method/description string A longer method description, in chosen language
/methods/method/logo string A

HTTP link pointing to method logo image

In case of error, response has following format:

element type required description
/error/code string A result code and error description:
/error/message string A 0 OK
1100 unknown error
1200 db error
1300 merchant has no enabled method
1400 request error
1500 unexpected error
/error/extraMessage string N longer error message
Example of getting enabled payment methods – HTTP request:

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

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

Example of getting enabled payment methods – HTTP response:

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

<?xml version="1.0" encoding="UTF-8"?>
<methods>
<method>
<id>BANK_CZ_AB</id>
<name>airbank</name>
<description>Bank transfer using bank account of Air Bank. </description>
<logo>https://payments.comgate.cz/assets/iamges/logos/BANK CZ AB.png</logo>
</method>
<method>
<id>BANK_CZ_CTB</id>
<name>citibank</name>
<description>Bank transfer using bank account of citimank. </description>
<logo>https://payments.comgate.cz/assets/image/logos/BANK CZ CTB.png</logo>
</method>
<method>
<id>BANK_CZ_CS_P</id>
<name>Česká spořitelna - PLATBA 24<?name>
<description> On-line paymant using bank account of Fio banka.<?description>
<logo>https://payments.comgate.cz/assets/images/logos/BANK CZ FB.png</logo>
</method>
</methods>

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

{
"methods": [
{
"id": "BANK_CZ_AB",
"name": "Air Bank",
"description": " Bank transfer using bank account of Air Bank.",
"logo": "https://payments.comgate.cz/assets/images/logos/BANK_CZ_AB.png"
},
{
"id": "BANK_CZ_CTB",
"name": "Citibank",
"description": " Bank transfer using bank account of Citibank.",
"logo": "https://payments.comgate.cz/assets/images/logos/BANK_CZ_CTB.png"
},
{
"id": "BANK_CZ_CS_P",
"name": "Česká spořitelna - PLATBA 24",
"description": " On-line payment using bank account of Česká spořitelna.",
"logo": "https://payments.comgate.cz/assets/images/logos/BANK_CZ_CS_P.png"
},
{
"id": "BANK_CZ_FB",
"name": "Fio banka - PayMyway",
"description": "On-line payment using bank account of Fio banka.",
"logo": "https://payments.comgate.cz/assets/images/logos/BANK_CZ_FB.png"
}
]
}

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

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

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

HTTP/1.1 200
OK Content-Type: application/json; charset=utf-8
{
"error": {
"code": 1400,
"message": "Unauthorized access!"
}
}

VAT rates in Poland

VAT ratr Value from 2011 Description

NONE

0%

Product is exempt from paying VAT.

LOWER_1 5%

Super reduced VAT rate.

LOWER_2 8%

The reduced rate of VAT.

STANDARD 23% The stamdard rate of VAT

Categories of goods

Category Description
DIGITAL Digital content, online delivery
PHYSICAL

Physical goods, physical delivery

EROTIC Erotic goods

Payment transaction states

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

Payment methods

List of available payment methods is here.

Type Description Identifier
Credit or debit card Provider atuomatically (recomended)

CARD_ALL (or CARD)

PROVIDED ČSOB (via GPE) CARD_CZ_CSOB
Provider ČSOB (via ČSOB) CARD_CZ_CSOB_2
Provider Česká spořitelna CARD_CZ_CS
Provider Slovenská spořiteľňa CARD_SK_SLSP
Provider B+S Card Service CARD_CZ_BS
Bank transfer Bank is choosed by Payer (recomended) BANK_ALL
ePayment for RaiffeisenBank clients BANK_CZ_RB_2
ePayment for clients of Komerční Banka BANK_CZ_KB_2
ePayment for GE Money Bank clients BANK_CZ_GE_2
ePayment for Sberbank CZ clients BANK_CZ_VB_2
ePayment for clients of FIO Banka BANK_CZ_FB_2
ePayment for Air Bank BANK_CZ_AB
ePayment for Citybank clients BANK_CZ_CTB
ePayment for clients of Česká spořitelna BANK_CZ_CS
ePayment for ČSOB clients BANK_CZ_CSOB
ePayment for Equa Bank BANK_CZ_EB
ePayment for mBank clients BANK_CZ_MB
ePayment for clients of era BANK_CZ_PS
ePayment for UniCredit Bank clients BANK_CZ_UC_2
ePayment for Zuno Bank AG BANK_CZ_ZB
ePayment for clients of other banks BANK_CZ_OTHER
ePayment+ for RaiffeisenBank clients BANK_CZ_RB
ePayment+ for clients of Komerční Banka BANK_CZ_KB
ePayment+ for GE Money Bank clients BANK_CZ_GE
ePayment+ for Sberbank CZ clients BANK_CZ_VB
ePayment+ for clients of FIO Banka BANK_CZ_FB
ePayment+ for clients of Česká spořitelna BANK_CZ_CS_P
ePayment+ for mBank clients BANK_CZ_MB_P
ePayment+ for ČSOB clients BANK_CZ_CSOB_P
ePayment+ for clients of era BANK_CZ_PS_P
ePayment+ for UniCredit Bank clients BANK_CZ_UC
ePayment+ for clients of Slovenská spořiteľňa BANK_SK_SP
ePayment+ for clients of VÚB Bank BANK_SK_VUB
ePayment+ for clients of Tatra Bank BANK_SK_TB
ePayment+ for clients of ČSOB BANK_SK_CSOB
ePayment+ for clients of UniCredit Bank BANK_SK_UC
ePayment+ for clients of Poštovná Banka BANK_SK_PB
ePayment for Prima Bank BANK_SK_DEXIA
ePayment for Fio Bank BANK_SK_FB
ePayment for clients of other banks BANK_SK_OTHER