User guide Magento 2 merchant gateway plugin

User guide Magento 2 merchant gateway plugin


The heidelpay/magento2-merchant-gateway plugin is designed for Magento versions 2.3 and higher. 

As soon as a Magento update is available, we will check the compatibility of the Unzer Magento 2 plugin. If problems occur, we will provide a plugin update as soon as possible. We will share this over Twitter.

The currently supported PHP versions can be viewed in the on GitHub and Packagist. 

Furthermore, your system must meet the standards required by Magento. As an example, here are the requirements for Magento 2.3: 

You should also note the requirements of our SDK.
You can find the relevant information under f.f. 

Only the proprietary Magento checkout is supported; Magento Multishipping Checkout is not supported. 

Third-party plugins and templates can affect the usability of our plugin and may even cause it to stop working. Before use and before each update, check to see if there are any effects on a test system. 


The Unzer / heidelpay payment extension for Magento 2 is available for download from our GitHub repository: 

However, we recommend that you install the plugin via Composer: 

composer require heidelpay/magento2-merchant-gateway 

Once Composer has installed the dependencies and the plugin, you need to activate it with the following command: 

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

Then execute the setup:upgrade command via the console, so that the plugin schemas can be imported into your database:
php bin/magento setup:upgrade 

The following commands clear the cache and execute the final steps for plugin installation: the generation of dependency injection and deployment of static files for the frontend. 

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

The installation is now complete and the plugin can be configured in the backend. 


In the store backend, switch to Stores → Configuration and there to the page navigation under Sales → Payment Methods. 

The configuration is not limited to the store Default Config and can be configured differently up to the Store View.
To do this, simply select the level which you want to configure in the top left.
The General Settings for the module can only be made in the Default Config. This means that currently only one keypair can be used per Magento installation.

General Settings 

Expand the heidelpay Merchant Gateway (MGW) entry and start with the general settings by opening the Settings entry. 

Public and private keys 

The plugin is supplied with access data for the Unzer heidelpay test system by default (sandbox mode). Financial transactions are NOT possible in this mode. It is only for testing. 

You can find the test data at:

For Live mode, please use the access data we sent on conclusion of the contract. The first letter of the keys determines the mode in which the transactions are executed.
p = Live mode (production)
s = Sandbox mode 


Please save the configuration before this step so that registration is carried out with the correct keypair. 

Webhooks notify the store of changes to the payment status, whatever the customer’s checkout process. This is particularly important for payment methods for which the actual receipt of payment will only occur later (e.g. invoice payment methods).
To activate webhooks, click on the button Register webhooks.
Unregister webhooks deactivates all webhooks that are set up for the current store URL. 

Find more information about webhooks here: 

Logging and Debugging 

This option can be activated to log debug information about the module; this information is written to the file var/log/hpmgw_debug.log. All queries to our payment interface and their answers are logged in JSON format. 

This option is only intended for troubleshooting and should be disabled in Live mode to save storage. 


Individual Payment Method Settings  

Now you can configure the individual payment methods. Expand the payment method to be configured, e.g. credit & debit cards. 

The setting options vary between payment methods. 


The title is the name of the payment method as it is displayed in the store and in emails. If your store supports multiple languages, when editing ensure that this is implemented per store or enter a translation in the language files. 

If you leave the default value in this field, it will be automatically translated into German if your store is set to German locale. 


This is used to activate the respective payment method in the store, so that it is offered to customers at “checkout”. 

Booking Mode 

It is possible to configure the booking mode for the payment methods Credit & Debit Cards and PayPal. You can choose between the modes Debit (direct booking) and Authorize (pre-authorization, where the booking is executed when the invoice is created). 

Sort Order 

This allows you to determine the order in which payment methods are displayed in the store. 

Minimum and Maximum Order Total 

Customers can select the payment method if the order total is between these two values only. To deactivate the limit, the corresponding value must be set to 0. 

Merchant Name 

This determines the merchant name displayed in the direct debit mandate for the respective payment method. 


Using stores without SSL 

The plugin generates URLs for redirects to the store and webhooks so that your store can be informed about the status of the payment. These URLs are forced in a secure environment. That means: Store URLs are always directed to payment with https://. 

If your store does not use SSL, a reply from the payment cannot be forwarded to your store. 

However, if you want to make payments on a test system for example, you can rewrite the https URLs so that the URLs are always prefixed with http://. 

Switch into the backend of the store using Stores → Configuration and from there into the page navigation GENERAL → Web. 

Click on the tab Base URLs (secure) and change the setting Secure Base URL from https to httpClick Save Config and empty the cache. 

Now you are also able to use the Unzer / heidelpay plugin in an http environment.
We do not recommend doing this in Live mode and advise the integration of SSL/HTTPS! 


