Magento 2

Technical manual for MultiSafepay's free plugin.


Action required

If you are still using the deprecated plugin, we recommend upgrading to the latest version as soon as possible.

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


  • MultiSafepay account
  • 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+


Magento modules

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


  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 modules, run 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 by running:

php bin/magento module:disable MultiSafepay_ConnectMSI

If you have a Magento 2 environment with MSI disabled, to enable the MultiSafepay CatalogInventory module instead, run:

php bin/magento module:enable MultiSafepay_ConnectCatalogInventory


  1. Sign in to your Magento 2 backend.

  2. Go to Stores > Configuration > MultiSafepay.

    Specific settings
    • 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.
    • Enter your site API key.
    • Payment methods: Contains the configuration options for all MultiSafepay payment methods.
      • Make sure you have activated your selected payment methods in your MultiSafepay dashboard.
    • Gift cards: Contains the configuration options for all gift cards supported by MultiSafepay.
      • Make sure you have activated your selected gift cards in your MultiSafepay dashboard.
      • For more information, see Gift cards.

User guide


The plugin is compatible with most Magento checkouts.

Supported checkouts
Checkout Module
Amasty One Step Checkout By default, Amasty One Step checkout is supported.
Hyvä React checkout Hyvä checkout module
MagePlaza One Step checkout By default, MagePlaza One Step checkout is supported.
Hyvä Megawire checkout Megawire checkout module By default, is supported.

**Note** We recommend testing compatibility with your configuration.

For support, email [email protected]

Custom totals

From version 1.9.0 and higher, all order totals from shopping cards are automatically read and displayed on MultiSafepay payment pages.

Sometimes this results in unwanted custom totals appearing on payment pages.

How to exclude custom totals from payment pages
  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 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.

Custom URLs

How to set up custom URLs
  1. Sign in to your Magento 2 backend.
  2. Go to Stores > Configuration > MultiSafepay.
  3. Select General settings > Advanced settings.
  4. In the Use custom return urls field, select Yes.
  5. Enter your custom URL in either:
  • The Custom redirect url after canceling the payment field, or
  • The Custom "Success page" url field.
  1. Click Save Config.

Generic gateways

The plugin supports generic gateways, which allows you to add a payment method manually. This is particularly useful for integrating gift cards specific to your business.

Supported since release: 2.4.0, February 22nd 2021.

How to configure generic gateways
  1. Sign in to your Magento 2 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 BNPL orders, specify whether to include a shopping cart.


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

Magento Vault and Instant Purchase

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

How it works
  1. After filling out their 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.
Mastercard and Visa requirements

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.
How to activate Magento Vault
To activate Magento Vault, and enable [recurring payments](/docs/recurring-payments/), email a request to
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.

Manual Capture

The Magento 2 integration supports Manual Capture from version 3.7.0 and up.

How to use manual capture in magento
It has been implemented for the following supported payment gateways:
  • Card payments
  • Maestro
  • Mastercard
  • Visa

For more information about Manual capture and how to enable it for your MultiSafepay account, please check our Manual capture instructions.

To enable Manual capture in your Magento environment:

  1. Go to Stores > Configuration > MultiSafepay > Payment Gateways
  2. Select a supported payment gateway, e.g. 'Card Payment'
  3. Select Enable Manual Capture > Yes

Please note that the full shipping amount will be captured whenever the first shipment has been made, even if it was just a partial shipment of the items. If the rest of the items in the order will not be shipped anymore, you can initiate a refund for the shipment costs of those items.

Order lifetimes

The default lifetime of Pending payment orders in Magento 2 is 480 minutes (8 hours). For payment methods with a longer authorization period, the order status changes to Cancelled after 8 hours.

How to extend order lifetimes
To extend the lifetime of pending payments orders, increase the **Order Cron settings** value to longer than the validation period.

For instructions, see Magento – Pending payment order lifetime .

Order requests

How to modify order requests

To modify an OrderRequest before a transaction is processed, create an observer based on the before_send_multisafepay_order_request event in the plugin.

For an example, see MultiSafepay GitHub – Magento 2 example module.

ERP systems

For ERP systems, if the order status is Declined, successful payments often fail to process for orders with Cancelled status.

The lifetime of bank transfers is 86400 minutes (60 days).

The order status in Magento 2 changes to Cancelled before the payment can be matched to the order.

Payment components

The 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.
How to activate the payment component in your backend
  1. Sign in to your Magento 2 backend.
  2. Go to Stores > Configuration > MultiSafepay > Payment Gateways.
  3. Select the relevant payment methods and then click Configure.
  4. Click Payment type and select Card payment component.
  5. Click Save config.

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

