This article provides information for developers who would like to develop a connection to the Shoptet payment gateway.
If you are a Premium client, contact your Account or Onboarding Manager. A new payment gateway must be approved by Shoptet, and the client needs to be familiar with the payment terms in advance.
The following sections must be implemented to integrate the payment gateway. The next chapters provide the details of each step.
Contact our Shoptet Partner Manager to create a record for your payment gateway in Shoptet. In this record, we will register the payment type and your gateway for redirection. If different payment methods are to be displayed separately in the e-shop (e.g., “Card Payment,” “Online Transfer,” “SMS Payment”), multiple records will be created. Additionally, records can be created both for live operation and for the development environment. This record registers the payment gateway as an intermediary or a technical means of implementing the payment.
The URL gateway must contain 2 placeholders, which will be used to pass the e-shop identification (ID or URL) and the one-time transaction code at the time of payment:
#ESHOP_ID# – E-shop number#ESHOP_URL# – E-shop URL#PAYMENT_CODE# – One-time payment transaction code (32 alphanumeric characters)#LANGUAGE# – E-shop language code. Possible values: cs, hu, sk, en, pl, de, vi, ro, bg.For example https://pay.to.me/gateway/#LANGUAGE#/#ESHOP_URL#/#PAYMENT_CODE#/
The language of the payment gateway can be set by the #LANGUAGE# value, or by the value of the eshopLanguage attribute in E-shop info API endpoint.
The second step is to create the payment method. Payment methods are created separately in each e-shop and are issued by the intermediary created in the preceding paragraph. Payment methods are created in the administration interface of the e-shop, and their labels, prices, terms and conditions must be set according to the currency, delivery country, delivery service, or order price. A logo may also need to be set. For more information, please visit Support.
However, the payment method can also be prepared for e-shop operators so that they make the settings look as per needs and save them from painful work. To create it, you must be registered as an intermediary (see the first paragraph). The creation is performed using the POST /api/payment-methods endpoint.
Set up the new payment method as inactive so that it does not appear in the e-shop before the operator reviews and confirms it, or modifies the parameters. The payment method should also not be visible before the e-shop operator signs the contract and obtains access to the payment gateway.
Once an addon is installed in the e-shop and a payment method is created, it will be displayed automatically (if the conditions are met in combination with transport, currency, order amount, etc.).
If the purchaser has selected your payment gateway, an online payment button will appear on the order confirmation page (Thank you page). The user can click on it or will be automatically redirected to your payment gateway after 5 seconds (using the gateway URL you provided).
In the gateway URL, the #ESHOP_ID#, #ESHOP_URL# and #PAYMENT_CODE# placeholders will be replaced with actual values. The payment code serves as the identifier of the payment transaction.
The link to the Thank you page in Shoptet (and in the customer’s confirmation e-mail) contains the Shoptet URL, which in turn redirects to the payment gateway URL.
The payment gateway can modify its API, or the addon can create a “proxy” between Shoptet and the payment gateway API.
In the first step, the addon must obtain information about the order being paid and the URL to return back to the e-shop. This is done using the endpoint [GET] /api/payment-status/{paymentCode} – see also Documentation.
For order information, please use the Order detail. Note that the order code may look like a number but is actually a string (it may also contain letters).
If you need detailed information about the e-shop (e.g., email, language), you can use the endpoint E-shop info.
You should assume that purchasers may return to the payment later (e.g., via an email link). The addon must verify whether the order has already been paid (the purchaser has clicked the link again, for some reason), or canceled in the meantime. If the order is already paid or canceled, this is considered an inconsistent situation and should be escalated to the e-shop owner and, if applicable, the purchaser.
The rest of the payment is processed according to the payment gateway’s functionality – e.g., selection of payment method, data entry, etc.
The result of the payment should be reflected in two places:
The payment result is set by calling the endpoint [PATCH] /api/payment-status/{paymentCode} – See also Documentation.
The available payment result statuses are:
Order status must be set depending on the payment result. Shoptet e-shops allow configurable order statuses, so each e-shop must define which status corresponds to each payment status.
You can retrieve the list of order statuses defined in the e-shop by calling the E-shop Info endpoint: /api/eshop?include=orderStatuses – See also Documentation or List of order statuses.
The payment gateway addon must be able to set at least the status that corresponds to the payment of the order. It is better, however, to allow the e-shop operator to set up a situation that will be set in case of payment failure, and if it is waiting for the confirmation (the “pending” status).
Order status is set using the endpoint: PATCH /orders/{code}/status (See also Documentation).
In the event of a successful payment, the form of the payment, corresponding to the payment method chosen by the user for payment, should be indicated (typically card for online payments).
The “payment flag” (i.e., switching to a given status also marks the order as paid), automatic document generation (invoice, delivery note), and email sending are handled within Shoptet’s status definitions and are outside the responsibility of the payment gateway addon.
Optionally, the addon can send email notifications to the purchaser and/or e-shop about payment progress or irregular statuses.
Optionally, the addon can add information to the order, for example the payment number on the payment gateway side using the Order Change Notes or History Remark endpoints.
Unfortunately, it cannot be excluded that the order will not change during the payment process, especially if it takes a long time. The addon should therefore also verify the following:
paymentMethodGuid) has not changed.The addon is responsible for resolving any inconsistencies, based on the procedures defined by the payment gateway operator. In all cases, it’s good practice to inform the e-shop operator.
Once the order status and payment result are set, the addon calls Shoptet’s return URL.
Shoptet will display the Thank You page based on the payment status:
OK – Shoptet checks if the order is marked as paid. If not, an inconsistency warning is shown.PENDING – The purchaser is informed that the payment was entered correctly and the order will be marked as paid once payment is received. Any attached message will be displayed.FAILED – The purchaser is offered an option to retry the payment or contact the e-shop owner for an alternative method.Besides initial payment handling, the addon should track ongoing payment changes and update order statuses accordingly. Optionally, it can send email alerts or notifications for payments that remain pending for too long.
The addon may also send links for repeat payment in case of failed attempts.
Addon settings can be configured directly in the Shoptet administration. The client account is usually initialized during addon installation. The identity of the e-shop operator can be verified directly in Shoptet via OAuth.
The addon must provide a GUI with at least the following configuration options:
/api/eshop?include=orderStatuses/api/order/{code}/notes can be used to insert a note, for example the payment number, more payment details (especially for underpaid/overpaid payments). If one of the optional fields (1-6) is used, it is recommended to have the e-shop operator set the fields this will be (their list can be obtained from the endpoint /api/eshop?include=orderAdditionalFields). However, these fields are written onto the order! Alternatively, you can use “eshopRemark” – then it is recommended to add it to the field (read the current value, attach a note, and save)