This technical manual is for installing and configuring our new free plugin for integrating MultiSafepay payment solutions into your Magento 2 webshop.
The new plugin features code improvements, and unit and integration testing. It is built on top of the Magento payment provider gateway structure. Some payment methods now skip the MultiSafepay payment page, which increases conversion.
We support most Magento functionalities. For any questions, email the Integration Team at [email protected]
As of version 2.4.0, we also support Magento Vault and Instant Purchase. For more information, see MultiSafepay Blog - Magento 2: Boost conversion through Magento Vault & Instant Purchase.
These features are based on recurring payments.
Features that are no longer available:
Our plugin is supported by a certified Magento 2 Solution Specialist and receives regular updates for the latest features from Magento and MultiSafepay.
Pay later methods
The plugin consists of several Magento modules:
|Multisafepay-magento2-core||Provides core functionalities|
|Multisafepay-magento2-frontend||Enables payment gateways in the Magento checkout|
|Multisafepay-magento2-adminhtml||Enables/disables payment gateways, and changes settings in the Magento backend|
|Multisafepay-magento2-msi||Handles stock when MSI is enabled|
|Multisafepay-magento2-catalog-inventory||Handles stock when MSI is disabled|
|Multisafepay-magento2||Meta package that installs all the above|
|Multisafepay-magento2-graphql||For GraphQL support, extends and adds GraphQL queries and mutations|
The meta-package has a dependency on MSI. This means the MSI modules must be available (but not necessarily enabled) in your store.
If you have removed MSI (e.g. with a composer-replace trick like yireo/magento2-replace-inventory), you can’t install the meta-package. To integrate with MultiSafepay, instead of installing the meta-package, install the magento2-frontend module and the magento2-catalog-inventory module.
The magento2-frontend module has a dependency on the magento2-core and magento2-adminhtml modules, so they are all installed together. In some cases, you also then need a stock-handling module. Since MSI is not available, you can install the magento2-catalog-inventory module instead.
The installation process is the same for the Adobe Commerce version.
Note: Make sure you finish processing all orders created in the deprecated plugin before you delete it. Meanwhile, it can run in parallel with the new plugin.
1. We recommend installing the meta-package using Composer:
composer require multisafepay/magento2 php bin/magento setup:upgrade php bin/magento setup:di:compile php bin/magento setup:static-content:deploy
2. To enable all the modules, use the following command in the Magento 2 root directory:
./bin/magento module:enable `./bin/magento module:status | grep MultiSafepay_`
When you disable MSI in Magento 2, you must also disable the MultiSafepay MSI module using the following command:
php bin/magento module:disable MultiSafepay_ConnectMSI
If you have enabled MSI in Magento 2, to disable the MultiSafepay CatalogInventory module, use the following command:
php bin/magento module:disable MultiSafepay_ConnectCatalogInventory
Sign in to your Magento 2 backend, and go to Stores > Configuration > MultiSafepay. This section contains the following pages:
You can download MultiSafepay logs via the configuration backend.
You receive a ZIP package containing a system report file and any MultiSafepay log(s) stored in the
You can update the plugin via Composer.
To update the plugin in your backend, follow these steps:
composer update multisafepay/magento2 --with-all-dependencies php bin/magento setup:upgrade php bin/magento setup:di:compile
Depending on your webserver/webshop configuration, you may also need to:
Our plugin supports Magento Vault, which lets customers securely store their payment details as a [card-on-file token](/features/recurring-payments] in the Magento database. This makes subsequent payments faster and easier, increasing conversion. At checkout, customers can simply select the Instant purchase button and don’t have to re-provide their CVC.
For more information, see Magento 2 – Adding vault integration.
Requirements from Mastercard and Visa
Activating Magento Vault
To activate Magento Vault in your backend, you must first enable recurring payments in your MultiSafepay account.
For support, email the Integration Team at [email protected]
The MultiSafepay Magento 2 plugin supports Payment Components, which:
If you’re new to accepting credit card payments, email applications to activate them your account manager at [email protected]
Activating the Payment Component
To activate the Payment Component in your Magento 2 backend, follow these steps:
For questions, email the Integration Team at [email protected]
Note: If you have a custom checkout and encounter a conflict with the Payment Component, the Integration Team will do their best to provide support, but we can’t guarantee compatibility in all cases.
Applying surcharges or payment fees is no longer supported in the Magento 2 plugin.
Using Fooman To apply a surcharge or payment fee to a payment method, you can use the third-party Fooman package.
Support The Integration Team will do their best to support you with installing Fooman, but bear in mind that it is a third-party package. We can’t guarantee perfect compatibility.
PSD2 implications For more information about how the Payment Services Directive 2 may affect surcharges or payment fees, see Payment Services Directive 2.
The Magento 2 plugin supports generic gateways. Generic gateways work like regular redirect payment methods. All features are supported, except for recurring payments.
Configuring generic gateways To configure generic gateways, follow these steps:
For any questions about integrating generic gateways, email the Integration Team at [email protected]
Configuring Magento tax settings
To configure tax settings in Magento, go to Stores > Configuration > Sales > Tax > Calculation settings.
Recommended tax settings
To avoid discrepancies between item amounts in MultiSafepay transactions and Magento orders, we recommend using the following tax settings in Magento.
To show prices excluding tax, use the following settings:
To show prices including tax, use the following settings:
These recommended settings are based on Magento’s standards. For more information, see Magento - Warning messages.
The way you delete the deprecated plugin depends on the way you installed it:
Composer There are two options:
Option 1: Remove the code base
composer remove multisafepay/magento2msp php bin/magento setup:upgrade
Option 2: Do a complete uninstall This includes removing database entries and configuration.
bin/magento module:uninstall MultiSafepay_Connect --remove-data --clear-static-content php bin/magento setup:upgrade
Backups You can back up certain parts of the plugin by adding the following parameters:
For information about all parameters, see Magento - Uninstall modules.
app/code 1. Disable the plugin:
php bin/magento module:disable --clear-static-content php bin/magento setup:upgrade
2. To remove the code base, delete the app/code/MultiSafepay/Connect directory:
cd app/code/MultiSafepay rm -rf Connect
Marketplace If you installed the plugin via the Magento Marketplace in your Magento backend, to delete the plugin, go to System > Web setup wizard > Extension manager > Update / uninstall.
Changes to refunds and shipping
Make sure you finish processing all orders created in the deprecated plugin before you delete it. The deprecated payment gateways are no longer available in Magento after deletion.
Note: After deleting the deprecated plugin, shipment requests for orders created in it are not automatically sent to MultiSafepay. You must set the order status to Shipped manually in your MultiSafepay account.
Changes to configuration fields
Under General settings, we have changed the following configuration fields from the deprecated plugin.
If you want one of these features back, email the Integration Team at [email protected]
Emailing invoices to customers
This feature is still supported in the new plugin, but it now uses the following Magento core configuration field: Sales > Sales emails > Invoice > Enabled.
We have removed the following Order status fields:
All MultiSafepay statuses now set the order to the default Canceled status via the offline action.
Create payment link
We have removed this field. Payment links are now generated automatically. See Retrieving payment links.
We have removed this field. When creating an order in the Magento 2 backend, you can now select the MultiSafepay payment gateway instead. The payment gateway displays all active payment gateways to the customer based on the website settings in your MultiSafepay account.
To enable or disable the gateway on your checkout page, we have added the Can use checkout configuration field.
Keep cart alive
We have removed this field. Now the cart is always kept alive when the customer clicks the back button on the MultiSafepay payment page.
Changes to order status flow
We have updated the order status flow from version 2.5.0:
Changes to the checkout
For the following payment methods, we have changed the default payment flow from redirect to direct:
We have included extra fields in the checkout for these payment methods. If you use a custom checkout, you must account for the iDEAL issuers checkout field and the new checkout fields for these payment methods.
Alternatively, you can disable additional checkout fields for these payment methods and change the flow back to redirect. Go to Stores > Configuration > MultiSafepay > Payment gateways > Gateway > Additional checkout fields.
This example shows the differences between the Luma checkout for Afterpay in the deprecated plugin and the new one
Payment page in the deprecated plugin:
From version 1.9.0 and higher, all order totals, including custom ones, are automatically read and displayed on MultiSafepay payment pages.
We read **all **custom totals in the cart. Sometimes this results in unwanted custom totals appearing on payment pages.
To exclude custom totals from payment pages, follow these steps:
If you have included a custom total and it is not being read, make sure that it implements the following methods:
The base values are required if you have enabled the
use base currency setting under MultiSafepay > General settings.
To process refunds from your Magento 2 backend, follow these steps:
Deprecated plugin You can refund orders for payment methods from the deprecated plugin in your MultiSafepay account, but not from your Magento 2 backend.
Second Chance emails are sent 1 hour and 24 hours after the order was created. By default, the status of Magento 2 orders changes from Pending payment to Cancelled after 8 hours (480 minutes).
If the customer pays via the second email (24 hours later), the payment is processed but the transaction update may not be handled correctly in Magento 2 because the order has expired. This may cause issues with external services (e.g. ERP/inventory management), if items are low in stock, or for one-off products like antiques.
To avoid this, you must match the order lifetime to the MultiSafepay payment link lifetime in your backend.
We recommend setting the lifetimes to 2 days (2880 minutes) to allow enough time for the customer to pay, but to avoid issues with external services.
The lifetime of orders marked as Pending payments in Magento 2 is determined by the Order Cron settings configuration. The default value is 480 minutes (8 hours).
For payment methods with a validation period longer than 8 hours, the status of orders in Magento 2 automatically changes to Canceled due to the default value. To fix this, increase the Order Cron settings value to longer than the validation period.
Setting pending payment order lifetimes
To set the lifetime of pending payments orders, see Magento - Pending payment order lifetime.
For ERP systems, if the order status is Declined, successful payments often fail to process for orders with Canceled status.
The lifetime of bank transfers is 86400 minutes (60 days).
The order status changes to Cancelled in Magento 2 before the payment can be linked.
For pay later payment methods, after you ship the order to the customer, you need to change the order status from Completed to Shipped. This prevents the order expiring, and lets the payment method initiate the billing process with the customer and pay the transaction out to your MultiSafepay balance.
If you change the order status to Shipped in your backend, the updated status is passed to your MultiSafepay account automatically.
Vue Storefront is not yet supported. The new plugin bases PWA integrations on GraphQL, which will only be supported by Vue Storefront when they release version 1.4.
MultiSafepay supports multiple checkouts:
Magento 2 core checkout
Our plugin works out of the box with the Magento 2 core checkout, which is based on the Luma theme.
MultiSafepay is an official partner of OneStepCheckout.com. Our plugin works with the latest version of the OneStepCheckout extension.
We have tested our plugin with the following checkouts:
Most Magento checkout plugins are compatible with our plugin, but we cannot guarantee that all features will function properly.
For questions or support, email the Integration Team at [email protected]