In this article you will find a list of the requirements for integrating the GoPay payment gateway into suppliers' commerce platforms (e.g. e-shop solutions of the Shoptet or Eshop-rychle.cz type).
The individual requirements are based on GoPay's long-standing experience with integrations of the GoPay payment gateway into these solutions. Their aim is to ensure that the GoPay payment gateway is displayed and works optimally for end users and to achieve the maximum conversion performance of the whole order process.
💡 GoPay tip: Do you want to become a GoPay Certified Supplier? Integrate GoPay according to the requirements given, have your integration assessed and obtain the GoPay Certified Supplier designation. You will find more information in the article "How do I obtain the GoPay Certified Supplier designation?".
Technical requirements
When implementing the payment gateway, your solution must meet the mandatory criteria and should follow our recommendations.
Mandatory criteria
Please give GoPay technical support a sample test page with a sales form and access to its administration (environment) from the merchant's point of view.
Access must not be conditional on installing a third-party solution / application – please provide web access to the sample page and to the administration.The integration with the payment gateway must use the REST API (V3).
Use the latest version of the SDK libraries and of the PHP, .NET, Java and similar languages.
The e-shop will run on a secure page with HTTPS; TLS support must be at least version 1.2.
Payments in the production environment must always take place from the same e-shop URL address that was registered and approved for the business account, see the article "Which URL can I create payments from?".
Make sure that the payment status query is always carried out after the redirect (
return_url) and the HTTP notification (notification_url) and that the relevant orders are updated correctly. Please do not make the payment status query in a loop.For orders, please display the names of the order statuses correctly and understandably for clients.
When the customer goes to the order basket (checkout) in the e-shop, please obtain the list of allowed payment methods (the list returned is always in Czech). Please call this function only once; do not send requests to it in a loop.
In the order basket, make sure the payment methods are displayed correctly – you can choose between direct / aggregated presentation, see the examples below. To display a pre-selected payment method at the gateway, please use the default_payment_instrument parameter in the payer object. The payment methods must not, however, be merged into a single option, i.e. so that the customer has to choose the method only at the gateway. The list of payment methods can be cached, but it must be possible to update it so that changes are reflected if the merchant disables / enables some methods in their GoPay business account. Alternatively, the merchant can be offered their own payment method settings in the plugin configuration. In that case, make the API call to obtain the payment methods in the plugin configuration, at the moment when the merchant is configuring the payment methods within the plugin.
If your environment supports several language versions and not only Czech, convert the payment method names and display them in the corresponding language (for example, on an English page display the English payment method names Payment card, Online bank transfer and so on).
Please make sure that the Apple Pay payment method is displayed to customers in the order basket only when supported Apple devices with the Safari browser are used. You will find implementation information in the "How do I integrate Apple Pay?" part of our article, or directly on the Apple developer page.
To present the payment methods, please use only the correct payment method logos.
Prevent payment methods being charged for.
Once the payment has been created, please make sure the payment gateway is invoked, see the "Invoking the payment gateway" part of our article. Offer the merchant a choice between Inline and Redirect.
In your administration, please present the correct names of the values Client Secret, ClientID and GoID, and likewise offer the merchant the option of configuring the test and production environments.
In your administration, make sure the values are validated (Client Secret, ClientID and GoID for the relevant environment variant – test / production) whenever the merchant changes the settings there, as follows. You verify the Client Secret and ClientID by obtaining an access token, and you check the GoID by obtaining the list of allowed payment methods. Please do not carry out the verification in a loop.
Please always pass all the parameters within the contact object. Always pass the customer's phone number including the dialling code (e.g. +420).
Please handle all the possible scenarios you support for successful / unsuccessful completion of payments, as well as the situation where the customer returns to the e-shop (order) without confirming a payment method at the payment gateway, and the situation where a bank has been confirmed at the gateway for an offline (standard) bank transfer. Specifically, these are the following situations.
Payment paid (PAID) – the customer returns to the e-shop and must be shown a summary confirming that the payment was successful.
Payment declined (CANCELED) – the customer did not complete the payment successfully and returns to the e-shop, where a summary should be displayed with information that the order has not been paid, and they should be offered the option of making a new payment, or the option of being sent an e-mail with a link for making a new payment.
Payment expired (TIMEOUTED) – the customer may have stayed at the gateway too long and did not return to the e-shop; they then refresh the order and information should be displayed that the order was not paid successfully, so again offer the option of making a new payment or of being sent an e-mail with a link for making a new payment.
Payment method selected (PAYMENT METHOD CHOSEN) – in this situation the payment result is awaited; the payment has not been paid yet, but it may be paid later. This situation most often arises with an offline bank transfer (if the merchant has Offline enabled for Bank transfers in their GoPay business account), but it can exceptionally occur with other payment methods as well. In this case the customer should not be offered the option of paying again, so that a double payment does not occur. If the payment subsequently ends in the TIMEOUTED state, GoPay will send an HTTP notification, on the basis of which an e-mail with a link for paying again can be sent to the customer.
Created (CREATED) – the customer did not confirm any payment method at the payment gateway, returned to the e-shop, the payment lifetime has not expired yet (which can be checked by a query after the redirect) and they should be able to continue with the same payment for that order.
A possible scenario in a non-standard situation – if the customer closed the window at a point when they had not confirmed any method at the gateway and did not redirect back to the e-shop from the gateway, and then, for example, opened the basket / order in a new browser window (by logging in to their account at the e-shop), this can be handled when the customer enters their account (for the relevant order) by making a payment status query outside the recommended situations (redirect, HTTP notification); it is enough to do this once / on entry (do not check the status in a loop). Using the payment id you previously saved in your database you obtain, for the relevant order, information about the current state of non-completion/payment. If the payment is still in the CREATED state, you can offer the customer a new invocation of the gateway for that payment with the order (the pre-selected method stays the same). If any other situation described above arises, you can follow the corresponding recommendation.
Optional – recommended options
If you offer the e-shop in several language versions, please also pass the lang parameter with the corresponding language when creating the payment.
If a payment is unsuccessful, offer and send the customer an e-mail with a link for paying again. The payment link can be generated in the standard way as the gw_url parameter and placed in the body of the e-mail. For the payment you can offer the same pre-selected payment method as for the original payment the customer made for the order. You can take inspiration from our article, specifically the "Placing the push payment in the order confirmation e-mail" part.
For greater convenience for clients, you can allow GoPay to pass merchants' production credentials (Client Secret, ClientID and GoID) directly into your platform's administration. That means providing access by logging in on the merchant's domain at www.nejakyeshop.xy/gopay-login. After logging in, a GoPay technical support engineer will be able to enter the necessary values into the form.
Other functionality you can offer
Payment refunds – offer customers the option of having funds returned.
Recurring payments – allow customers to have payments taken regularly, in one of the two supported variants.
Pre-authorised payments – this functionality is suitable for use in combination with recurring payments, for pre-orders and for payment for services where the amount may change or where the payment may not take place in the end. We guarantee a block for up to 4 days.
Downloading statements of movements via the API – this functionality allows statements of movements to be downloaded in the supported formats.
Unique card fingerprint and Payment by card token – this functionality makes it possible, through the card fingerprint, to verify that a particular payment card was used for the payment, and also to ensure that this particular card is used for subsequent payments (it can be used for a standard payment, an initiating recurring payment and a pre-authorised payment).
PSD2 payment by account token – this functionality makes it possible, for PSD2 (express) bank transfers, to ensure that payments in the remembered mode are made to the customer's particular bank account.
Requirements for presenting GoPay
To present information about GoPay on your pages or in the administration of your solution, work solely from the article "What information about GoPay can you present to customers"? If you want to present information beyond what is given in the article, always inform GoPay and consult the intended result with us.
Make sure that the merchants using your solution can register with GoPay through the registration form assigned to you with its specific URL address. Registration through this form lets us recognise that the merchant uses your solution.
Present the link to the registration form in a visible place in your solution's administration and on your website, if you give information about GoPay there.