The plugin consists of several Magento modules:

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: We recommend testing compatibility with your configuration.

For support, email [email protected]

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.

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.

6. Click Save Config.

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.

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.

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.

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.

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.

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

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.

For instructions, see Magento – Pending payment order lifetime .

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.

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.

To get a payment link for a customer, follow these steps:

1. Sign in to your Magento 2 backend.
2. Go to Sales > Orders > Create new order, and then create an order.
3. Go to the Orders overview, and then select the newly created order.
4. Go to Comments history.
5. Under Notes for this order, copy the payment link.
6. Send the payment link to the customer.

1. Sign in to your Magento 2 backend.
2. Go to Marketing > Email templates.
3. Under New order, import a template.
4. 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}}

1. Go to Stores > Configuration > Sales > Sales emails.
2. Replace the New order confirmation template with your template.
3. Test the template to confirm it is working.

  💡 Tip! You can also implement this directly in the email template files.

• 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

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

2. Add is_online parameter to the JSON body:

"is_online": true

1. Sign in to your Magento 2 backend.
2. Go to Stores > Configuration > MultiSafepay > Payment gateways, and select the relevant gateway.
3. Go to Custom payment link lifetime, select Pending payment order lifetime, and set to 2880 minutes.

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.

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 .

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.

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:

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