MultiSafepay plugin for WooCommerce

This technical manual is for installing and configuring the MultiSafepay plugin for WooCommerce. WooCommerce is a free, open-source ecommerce platform for Wordpress.

Test environment

We recommend first installing the plugin in a test environment following the recommended WooCommerce installation procedure. Make sure you have made a backup.


Contact us:

  • Telephone: +31 (0)20 8500 500
  • Email: [email protected]
  • GitHub: Create a technical issue



There are two ways to install the plugin:

Manual installation

  1. Click the Download button above.
  2. Sign in to your WooCommerce backend.
  3. Go to Plugins > Add new.
  4. Click Browse file.
  5. Upload the file.

Wordpress installation

  1. Sign in to your WooCommerce backend.
  2. Go to Plugins > Add new.
  3. Search for MultiSafepay.
  4. For the MultiSafepay plugin for WooCommerce, click the Install now button.


  1. Sign in to your WooCommerce backend.
  2. Go to WooCommerce > MultiSafepay Settings
  3. On the Account tab, enter your API key. For where to find your API key, see API key.
  4. On the Order status tab, confirm the match between WooCommerce order statuses and MultiSafepay order statuses, and then click Save changes.
  5. On the Options tab, confirm your settings, and then click Save changes.
  6. On the WooCommerce > Settings > Payments. Enable the relevant payment methods and confirm the settings.

User guide

Allowing notifications

Notifications are webhooks our API uses to notify your server when the status of a transaction changes. They are triggered by actions like:

  • Customers completing a payment
  • Merchants processing a refund

From WooCommerce version 4.7.0, notifications via POST requests, instead of GET requests.

However, sometimes the REST endpoint used to process notifications may be blocked by a firewall at server level or by some WordPress plugins at application level. In this case, ensure you include MultiSafepay requests on your safelist.

For more information, see Notification URL.

Applying surcharges

You can apply surcharges or payment fees with the WooCommerce plugin when combined with a relevant third-party package. The package must follow WooCommerce and Wordpress development guidelines.

The Integration Team will do their best to help you install third-party packages, but 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 WooCommerce plugin supports a generic gateway for all payment methods.

To configure the generic gateway, follow these steps:

  1. Sign in to your WooCommerce backend.
  2. Go to Settings > Payments tab. All payment methods are listed here.
  3. Select Generic gateway and set:
    • Gateway code
    • Gateway logo
    • Gateway label
    • For pay later methods, whether to include the shopping cart in refunds (required)
  • You can filter the generic gateway by:

    • Country
    • Minimum amount
    • Maximum amount
  • You can also set a custom initial order status.

  • Full refunds, partial refunds (except for pay later methods), and backend orders are fully supported.

Enabling recurring payments

You need to enable recurring payments in your MultiSafepay account and then in the plugin settings.

Modifying order requests

To change something in the OrderRequest before the transaction is processed, use the multisafepay_order_request filter hook in our plugin.

First, read the following:


Example of how to implement and overwrite the shopping cart:

add_filter('multisafepay_order_request', 'return_my_multisafepay_order_request');
function return_my_own_locale( \MultiSafepay\Api\Transactions\OrderRequest $order_request) {
    // Your conditions and logic to return a valid order request
    // Register a CartItem
    $shopping_cart_items = array();
    $cart_item = new \MultiSafepay\ValueObject\CartItem();
    $cart_item->addName( 'The product name' )
              ->addQuantity( (int) 1 )
              ->addMerchantItemId( (string) 'SKU' )
              ->addUnitPrice( \MultiSafepay\WooCommerce\Utils\MoneyUtil::create_money( (float) 10.00, (string) 'EUR' ) )
              ->addTaxRate( '21' );
    $shopping_cart_items[] = $cart_item;
    // Register the CartItem in the ShoppingCart     
    $shopping_cart = new MultiSafepay\Api\Transactions\OrderRequest\Arguments\ShoppingCart($shopping_cart_items);
    // Overwrite the ShoppingCart    
    $order_request->addShoppingCart( $shopping_cart );
    // Overwrite the total amount of the transaction
    $order_request->addMoney(\MultiSafepay\WooCommerce\Utils\MoneyUtil::create_money( 12.10, 'EUR' ));
    return $order_request;
Processing refunds

You can process full and partial refunds for all payment methods, except pay later methods for which you can only process full refunds.

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 informs the payment method that they can invoice the customer and transfer the funds to MultiSafepay.

If you change the order status to Shipped in your backend, the updated status is passed to your MultiSafepay account automatically.

Specifying customer language

MultiSafepay supports payment pages and messages to customers (e.g. Second Chance emails, links, order confirmations) in several languages.

However, WooCommerce only supports the language of your ecommerce platform, irrespective of the customer’s language or country, or the language of the webshop (if you use a third-party plugin for a multi-lingual webshop).

Our plugin sets the language for payment pages and messages based on the locale code get_locale() - a Wordpress function.

To change this behavior, use the multisafepay_customer_locale filter hook in our plugin.

Ask your developer to read:

Example implementation:

add_filter('multisafepay_customer_locale', 'return_my_own_locale');
function return_my_own_locale($locale) {
  // Your conditions and logic to return a valid locale code
  return $custom_locale;
Updating the plugin

There are 3 ways to update the plugin:

  • In your backend
  • In the CMS marketplace
  • Using SFTP

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. From the WooCommerce manual, download the plugin again.
  3. Follow the Installation and configuration instructions from step 2.
Using the credit card gateway

The credit card number field automatically detects the type of card (e.g. Visa) as the customer enters their card number.


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.