Payment methods and processing FAQ - csob/paymentgateway GitHub Wiki
Can we accept EUR payments?
Sure. Incoming payments will be settled to your EUR account, or converted to CZK. We will just need to know the way you prefer. Currencies and accounts are defined in the contract. If you need to make any changes to your account or service setup, please contact [email protected].
Which currencies are supported?
The payment gateway currently accepts payments in CZK, EUR, USD, GBP, HUF, PLN, RON, NOK and SEK. Currencies and accounts are defined in the contract. If you need to make any changes to your account or service setup, please contact [email protected].
How do you ensure security of online payments?
Communication between the customers and the gateway is secured using the standard https connection. The integration interface with merchants requires the use of encryption keys that sign the messages transmitted in both directions. The payment gateway is therefore sure that it communicates with the merchant (and not some middleman attacker) and the merchant can verify the authenticity of the bank's messages. The transactions itself support the state of the art 3D Secure technology developed by Visa and Mastercard to authenticate the cardholder.
What is 3D-Secure?
3D-Secure is authentication technology for card payments that complies with the PSD2 directive of the European Union.
It is a security technology developed by Visa and Mastercard. All sensitive cardholder data is processed outside the shop and (if supported by the issuer) the customer needs to authenticate the transaction (e.g. using a one-time code sent in a text message to the customer's phone). The technology is also known as Mastercard SecureCode and Verified by Visa.
How can we manage the transactions?
All transactions from the payment gateway as well as payment terminals can be managed in the ČSOB POS Merchant system (please check your contract if you are searching for the access credentials).
We shipped only a part of the original order to the customer. How do we refund the money?
Please use the payment/refund API operation to initiate a partial refund. Alternatively, you can log into the ČSOB POS Merchant system, find the original transaction and request a partial refund of the transaction.
Do I need ČSOB account to accept online payments?
Yes, one of the conditions for online card acceptance is settlement of the transactions to an account held with ČSOB. We will be happy to offer you one in our advantageous bundles for online merchants.
Do you provide the payment gateway for smartphones and tablets?
Of course. You do not need to change anything on your side, the payment gateway detects the customer's device and adapts automatically.
When will you settle the funds to our bank account?
Payments from customers paying with cards issued in the Czech republic are usually settled within the next business day.
Will I need to change the technical implementation when you roll-out new features in the future?
As the API of the payment gateway evolves, you do not need to immediately upgrade to the new version. However, in the longer term, some services will be closed (such as the ESR reporting, that is not available on the version 1.9 anymore). You will be informed in advance about the need to upgrade your integration in such cases.
How can we import the transaction information to our accounting system?
Sure. The majority of czech accounting systems supports the format in which we provide transaction statements.
Can we pre-authorize the transaction and debit the funds from the customer's account only when we ship the goods?
Yes. You can flag each individual transaction to automatically transfer the money at the end of the day or later. If you choose to transfer the money later, you need to complete the transaction within 7 days. You can complete the transaction manually in the ČSOB POS Merchant system, or using the eAPI from your shop backend.
ČSOB payment button transaction is paid by the customer, the ČSOB POS Merchant shows the transaction as “authorized”, but my e-shop system says the transaction is declined.
Payment button transactions have one specific of the lifecycle - the authorized transaction immediately transitions to state 8. Your e-shop system may evaluate only states 4 and 7 as “paid”. Therefore a small adjustment of the integration is necessary.
The customer complains that she/he can not pay online on your gateway. What could be the issue?
Based on our experience and data, the customers very often use cards which are blocked for internet payments. In such a case, the customer needs to contact her/his issuing bank and activate internet payments.
Can I accept cards also in my store or pickup location?
Yes, of course. We will be happy to offer you a payment terminal as an add-on to the payment gateway. Transactions made on the payment gateway as well as on the terminals can be conveniently managed in the ČSOB POS Merchant system (user name is found in the contract with the bank).
What is the minimum amount for an authorization payment?
We recommend an amount higher than 0.41 CZK (or equivalent in other currency, for example 0,017 EUR).
Notification of Change in Refund Processing
Dear Clients,
Due to new rules introduced by the card associations, the way of refunds are processed is changing. Refunds will now be handled as online refunds (“Refunds”).
Going forward, online refunds will be authorised directly by the card issuer—similar to a standard payment—meaning the authorisation happens at the moment the refund request is initiated. Previously, refunds were processed asynchronously as an “advice” message, meaning they could not be rejected by the issuer. The response you received did not reflect the actual outcome of the refund, so you had no real-time visibility into its final status.
Under the new process, card issuers will also be able to notify cardholders through online banking or other tools when the refund request has been accepted. This will reduce the number of refund related enquiries and, in turn, decrease calls to both issuer and merchant call centres—ultimately improving customer satisfaction.
After this project is deployed, we will be able to return the actual refund status to you (the merchant). If a refund is unsuccessful, you will be able to distinguish between a technical error and a merchant related (business) error.
With these changes, customers will immediately know whether their online refund request has been approved or denied.
Please note that customers may submit multiple refund attempts. If a request is denied due to technical reasons (e.g., temporary service unavailability, timeout, network issues), retrying is appropriate.
If, however, the refund is denied for business reasons, additional attempts will not help. We therefore recommend making no more than one additional attempt in the case of a business error. If the second attempt is also denied, the refund must be handled outside the payment gateway.
From the merchant’s perspective, the immediate decision provides clarity on the refund status, removes unnecessary manual steps, and reduces the risk of errors. This improves internal efficiency and speeds up dispute resolution, helping to maintain healthier cash flow.
How it worked until now
Until now, you used the existing payment/refund method and received an immediate confirmation from the payment gateway (within milliseconds) that the request had been accepted for processing. You could check the refund status via a payment/status request. For the first refund, the status changed from 8 (settled) to 10 (returned) once the refund was processed.
However, after the first refund, no further status change was available, so you could not verify whether additional refunds were actually processed.
What is changing
- When you call the payment/refund method, you will now wait slightly longer for the result since the request is processed by the card issuer.
- The gateway response will remain fast, but the final result will typically take 3–7 seconds, and in rare high load cases, up to 32 seconds.
Technical errors
- If the HTTP status code is between 500–599 and the resultCode is 900, this indicates a technical error.
- In such cases, retrying the refund is appropriate.
- The issue may be caused by temporary system unavailability or a connection interruption. We recommend retrying the refund request after a delay (e.g., after 1 hour).
Business errors
- If the HTTP status code is between 200–299 and the resultCode is 190, this indicates a business related error.
- These are usually issuer rejections, and historically, retries have also been rejected.
- Therefore, we recommend making only one additional attempt. If that attempt is also declined, you must resolve the refund outside the payment gateway.
Changes required by card associations
Processing will now be synchronous.
The paymentStatus value in the response will contain either the final refund status (“Payment Returned”) or an error. You can also monitor the status via payment/status. Processing times will be the same as for regular payments.
After receiving the response from the gateway, your system must be able to handle cases where the card issuer rejects the refund. If you have already implemented eAPI version 1.9 according to our GitHub documentation, no further changes are required.
We believe this change, mandated by the card associations, will significantly improve the refund experience for your customers.