This article will provide information to developers who would like to develop a connection to the payment gateway for Shoptet.
If you are a Premium client, contact your Account or Onboarding manager. New payment gateway has to be approved by Shoptet and client needs to be familiar with the terms of payment in advance.
The following sections must be implemented to integrate the payment gateway. The next chapters will give the details of each step.
Contact our Shoptet partner manager to create a record for your payment gateway in Shoptet. In it, 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. In addition, the records can be created once for live operation, and once for the development environment. This record will register the payment gateway as an intermediary, or a technical means of implementing the payment.
The URL gateway must contain 2 placeholders, in which we will pass you 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.For example https://pay.to.me/gataway/#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’. The payment methods are already created in each e-shop separately, and are issued by the intermediary created in the preceding paragraph in the e-shop. Payment methods are created in the administration of the e-shop and labels, prices, terms and conditions must be set according to the currency, delivery country, delivery service or order price, or the logo must 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, 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 its operator views it 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 a 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 is automatically redirected to your payment gateway after 5 seconds (the gateway URL you provided to us).
In the URL gateway, the #ESHOP_ID#, #ESHOP_URL# and #PAYMENT_CODE# placeholders will be replaced with actual values. The Payment Code serves as identification 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 will redirect you 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 ordering information, please use Order detail. Note that the order code looks like a number, but it 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 endpoint E-shop info.
You should assume that purchasers can still get to the payment later than immediately after the purchase, e.g. via e-mail link. The addon must verify if the order has already been paid (the purchaser has clicked the link again, for some reason), or has not been canceled in the meantime. If an order is already paid or canceled, it is an inconsistent situation, and should be escalated to the owner of the e-shop and, if applicable, the purchaser.
Further on, the payment is already processed according to the function of the payment gateway, i.e. optionally selecting the payment method, calling to enter the data, etc..
The result of the payment should be reflected in two places:
The resulting payment status is set by calling the endpoint [PATCH] /api/payment-status/{paymentCode} – See also Documentation.
The payment result has the following statuses:
The order status needs to be set depending on the payment result. Shoptet e-shops have a configurable order status, so it is necessary to assume that in the setting for each e-shop you need to specify which order status corresponds to which payment status.
You can find the list of order statuses that are defined by 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).
The order status is set by calling the endpoint change order status 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 will also mark the order as paid), the possibility to generate documents (invoice, delivery note), possibility to send an e-mail are part of the status definition in Shoptet. This is not in the responsibility of the payment gateway addon.
Optionally, the addon can send an e-mail to both the purchaser and the e-shop about the payment progress, or if a non-standard status is detected.
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 solution to any inconsistency must be done by the addon. The solution is individual according to the payment gateway operator’s process procedures. However, it is always good to inform the e-shop operator so they understand the situation.
If order status and payment result are set, the addon will call our return URL.
Shoptet will render the Thank you page according to the payment status:
OK, we will verify that the order is paid. If it is not the case, we need to notify about the inconsistency.FAILED state), we will offer a repetition of payment, or will contact the owner of the e-shop and arrange an alternative payment method with them.In addition to the payment itself, the addon still needs to track the changes of the payments in progress and set order statuses accordingly. As an option, it can send e-mails or notify you of payments that are being processed for too long.
The failed payments can be sent by a addon with a link for repeat payment.
The addon settings can be [placed directly in administration] in Shoptet (/uvodni-stranka/api/dokumentace/nastaveni-doplnku/). 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 shall provide its GUI for setting parameters, as a minimum:
/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)