Payment links

From version 2.0 and higher, payment links are automatically generated for every order.

Payment methods

Supported payment methods
  • Cards: All
  • Banking methods: All
  • BNPL: All
  • Wallets: All
  • Prepaid cards:
    • Baby gift card
    • Beauty and Wellness gift card
    • Boekenbon
    • Edenred
    • Fashioncheque
    • Fashion gift card
    • Fietsenbon
    • Gezondheidsbon
    • Givacard
    • Good4fun
    • Goodcard
    • Nationale tuinbon
    • Paysafecard
    • Parfumcadeaukaart
    • Podium
    • Sport en Fit
    • VVV gift card
    • Webshop gift card
    • Wellness gift card
    • Wijncadeau
    • Winkelcheque
    • Yourgift

Progressive web apps

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


Refund rules
PlatformSupported refunds
MultiSafepay dashboardFull and partial refunds
Orders with Fooman surcharges
Orders from the deprecated plugin
Note: Credit memos are not generated
BackendFull and partial refunds, and credit memos
You can't refund more than the original amount in your backend
APISee Refund order > BNPL refund
PATCH requests not supported
How to process refunds

To process backend refunds:

  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.

To process refunds via the REST API:

  1. Use the following endpoint in your request:
POST V1/invoice/:invoiceId/refund

For more information, see Magento REST API - Refunds

  1. Add is_online parameter to the JSON body:
"is_online": true

Second Chance

Second Chance emails are sent 1 hour and 24 hours after orders are created. By default, the order status 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, match the order lifetime to the payment link lifetime.

See Order lifetimes above.

✅   Tip! We recommend setting order lifetimes to 2 days (2880 minutes) to allow enough time for the customer to pay, but avoid issues with external services.


When you ship BNPL orders, you need to change the order status from Completed to Shipped. This prevents the order expiring and triggers invoicing.

If you do so in your Magento 2 backend, the updated status is passed to your MultiSafepay dashboard automatically.


The plugin does not support surcharges, but you can use third-party service Fooman to apply them.

How to use Fooman for surcharges

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.

BNPL orders

For Dutch merchants, We strongly recommend not applying surcharges to BNPL orders. 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).


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.

Tax settings

How to configure 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:

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


You can update the plugin via Composer .

How to update
  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
  4. 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.


If you are still using the deprecated plugin , we recommend upgrading to the latest version as soon as possible.

Why upgrade?

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, including support information
    • Translations
    • Error handling, and event and error logs
  • Documentation for payment methods
  • Modular setup for greater installation flexibility
  • PWA (GraphQL) endpoints
  • Support for Magento Vault and Instant Purchase (replace recurring payments)

Configuration fields

We have removed or altered the following configuration fields:

Emailing invoices to customers

This feature now uses a Magento core configuration field: Sales > Sales emails > Invoice > Enabled.

Order statuses and flow

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

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

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 your success page.
  • If the payment is succesfully received at this point, the status changes to Processing.
  • Around the same time, the webhook is triggered and the invoice is created. The webhook changes the status to Processing (if it isn't already).
  • For bank transfers, 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.

Payment links

Payment links are now generated automatically.

Reset gateway

When creating an order in your 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 site settings in your MultiSafepay account.

To enable or disable the gateway on your checkout page, we have added a Can use checkout configuration field.

Keep cart alive

The cart is now always kept alive when the customer clicks Back on the MultiSafepay payment page.


We have changed the default payment flow from redirect to direct for:

  • AfterPay, E-Invoicing, in3, Pay After Delivery
  • Direct Debit, Request to Pay

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.

How to delete the deprecated plugin

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.

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 .
If you want a field from the deprecated plugin back, email [email protected]


  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, go to System > Web setup wizard > Extension manager > Update / uninstall.


How to troubleshoot Magento 2 issues

Order Status Update

If you experience issues with order statuses not being updated correctly (e.g., incongruence between pending and processing), this might happen randomly and be difficult to replicate. This is generally caused by third-party solutions interfering in the order processing flow and the observer being based on a different instance of the order object.

Tip: This issue might appear after upgrading to our latest plugin version, possibly due to faster notification processing times surfacing an already existing update conflict.

To debug this issue on your side:

  1. Set to debug mode.
  2. Use our Order Save Inspector to check which module might interfere (for example, delivery software, ERP).



Contact MultiSafepay:

Top of page