For guaranteed payment methods, we recommend setting the salutation in the customer details as a required field. This can lead to a higher success rate.
You can enable it here:
Stores → Configuration → Customers → Customer Configuration → Name and Address Options → Show Gender 


The order number in the store is the same as the one on the heidelpay Intelligence Platform (hIP) and is assigned by it. 

The Comments History in the Order View shows the progress of the payment process. Here is a credit card payment as an example. 

The order was created and set to the status Ready to Capture because the order was executed as an authorization. When the invoice is created, the reserved amount is debited and the order is set to Processing. 

The UniqueId and ShortId are listed here for the initial transactions.
Please provide us with this information if you require support. 

Order status 

The order status indicates where the order is in the order process. We have followed Magento 2 here and added the status Ready to Capture (see below), which is automatically added when the module is installed. 

As the order status in Magento 2 is not suitable for displaying the payment status, please make sure that the invoice for an order is marked as paid to find out whether the payment was successful. 


Under Sales → Invoices you can filter all invoices with the status “open”. 

Partial payments (e.g. for invoice payments) are not recorded in the Order Totals overview. You can find this in your hIP account. 


Below we have listed the individual status and their meanings. 


… is the initial status of an order. If there are delays during the status synchronisation between Unzer / heidelpay and the payment provider (e.g. PayPal), orders may remain in this status initially and notification of success or error during the payment process will reach the store later. 

Payment Review 

… is used in case of invoice payments after the goods have been shipped. The order remains in this status until the payment is complete. The store will be notified via webhook event. This status is also applied if the customer has paid too much. 

Ready to Capture 

… indicates that the authorization was successful and the amount can be collected. To do this, an invoice must be created manually by selecting Capture Online for the corresponding order. For details, see the section Capturing an authorization. 


… indicates that the shipment of the goods can be initiated. 


… means that the payment was cancelled after the order was created. This can happen if for example an order is first created with the status “Pending Payment” and then a third-party system such as PayPal, Sofort etc. reports that the payment was not successful. 


… indicates that payment has been received and the order has been shipped. 


… shows that an order has been fully refunded.



Capturing an authorization online 

A capture retrieves a previously authorized amount. This is possible with the payment methods Credit & Debit Card and PayPal, if the Booking Mode Authorize is configured. Currently only one complete order capture is supported. 

  1. Open the relevant booking in the merchant front end, its status should be set to Ready to Capture.
  2. Now select Invoice from the top menu and scroll down to the bottom of the page.
  3. In the dropdown menu select Capture Online and then click on Submit Invoice

Magento 2 then generates an invoice which can be found under Invoices. The invoice is marked as “paid” and the status changes to Processing. The order is now ready for shipping. 


credit card charge for the order will now be visible in hIP. 

Finalizing a guaranteed invoice payment 

In order to activate the insurance of a guaranteed invoice method, the payment must be finalized. This is done by shipping the goods. 

Please follow the steps below: 

  1. Open the orderwhich should have the status Processing.
  2. Now select Ship from the top menu.
  3. Scroll down and click Submit Shipment

Magento creates a shipment note for the order and changes the status to Payment Review. You will now find a finalization for the previous reservation in hIP.

Crediting an order (online) 

A payment can only be credited via the invoice. If the credit is executed directly on the order, it will only take place “offline”, which means that no transaction is triggered and no money is refunded. 

Follow the following steps to create a credit memo with refund: 

  1. Open an order and then go to the Invoices tab
  2. Select the paid invoice and click on Credit Memo 
  3. Here you can set which products are to be refunded
    (Qty to Refund). Upon clicking on Update Qty's, Magento will re-calculate the amount to be refunded.

  4. Clicking on Refund triggers the credit memo and completes the process. 


Reversal of balances 

If only partial payment was made for an invoice payment, this will not be shown in the Magento invoice. This is only marked as paid when the payment is complete. If a part of the order is returned, the balance must be cancelled via hIP. This changes the status of the order in hIP to paid , the store is notified and the invoice in the store is set to paid. 

Now you can make an Offline Refund in the store to correct the order accordingly. As it is not possible to clearly identify which item was returned, this does not happen automatically. 

A reversal of partial amounts is currently not supported for authorizations. 

Full cancellation 

Open reserved amounts are automatically released when the order is cancelled.
This cancels the complete payment and the order. This function is only available before shipping if an amount has been reserved but the invoice has not yet been marked as paid. 

  1.  Select the order and click on “Void”.

  2. A query appears which can be confirmed by clicking “OK”.


Typically in Magento, text and translations can be found in the language files in the i18n folder, which can be found in the Plugin folder. You can customize the files, but make sure to create backups before updating.


You can find access data for our test system on the Test environment page 

Known Issues 

  • Currently Checkout does not allow you to update the billing address from the payment method page. The setting Stores → Configuration → Sales → Checkout → Display Billing Address On should therefore remain the default value Payment Method.