Magento 2
Technical manual for MultiSafepay's free plugin.
Our plugin is supported by a certified Magento 2 Solution Specialist and receives regular updates for the latest features from Magento and MultiSafepay.
Prerequisites
- MultiSafepay account
- Magento Open Source version 2.3.6+ & 2.4.x or Adobe Commerce version 2.4.x (For GraphQL, only Magento Open Source versions 2.4.x are supported)
- PHP 7.2+
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 |
Multisafepay/hyva-checkout | Adds support for HyvƤ Checkout |
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
- 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
- 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
Configuration
-
Sign in to your Magento 2 backend.
-
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
Checkouts
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Ƥ Checkout | HyvƤ Checkout module |
OneStepCheckout.com | By default, OneStepCheckout.com 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
- Sign in to your Magento 2 backend.
- Go to Stores > Configuration > MultiSafepay.
- 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
- Sign in to your Magento 2 backend.
- Go to Stores > Configuration > MultiSafepay.
- Select General settings > Advanced settings.
- In the Use custom return urls field, select Yes.
- Enter your custom URL in either:
- The Custom redirect url after canceling the payment field, or
- The Custom "Success page" url field.
- 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
- Sign in to your Magento 2 backend.
- Go to Stores > Configuration > MultiSafepay > Payment methods > Generic gateway.
- Set the relevant payment method gateway IDs and upload a custom gateway image.
- For BNPL orders, specify whether to include a shopping cart.
Logs
How to download MultiSafepay logs
- Sign in to your Magento backend.
- Go to Stores > Configuration > MultiSafepay > General settings > MultiSafepay payment logs.
- 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
- After filling out their card number, CVC, and expiry date at checkout, customers can give permission to store these details for future payments.
- MultiSafepay encrypts the sensitive payment details and stores the encrypted version on our secure, GDPR compliant servers.
- We return a non-sensitive identifier for the payment details, known as a token, which can only be used in your Magento webshop.
- The token is automatically stored in your Magento Vault.
- 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 https://docs.multisafepay.com/docs/manual-capture#integration instructions.
To enable Manual capture in your Magento environment:
- Go to Stores > Configuration > MultiSafepay > Payment Gateways
- Select a supported payment gateway, e.g. 'Card Payment'
- 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
- Sign in to your Magento 2 backend.
- Go to Stores > Configuration > MultiSafepay > Payment Gateways.
- Select the relevant payment methods and then click Configure.
- Click Payment type and select Card payment component.
- 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.
How to fetch a payment link
To get a payment link for a customer, follow these steps:
- Sign in to your Magento 2 backend.
- Go to Sales > Orders > Create new order, and then create an order.
- Go to the Orders overview, and then select the newly created order.
- Go to Comments history.
- Under Notes for this order, copy the payment link.
- Send the payment link to the customer.
How to add payment links to order confirmation emails
- Sign in to your Magento 2 backend.
- Go to Marketing > Email templates.
- Under New order, import a template.
- Add the following code snippet to the template:
{{depend order.getPayment().getAdditionalInformation('payment_link')}}
<a href="{{var order.getPayment().getAdditionalInformation('payment_link')}}">Pay now with {{var order.getPayment().getAdditionalInformation('method_title')}}</a>
{{/depend}}
Backend emails
To add payment links to order confirmation emails from your Magento backend, you can use the payment_link
variable and an if/else
statement in the template.
Frontend emails
You cannot add payment links to order confirmation emails created in your frontend, but you can display the name of the payment method:
{{if payment_link}}
<a href="{{var payment_link}}">Pay now with {{var order.payment.additional_information.method_title}}</a>
{{else}}
<p>{{var order.payment.additional_information.method_title}}</p>
{{/if}}
- Go to Stores > Configuration > Sales > Sales emails.
- Replace the New order confirmation template with your template.
- Test the template to confirm it is working.
Ā š” Tip! You can also implement this directly in the email template files.
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.
Refunds
Refund rules
Platform | Supported refunds |
---|---|
MultiSafepay dashboard | Full and partial refunds Orders with Fooman surcharges Orders from the deprecated plugin ā ļø Note: Credit memos are not generated |
Backend | Full and partial refunds, and credit memos You can't refund more than the original amount in your backend |
API | See Refund order > BNPL refund PATCH requests not supported |
How to process refunds
To process backend refunds:
- Sign in to your Magento 2 backend.
- On the Invoices tab, click the invoice created by MultiSafepay, and then click Credit memo.
- 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:
- Use the following endpoint in your request:
POST V1/invoice/:invoiceId/refund
For more information, see Magento REST API - Refunds
- 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.
How to set payment link lifetimes
- Sign in to your Magento 2 backend.
- Go to Stores > Configuration > MultiSafepay > Payment gateways, and select the relevant gateway.
- Go to Custom payment link lifetime, select Pending payment order lifetime, and set to 2880 minutes.
Shipment
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.
Surcharges
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.
Refunds
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).
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
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 .
Updates
You can update the plugin via Composer .
How to update
- Make sure you have a backup of your production environment, and that you test the plugin in a staging environment.
- Sign in to your Magento 2 backend.
- 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
- 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.
Troubleshooting
How to troubleshoot Magento 2 issues
Order Status Update
If you experience issues with order statuses not being updated correctly (e.g., incongruent 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:
- Set to debug mode.
- Use our Order Save Inspector to check which module might interfere (for example, delivery software, ERP).
Support
Contact MultiSafepay:
- Telephone: +31 (0)20 8500 500
- Email: [email protected]
- GitHub: create a technical issue
Updated 17 days ago