User guide Magento 2 extension


The heidelpay Magento 2 Plugin can be used for all Magento 2.0.x –  2.3.x versions.

As soon as an update is available for Magento, Unzer proofs the compatibility of the Magento 2 plugin. If there are any disruptions Unzwer will provide an update of the plugin immediately

The plugin supports the PHP versions 5.6.x, 7.0.x, 7.1.x, 7.2.x and 7.3.x.

Furthermore your system has to fulfill all the requirements given by Magento.

Only the Magento own checkout will be supported, a support of the Magento multishipping checkout is not available yet.

Foreign plugins and foreign templates can affect the usability of the plugin likewise lead to a dysfunction. Please proof in the test system if there are any affections before making an update.


If there is an older version installed app/code/Heidelpay please erase the files from the server now.

The heidelpay payment-extension for Magento 2 is available to be downloaded in the GitHub Repository:

We recommend the installation of the plugin via composer:

composer require heidelpay/magento2

If the composer has installed all requirement and our plugin, you have to activate it by using the following command:

php bin/magento module:enable Heidelpay_Gateway --clear-static-content

Afterwards please run the setup:upgrade method from Magento2 so that the schema of the plugin can be updated as well .

php bin/magento setup:upgrade

The following command helps to erase the cache for security reasons and final steps for the plugin installation will be executed. (Generation of the dependency injection and the deployment of statistical files for the frontend).

php bin/magento cache:flush
php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy

Afterwards the installation is completed and the plugin can be configured in the backend.



Switch in the backend of your shop to „Stores“ „Configuration“ and follow the page navigation „Sales“ “Payment Methods“.

The configuration is not limited to the „Default Config“ of the shop, I can be taken until the store view, so that you can use f.e. different login data per language shop. Please set the configuration on the left side for the specific level.


General settings

Open the entry  „Heidelpay“


Start with the general settings. Please open the entry „Settings“


The plugin will provide login data for the „heidelpay test system“. (Sandbox-mode). There are NO transactions of money possible in that mode. IT is only usable for testing.

If you would like to make use of the live mode, please type in the login data which you have received from the heidelpay support  and switch in „Sandbox-Modue“ to „No“.

In the field „IFrame CSS“

you are able to enter an URL for a CSS-file. This file will be validated by the heidelpay server and implemented in the credit card and debit card iframe. If you need a documentation on which parameter for the CSS are allowed, please contact the heidelpay support. (supportmail)

Setting of the individual payment methods

Now you are able to configure the individual payment methods. Just open the payment method like f.e.  „credit card“.


The setting possibilities can vary between the different payment methods. In general they have the following settings:


The title is the name of the payment method and how it is displayed in the shop and in the emails. This name can be changed by you. Please note that if several languages are supported, you have to implement them by store or you have to register the translations in the language files.


Hereby you are activating the payment method in the shop.


Type in the received heidelpay channel for the payment method. During the installation a channel for the test system will be consigned.


Some payment methods are using a direct entry of payment methods in the shop. Please use this option if you like that these entries will be loaded for the customer for a new order. Never‚ means that the files will never be loaded. Same Shipping Address‚ means the information will only be loaded if the shipping address is the same like in the order before. Always‚ means that the payment information for the specific payment method will be loaded for the customer.

Booking Mode

There is the possibility to configure the booking mode for the payment methods credit card and debit card as well as PayPal. Choose between the mode direct debit „Debit” and pre-authorisation  “Authorization”.

Sort Order

Hereby you determine the sort order of the payment methods in the shop.

Payment from applicable countries/ payment from specific countries

Determine for which countries the payment methods should be available.

Use of shops without SSL

The plugin generates the returning-answer of the payment URL, so that the shop can be informed about the payment status in the shop (Request -> Response -> Redirect). These URLs will be forced in a secure context. It means that the shop URL will always be send with https:// to the payment.

It is not possible to forward an answer from the payment to your shop if your shop is not using SSL.

If you would like to make payment transactions in the test system f.e. you can rewrite the URLs.

Switch into the backend of the shop   „Stores“ „Configuration“ and into the page navigation „General“ “Web“.

