- 1 SYSTEM REQUIREMENTS
- 2 INSTALLATION AND UPDATE
- 3 CONFIGURATION
- 3.1 General Settings
- 3.2 Individual Payment Method Settings
- 3.3 Other
- 4 ORDERS
- 5 Workflows
- 6 Translations
- 7 ACCESS AND PAYMENT DATA FOR OUR TEST SYSTEM
- 8 Known Issues
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.
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 https://docs.unzer.com/docs/system-requirements 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.
INSTALLATION AND UPDATE
The Unzer / heidelpay payment extension for Magento 2 is available for download from our GitHub repository: https://github.com/heidelpay/magento2-merchant-gateway
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.
heidelpay Merchant Gateway (MGW) entry and start with the general settings by opening the
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: https://docs.unzer.com/docs/testdata
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
Unregister webhooks deactivates all webhooks that are set up for the current store URL.
Find more information about webhooks here: https://docs.unzer.com/docs/webhook-overview
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”.
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
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.
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
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
http. Click 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.
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.
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.
… 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.
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.
- Open the relevant booking in the merchant front end, its status should be set to
Ready to Capture.
- Now select Invoice from the top menu and scroll down to the bottom of the page.
- In the dropdown menu select
Capture Onlineand then click on
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.
A 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:
- Open the order, which should have the status
- Now select
Shipfrom the top menu.
- Scroll down and click
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:
- Open an order and then go to the
- Select the paid invoice and click on
- 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.
- Clicking on
Refundtriggers 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
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.
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.
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.
ACCESS AND PAYMENT DATA FOR OUR TEST SYSTEM
You can find access data for our test system on the Test environment page
- 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 Onshould therefore remain the default value