MultiSafepay plugin for Magento 2

This technical manual is for installing and configuring our new free plugin for integrating MultiSafepay payment solutions into your Magento 2 webshop.

If you are still using the deprecated plugin, we recommend migrating to this new version as soon as possible.

  • MultiSafepay account – See Getting started.
  • Magento Open Source version 2.3.x & 2.4.x or Adobe Commerce version 2.3.x & 2.4.x (For GraphQL, only Magento Open Source versions 2.4.x are supported)
  • PHP 7.1+


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 [email protected]

New features

  • Improved:
    • Magento backend configuration
    • Translations
    • Error handling
    • Event and error logs
  • Support information available in the Magento backend
  • Clear explanation of each payment method with links to docs
  • Modular setup, providing more installation flexibility
  • PWA (GraphQL) endpoints

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.

Obsolete features

Features that are no longer available:

  • Recurring Payments – replaced by Magento Vault and Instant Purchase
  • FastCheckout – no longer supported


Contact us:

Our plugin is supported by a certified Magento 2 Solution Specialist and receives regular updates for the latest features from Magento and MultiSafepay.


View modules

The plugin consists of several Magento modules:

Module Description
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

View module dependencies

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_`

Stock handling

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:

  • General information: Contains all the main support information. We recommend reading this first.
  • General settings: Contains all main settings.
    • Here you can configure all gateways and gift cards.
    • For finding your account ID, site ID, site secure code, or API key, see Get your API key.
    • Your account ID appears in the top-right corner of your MultiSafepay dashboard.
  • Payment methods: Contains the configuration options for all MultiSafepay payment methods.
  • Gift cards: Contains the configuration options for all gift cards supported by MultiSafepay.
MultiSafepay is an official partner of

User guide

Deprecated Magento 2 plugin user guide
Downloading logs

To download MultiSafepay logs:

  1. Sign in to your Magento backend.
  2. Go to Stores > Configuration > MultiSafepay > General settings > MultiSafepay payment logs.
  3. Click Download.

You receive a ZIP package containing a system report file and any MultiSafepay log(s) stored in the /var/log directory.

Updating the plugin

You can update the plugin via Composer.

To update the plugin in your backend, follow these steps:

  1. Make sure you have a backup of your production environment, and that you test the plugin in a staging environment.
  2. Sign in to your Magento 2 backend.
  3. Run the following commands via the CLI:
composer update multisafepay/magento2 --with-all-dependencies
php bin/magento setup:upgrade
php bin/magento setup:di:compile
  1. Depending on your webserver/webshop configuration, you may also need to:

    • Check the ‘rights’ on files are correct. For the MultiSafepay files, see vendor/multisafepay.
    • Empty static files when running in production mode.
    • Clear your cache.
Activating Payment Components

The MultiSafepay Magento 2 plugin supports Payment Components, which:

  • Provide a seamless checkout experience to increase conversion.
  • Encrypt customer payment details for secure processing.
  • Shift responsibility for PCI DSS compliance to MultiSafepay.

If you’re new to accepting credit card payments, email a request to activate them to [email protected]

Activating the payment component

To activate the payment component in your Magento 2 backend, follow these steps:

  1. Sign in to your Magento 2 backend.
  2. Go to Configuration > Credit card, and then click Configure.
  3. Click Payment type and select Credit card component.
  4. Click Save config.

For questions, email [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
Attention Dutch merchants
We strongly recommend that you do not apply surcharges to pay later methods. This is now considered providing credit under the Wet op het consumentenkrediet and article 7:57 of the Burgerlijk Wetboek, and requires a permit from the Authority for Financial Markets (AFM).

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.

You can refund orders with a Fooman surcharge applied in your MultiSafepay dashboard, but not from your Magento 2 backend.


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.

Configuring generic gateways

The Magento 2 plugin supports generic gateways. You can filter generic gateways by country, and minimum and maximum amount.

To configure a generic gateway:

  1. Sign in to your backend.
  2. Go to Stores > Configuration > MultiSafepay > Payment methods > Generic gateway.
  3. Set the relevant payment method gateway IDs and upload a custom gateway image.
  4. For pay later methods, specify whether to include a shopping cart.

For support, email [email protected]

Configuring tax settings

Configuring Magento tax settings

To configure tax settings in Magento, go to Stores > Configuration > Sales > Tax > Calculation 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:

  • Tax calculation method based on: Row total
  • Catalog prices: Excluding tax
  • Apply customer tax: After discount
  • Apply discount on prices: Excluding tax

To show prices including tax, use the following settings:

  • Tax calculation method based on: Row total
  • Catalog prices: Including tax
  • Apply customer tax: After discount
  • Apply discount on prices: Including tax

These recommended settings are based on Magento’s standards. For more information, see Magento – Warning messages.

Deleting the deprecated plugin

The way you delete the deprecated plugin depends on the way you installed it:


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


You can back up certain parts of the plugin by adding the following parameters:

  • --backup-code
  • --backup-media
  • --backup-db

For information about all parameters, see Magento - Uninstall modules.


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


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.

Features of latest release

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.

You can refund transactions processed through the deprecated plugin in your MultiSafepay dashboard, but not from your Magento 2 backend.

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 dashboard.

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 [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.

Order status

As of version 2.16, the following MultiSafepay statuses can be assigned to a Magento order status:

  • Cancelled
  • Chargeback
  • Declined
  • Expired
  • Initialized
  • Partial refunded
  • Refunded
  • Reserved
  • Uncleared
  • Void

Order status flow

We have updated the order status flow from version 2.5.0:

  • All new orders first receive Pending status.
  • When redirecting the customer, the status changes to Pending payment, until the customer reaches the ‘Thank you’ page.
  • If the payment is succesfully received at this point, the status changes to Processing.
  • Around the same time, the offline action is triggered and the invoice is created. The offline action sets the status to Processing if it isn’t already.
  • For bank transfer payment methods, the status doesn’t change to Pending payment, therefore the order isn’t automatically cancelled after a set period of time to give the customer more time to pay.

We have removed this field. Payment links are now generated automatically. See Retrieving payment links.

Reset gateway

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.


For the following payment methods, we have changed the default payment flow from redirect to direct:

  • Afterpay
  • Request to Pay
  • Direct Debit
  • E-Invoicing
  • in3
  • Pay After Delivery (Betaal na Ontvangst)

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

Deprecated plugin:

Payment page in the deprecated plugin:

New plugin:

Integrating with PWA stores

Our Magento 2 plugin is compatible with GraphQL queries and can be integrated into PWA stores using an additional GraphQL support module.

We also offer full extensions for ScandiPWA and Vue Storefront.

Order totals on MultiSafepay payment pages

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:

  1. Sign in to your Magento 2 backend.
  2. Go to Stores > Configuration > MultiSafepay.
  3. Select General settings > Advanced settings > Exclude custom totals.

If you have included a custom total and it is not being read, make sure that it implements the following methods:

  • getCode()
  • getTitle() or getLabel()
  • getValue() or getAmount() and getBaseAmount()
  • getTaxRate() or getBaseTaxRate()
  • getTaxAmount() or getBaseTaxAmount()

The base values are required if you have enabled the use base currency setting under MultiSafepay > General settings.

Processing refunds

Refund rules

  • From your MultiSafepay dashboard: Full and partial refunds
  • From your Magento 2 backend (see below):
    • Full and partial refunds, and credit memos
    • Refunding more than the original transaction is not supported
  • API:
    • Refund order > Pay later refund
    • PATCH requests are not supported

To process refunds from your Magento 2 backend, follow these steps:

  1. Sign in to your Magento 2 backend.
  2. On the Invoices tab, click the invoice created by MultiSafepay, and then click Credit memo.
  3. Click the relevant refund button:
    • Offline refund: Doesn’t send a refund request to MultiSafepay.
    • Refund: Sends a refund request to MultiSafepay.

Deprecated plugin

You can refund orders for payment methods from the deprecated plugin in your MultiSafepay dashboard, but not from your Magento 2 backend.

Fooman surcharges

You can refund orders with a Fooman surcharge applied in your MultiSafepay dashboard, but not from your Magento 2 backend.

Setting order lifetimes for Second Chance

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.

Setting the Magento 2 order lifetime

  1. Sign in to your backend.
  2. Go to Stores > Configuration > Sales > Sales > Orders cron settings.
  3. Select Pending payment order lifetime (minutes) and set to 2880 minutes.
  1. From your Magento 2 admin panel, go to Stores > Configuration > MultiSafepay > Payment gateways.
  2. Select the relevant gateway, and then go to Custom payment link lifetime.
  3. Select Pending payment order lifetime and set to 2880 minutes.
Setting pending payment order lifetimes

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.

ERP systems

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.

Shipping orders

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 dashboard automatically.

Supported checkouts

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 Our plugin works with the latest version of the OneStepCheckout extension.

Note: Always test OneStepCheckout before use to make sure it is compatible with your specific configuration of the plugin.


Our plugin is compatible with Hyvä’s themes and checkout.

Other checkouts

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]

Using Magento Vault for Instant Purchase

Magento Vault enables you to use Instant Purchase, a feature that helps make repeat payments faster and easier, increasing conversion.

How it works

  1. After filling out their credit card number, CVC, and expiry date at checkout, customers can give permission to store these details for future payments.
  2. MultiSafepay encrypts the sensitive payment details and stores the encrypted version on our secure, GDPR compliant servers.
  3. We return a non-sensitive identifier for the payment details, known as a token, which can only be used in your Magento webshop.
  4. The token is automatically stored in your Magento Vault.
  5. For subsequent payments, the customer can simply click Instant purchase at checkout. They don’t need to re-provide any details.

To see Instant Purchase in action, see Magento – Instant purchase.

Requirements set by Mastercard and Visa

You must:

  • Include a checkbox at checkout for customers to give permission to tokenize their payment details (provided as standard by Magento Vault).
  • Explain in your terms and conditions how you use and store their details.
  • Inform customers how they can delete stored payment details.

Activating Magento Vault

To activate Magento Vault, email a request to enable recurring payments to [email protected]

Vault security

If you host Magento yourself, the security of the vault depends on the security of your server.

However, the vault only contains tokens valid in your webshop. If your server is compromised, no actual payment details are at risk, only stored customer data.


Propose a change on GitHubexternal-link-icon or
send an email to [email protected]

Other languages

For an explanation in another language, contact your account manager.

MultiSafepay is a proud member of ExtDNexternal-link-icon.