API Protocol
API Protocol
Article Summary
Share feedback
Thanks for sharing your feedback!
API Documentation
Comprehensive API documentation can be found at this link. It is used for custom implementation of e-shop connection to API. It contains sample CURL, PHP, JAVA and Python requests.
PHP Software development kit (SDK)
To easily implement the payment gateway, you can use this PHP SDK (install with composer).
Frequently asked questions
Where can I find my API login credentials?
You can find the login details in the client portal under "Integration" > "Store Settings" and then "Store Connection".
What is a login and what is an API password?
The login is the store link identifier (in most cases a six-digit number) and the password belongs to this identifier. Both of these are listed in the client portal under "Integration" > "Store Settings" > "Store Linking".
What is background setup vs. setup by redirection and why is background setup better?
Background setup is used to set up a secure and guaranteed payment with parameters that correspond to the e-commerce order. So the payer cannot influence e.g. the price, he has to pay it in full. In contrast, setting up by redirection is used e.g. for donations, where the payer can change the payment price at will. In the vast majority of cases, we therefore recommend setting up the payment in the background (calls from the e-shop to the Comgate API).
Why is it not a good idea to start the implementation in SOAP?
We support SOAP for historical reasons and it is no longer evolving, so it is not a good idea to start an implementation in SOAP.
How to set up IP whitelist?
The Comgate API is protected by an IP whitelist. For each e-shop we keep a record of the IP addresses from which you can communicate with our API. You can add the allowed IP addresses in the client portal under "Integration" > "Store Settings" and then "Store Connection".
What should be set in PENDING, PAID and CANCELLED URL in the store link?
You need to fill in the URL if you are using HTTP POST protocol (not necessary with SOAP). The first three URLs are used to redirect the user, the last URL is used to pass the result in the background. Without a properly set URL, the e-shop may not know the result of the transaction. If you do not fill in the "pending URL", the "Return to e-shop" button will not be displayed on the payment gateway. The PENDING, PAID and CANCELLED URLs are the endpoints in the e-shop where we redirect the payer from the payment gateway if, for example, the payment is successful. The URL for forwarding the payment result is used to communicate our API with the e-shop (forwarding the payment result to the e-shop).
How to set the URL?
You need to fill in the URL if you are using the HTTP POST protocol (not necessary with SOAP). The first three URLs are used to redirect the user, the last URL is used to pass the result in the background. Without a properly set URL, the e-shop may not know the result of the transaction. If you do not fill in the "pending URL", the "Return to e-shop" button will not be displayed on the payment gateway.
How to set up the establishment by redirection?
Establishment by redirection must first be enabled in the store link in the client portal "Integration" > "Store Settings" > "Store Link". There is no need to fill in the IP whitelist and no need to send a password when setting up the request. This type of setting up is not preferred and is only for simple donation type applications.
Where can I find examples in PHP?
You can find PHP examples on the API documentation page.
What does test mean?
The test parameter of a payment determines whether it is a simulation of a payment or a real payment, e.g. by credit card. Typically it will be used before deployment to production to test the functionality of the payment gateway on a specific payment.
How to set up an email for sending errors?
In the client portal under "Integration" > "Contact details" it is advisable to set up an email for sending errors. You can separate multiple addresses with a semicolon. The developer will then receive errors (e.g. wrong combination of currency and payment method) from the API directly via email.
Where can I find a list of allowed methods in the API?
We recommend downloading the current methods whenever the payer generates a cart. You can retrieve them by making an API call - see this documentation.
How can an organization administrator set up login credentials for their developer?
An organization administrator can set up logins for their developer in the client portal under "Manage Users" and then "Add User".
Is email mandatory when creating a transaction? What instructions do payers receive via email?
We require an email to be completed for each payment. Either from the e-shop when setting up the payment or subsequently from the payer when viewing the payment gateway. To simplify the payment, we recommend the payer to fill in the email directly from the e-shop. We will send a link to the payer's email to view the status of their payment. At the same time, the payer can retry an earlier unsuccessful payment by promoting the sent link.
How can I check the payment status?
The only safe way to check the status of a payment is by calling an API method - see this documentation.
How do I access the test logs/test payments?
Test logs/test payments can be accessed if the user has the Tester privilege (you will need to log in again after setting new user privileges).
What happens if the background http code 200 is not acknowledged to accept the result?
If the background acceptance of the result is not acknowledged with http code 200, this will trigger a retransmission up to a maximum of 1000 attempts. If even after 1000 attempts (spread over time) the payment status could not be passed to the e-shop, we will generate an error email and send it to the e-shop.
How to proceed with repeated payments?
For recurring payments, the code 1500 is common for both non-payment and error. We recommend to retry the payment attempt a maximum of 5 times with a certain time interval (e.g. due to the daily limit on the account) and then create a new initiating payment. Repeated payments may not be made for various reasons - insufficient funds on the payer's card, over the payment limit, etc.
Who initiates a repeat payment for recurring payments?
For recurring payments, the e-shop always initiates the recurring payment. The first payment is the initiating payment, which the payer must pay. Subsequently, the recurring payment takes place without his participation.
How to proceed if the e-shop has multiple languages?
If an e-shop has multiple language mutations on multiple URLs (e.g. cz.eshop.com and sk.eshop.com), it can create multiple store links and define different return URLs there. Each e-shop mutation must be reported to the card associations. If all communication with the payment gateway takes place in one e-shop, only one notification to the card associations is needed. Multiple store links can also be used, for example, when migrating an e-shop to a new e-shop platform or creating a test version of an e-shop.
How to disable IP whitelist?
Some hosts use different IPs for outbound connections, plus they can rotate them randomly. Therefore, it is a good idea to contact the hosting administrator to provide all possible outbound IPs, which will then be entered into the IP whitelist. Hosting providers often publish lists of IP addresses on the web.
Why don't you support IPv6?
IPv6 cannot be specified. We use an IPv4 whitelist, which provides information on which IP address the e-shop can communicate with our API from.
Do you support Google Analytics?
We do not support Google Analytics. More information can be found in this article (CZ).
When to redirect to the e-shop URL for PAID status?
The redirection to the e-shop URL for PAID status takes place within one hour of payment creation. Once the payer accesses the payment gateway more than one hour after the payment is created, the gateway will no longer actively redirect the payer to the e-shop on its own. This is due to the fact that the payer often accesses the payment status from another device (e.g. phone) after a longer time delay. Therefore, the e-shop might no longer have a current session with the order.
In which parameter should the order number from the e-shop be stored?
Ideally, store the order number in the refId parameter so that CSV/ABO matching can be done in accounting.
Is it possible to implement a payment gateway in PHP 5?
This example of outdated PHP 5 implementation is also available for download. However, we recommend using the SDK (above) if possible.
Was this article helpful?