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

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

Features

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]

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
  • PWA (REST) endpoints – replaced by GraphQL endpoints

Support

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.

Modules

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.

Installation

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

Configuration

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 account.
  • 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 OneStepCheckout.com.

User guide

Deprecated Magento 2 plugin user guide
Downloading logs

You can download MultiSafepay logs via the configuration backend.

  1. Go to Stores > Configuration > MultiSafepay > General settings > MultiSafepay payment logs.
  2. To generate and download the logs, 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 Magento Vault

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

You must:

  • Ask customers when entering their card details to check a checkbox to give permission to store the payment details for future purchases.
  • Add information to your terms and conditions about how you will use and store this data.
  • Inform customers how they can delete saved payment details.

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]

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

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

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 account, but not from your Magento 2 backend.

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.

Configuring generic gateways

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:

  1. Sign in to your Magento 2 backend.
  2. Go to Stores > Configuration > MultiSafepay > Payment methods > Generic gateway.
  • Enter the gateway code and upload a custom gateway image.
  • Specify if the gateway requires a shopping cart or not.

For any questions about integrating generic gateways, email the Integration Team at [email protected]

Configuring tax settings

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:

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

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:

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

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.

Features of latest release

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.

You can refund transactions processed through the deprecated plugin in your MultiSafepay account, 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 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.

Order status

We have removed the following Order status fields:

  • Declined
  • Canceled
  • Expired
  • Chargeback

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.

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.

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

Changes to the checkout

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.

Example
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. For more information, see PWA integrations.

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 account: 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:

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 account, but not from your Magento 2 backend.

Fooman surcharges You can refund orders with a Fooman surcharge applied in your MultiSafepay account, 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 account automatically.

Support for Vue Storefront

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.

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.

OneStepCheckout.com
MultiSafepay is an official partner of OneStepCheckout.com. 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.

Hyvä
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]

Feedback

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.