Skip to main content

Frequently Asked Questions (FAQ)

Where can I find API credentials?​

You can find your API credentials in the client portal under “Integration” > “Shop settings” > “Shop connection”.

What is the API login and what is the API password?​

The login is the shop connection identifier (in most cases a six-digit number), and the password belongs to this identifier. Both values are listed in the client portal under “Integration” > “Shop settings” > “Shop connection”.

What is background payment creation vs. redirect payment creation and why is background creation better?​

Background payment creation is used for secure and guaranteed payment creation with parameters that correspond exactly to the e-shop order. The payer cannot influence values such as the price and must pay the full amount. Redirect payment creation, on the other hand, is typically used for donations, where the payer can freely change the payment amount. In the vast majority of cases, we therefore recommend background payment creation (calling the Comgate API directly from the e-shop).

SOAP is supported only for historical reasons and is no longer being developed, so it is not recommended to start a new implementation using it.

How do I set up the IP whitelist?​

The Comgate API is protected using an IP whitelist. For each e-shop, we register IP addresses from which communication with our API is allowed. You can add allowed IP addresses in the client portal under “Integration” > “Shop settings” > “Shop connection”. Contact your hosting provider to obtain all outgoing IP addresses from which your servers may communicate. Hosting providers often publish lists of IP addresses on their websites. If your server uses a dynamic IP address, you can disable IP whitelist checking in the client portal. In this case, pay maximum attention to securing the communication password.

What should be set in the PENDING, PAID, and CANCELLED URLs in the shop connection?​

You must fill in the URLs if you are using HTTP POST or REST (not required for SOAP). The first three URLs are used for redirecting the user, while the last URL is used for background result delivery. Without properly configured URLs, the e-shop may not receive the transaction result. If you do not fill in the pending URL, the payment gateway will not display the “Return to e-shop” button. PENDING, PAID, and CANCELLED URLs are endpoints in the e-shop to which the payer is redirected from the payment gateway (e.g. after successful payment). The result delivery URL is used for communication between our API and the e-shop (passing the payment result to the e-shop).

How do I set the URLs?​

You must fill in the URLs if you are using HTTP POST or REST (not required for SOAP). The first three URLs are used for redirecting the user, while the last URL is used for background result delivery. Without properly configured URLs, the e-shop may not receive the transaction result. If you do not fill in the pending URL, the payment gateway will not display the “Return to e-shop” button.

How do I enable redirect payment creation?​

Redirect payment creation must first be enabled in the shop connection in the client portal under “Integration” > “Shop settings” > “Shop connection”. There is no need to configure an IP whitelist and no password needs to be sent when creating the request. This type of payment creation is not preferred and is intended only for simple applications such as donation payments.

Where can I find PHP examples?​

PHP examples can be found on the API documentation page.

What does the test parameter mean?​

The test parameter determines whether the payment is only a simulation or a real payment (e.g. by payment card). It is typically used before deployment to production to test the payment gateway functionality for a specific payment.

How do I set an email address for error notifications?​

In the client portal under “Integration” > “Contact details”, it is recommended to set an email address for receiving error notifications. Multiple addresses can be separated by semicolons. The developer will then receive API errors (e.g. invalid currency and payment method combinations) directly by email.

Where can I find the list of allowed payment methods in the API?​

We recommend downloading the available methods dynamically when generating the payer’s cart. They can be obtained via an API call – see this documentation.

How can an organization administrator create API credentials for a developer?​

An organization administrator can create credentials for a developer in the client portal under “User management” > “Add user”.

Is an email address required when creating a transaction? What instructions are sent to the payer by email?​

An email address is required for every payment—either provided by the e-shop when creating the payment or entered later by the payer on the payment gateway. To simplify the payment process, we recommend providing the email directly from the e-shop. The payer receives an email with a link to view the payment status and can also retry a previously unsuccessful payment using that link.

How can the payment status be verified?​

The only secure way to verify the payment status is by calling the appropriate API method – see this documentation.

How can I access test logs / test payments?​

Test logs and test payments are accessible if the user has the Tester role (after changing user permissions, re-login is required).

What happens if background result delivery is not confirmed with HTTP status code 200?​

If background result delivery is not confirmed with HTTP status code 200, retries will be triggered up to a maximum of 1000 attempts. If the payment status still cannot be delivered to the e-shop after 1000 attempts (spread over time), an error email will be generated and sent to the e-shop.

How should recurring payments be handled?​

For recurring payments, error code 1500 is used both for unpaid transactions and errors. We recommend retrying payment up to a maximum of 5 times with a time delay (e.g. due to daily account limits), and then creating a new initial payment. Recurring payments may fail for various reasons—insufficient funds, exceeded limits, etc.

Who initiates payment retries for recurring payments?​

For recurring payments, retries are always initiated by the e-shop. The first payment is the initial payment and must be completed by the payer. Subsequent recurring payments are processed without the payer’s involvement.

How should an e-shop with multiple language versions be handled?​

If an e-shop has multiple language versions on different URLs (e.g. cz.eshop.com and sk.eshop.com), it can create multiple shop connections with different return URLs. Each language version must be reported to card associations. If all communication with the payment gateway takes place within one e-shop, only one report to card associations is required. Multiple shop connections can also be used during e-shop migration or for creating a test version of the e-shop.

Why is IPv6 not supported?​

IPv6 cannot be used. We use an IPv4 whitelist that specifies which IP addresses are allowed to communicate with our API.

Do you support Google Analytics?​

Google Analytics is not supported. More information can be found in this article.

When does the redirect to the PAID URL occur?​

Redirection to the PAID URL occurs within one hour of payment creation. If the payer accesses the payment gateway more than one hour after payment creation, the gateway will no longer actively redirect the user back to the e-shop. This is because the payer often accesses the payment from a different device (e.g. a mobile phone) after a longer delay, and the original e-shop session may no longer exist.

Which parameter should store the e-shop order number?​

Ideally, store the order number in the refId parameter to enable CSV/ABO matching in accounting systems.

Is it possible to implement the payment gateway in PHP 5?​

A downloadable example of a legacy PHP 5 implementation is available. If possible, we recommend using the SDK instead (see above).