Magento 2 plugin


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

This technical manual is for installing and configuring MultiSafepay’s free plugin for integrating with Magento 2.

Requirements

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

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

Magento 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

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

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 enabled MSI in Magento 2, to disable the MultiSafepay CatalogInventory module, run:

php bin/magento module:disable MultiSafepay_ConnectCatalogInventory

Configuration

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

Checkouts

The plugin is compatible with most Magento checkouts.

Supported checkouts

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.

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

Generic gateways

The plugin supports generic gateways, which redirect customers from your checkout to a MultiSafepay payment page. You can use them to integrate custom gift cards, or co-branded credit cards.

Configuring 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 pay later methods, specify whether to include a shopping cart.

Generic gateways support:

Gift cards

Generic gateways are particularly useful for integrating gift cards, including custom gift cards. This is because we don’t support all open-loop gift cards in our ready-made integrations and no closed-loop gift cards.

Co-branded credit cards

You can integrate Visa co-branded credit cards (Cartes Bancaires, Dankort, and V Pay), using the generic VISA gateway.

For the logo, see MultiSafepay GitHub – MultiSafepay icons.

Logs

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

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.

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.

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.

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.

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

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.
Activating the payment component in your backend

  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.

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

Payment methods

Supported payment methods

  • Cards: All
  • Banking methods: All
  • Pay later methods: 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.

Refunds

Refund rules

MultiSafepay dashboard - Full and partial refunds
- Orders with Fooman surcharges
- Orders from the deprecated plugin
Backend - Full and partial refunds, and credit memos
- You can’t refund more than the original amount in your backend
API - See Refund order > Pay later refund
- PATCH requests not supported

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

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 Setting order lifetimes above.

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

Shipping orders

When you ship pay later 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.

Surcharges

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

Using Fooman for surcharges

To apply a surcharge or payment fee to a payment method, you can use the third-party Fooman package.

Refunds

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

Pay later methods

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

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.

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.

Updates

You can also update the plugin via Composer or in your Magento 2 backend.

Backend updates

  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.

Upgrading

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.

Checkout

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.

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

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

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

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.