Click on r „Base URLs (Secure)“ and change the setting „Secure Base URL“ 

the https into http. The Magento 2 backend will request to empty the cache. Please empty the cache. Now you are able to use the heidelpay plugin also in the HTTP context.

We do not recommend this in the live mode and advise the implementation of SSL/HTTPS!


You are able to comprehend the payment process by looking at the ordering details.

Please take a look at the example for a payment with credit card below.


The order was attached by heidelpay (see „heidelpay – saving order“) and afterwards changed into “edit”.  Furthermore the shortID for the transaction was consigned. With this shortID you are able to find the transaction easily in the hIP (Heidelpay Intelligence Platform).


For each payment a transaction for the order will be consigned, which can be seen in the order at Transaktions


Alternatively you can find all transactions here  „Sales“ „Transaktions“.


Order status

The order status is not suitable to display the payment status. Please note for the orders that an order is market as paid.


This can be seen in the invoice overview of the order.


Please go to   „Sales“ „Invoices“where you have the possibility to filter all invoices with the status „open“.

The ordering status itself shows the working process. Heidelpay kept to the requirements of Magento.


Pending Payment

The payment process is not finished and the dispatch is not possible yet. This can be the case f.e. for credit card reservations.

Payment Review

This payment process is finished certainly there is a deviation. This can be if there is f.e. a deviating amount or currency.


The dispatch of the order can be initiated.


The order was marked as cancelled after the attachment of the order. This can be the case if an order is consigned with a “pending payment” first and then a third-party system like f.e. PayPal or SOFORT- Überweisung report that the payment was not successful.


The order was successfully dispatched.


Capturing an Authorization

Please perform the following steps in order to capture a reserved amount (e.g. by means of a credit card payment):

  1. Select the order in your merchant frontend, it should have the state “Pending Payment”.
  2. Now select “Invoice” in the top menu and scroll down to the bottom of the page.
  3. Select “Capture Online” in the drop down menu and click “Submit Invoice”.

The new invoice can be found under “Invoices” and is marked “Paid”. The state of the order has changed to “Processing” and it is now ready for shipment.

A new Capture-Transaction (CAP) has been created for the authorization (RES) and is visible in the hIP.

Finalizing a secure Payment

In case of a secure payment method there has to be a finalize transaction which marks the start of the insurance of the payment. Because an order can be shipped in chunks, this is generally done with the shipment of the order.

Please follow these steps to perform a finalize:

  1. Select the order in your merchant frontend, it should have the state “Processing”.
  2. Now select Shipment in the top menu.
  3. Scroll down to the bottom of the page and click “Submit Shipment”.

Magento creates a shipment for the order and changes its state to “Pending Payment”. You can see the notification “Shipping Notification has been sent to Heidelpay.”.

In hIP is a new finalize transaction (FIN) belonging to the initial reservation (RES).


If you are planning to make use of SOFORT or if you are already using SOFORT heidelpay, please contact the heidelpay support who will configure the SOFORT project with entering bank account data.

The heidelpay support can be reached via email or via phone 06221-65170-10.


Some payment methods (beneath secured purchase on account B2C, since version 17.4.16) require the push-functionality of the plugin to edit payment entrances. Thereby this functionality will work your channel has to deposit a push-URL. Please contact your contract partner to activate this functionality and to deposit the push-URL for the shop and the specific payment method.

The URL is always the following:

This plugin creates the order as soon, as the customer is redirected to the shop after successful payment. This can lead to an existing payment in hIP but missing order in the shop if the customer stops the redirect by closing the browser or tab.
In this case the Order will be created as soon as the shop receives the push of a debit or receipt transaction.



Usually the Magento texts and translation will be adapted in the language file in the folder „i18n“, which can be found in the plugin folder. The files can be adapted, please note that you secure the files before making an update.

Whitelable Payment Frame

Due to the PCI 3 payment standards the payment methods debit card and credit card will be integrated in the shop via iframe. You are able to indicate a CSS file in the backend of the shop which affects the look. See chapter 3.1. Settings


Login data for the test system can be found here.  sandbox-environment