MultiSafepay plugin for WooCommerce

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


Contact us:

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



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

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

Activating Payment Components

The MultiSafepay WooCommerce 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 a request to activate them to [email protected]

Activating the payment component

To activate the payment component in your Wordpress - WooCommerce backend, follow these steps:

  1. Sign in to your Wordpress backend.
  2. Go to WooCommerce > MultiSafepay settings > Payment methods > Credit card, and then click Manage.
  3. Select the Payment components checkbox.
  4. Click Save changes.

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.

Allowing notifications

MultiSafepay uses a webhook to send you updates about orders and other notifications.

The webhook is triggered when the order or transaction status changes, e.g. when:

  • A customer completes payment.
  • A customer’s attempt to pay fails.
  • You process a refund.

From WooCommerce version 4.7.0, notifications are sent 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 allow list.

For more information, see Webhook.

Applying surcharges
Attention Dutch merchants
We strongly recommend that you do not apply 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).

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 offers a generic gateway that supports all payment methods.

You can:

  • Filter the generic gateway by country, and minimum and maximum amount.
  • Set a custom initial order status.
  • Process full and partial refunds (except for pay later methods), and backend orders.

To configure a generic gateway:

  1. Sign in to your backend.
  2. Go to Settings > Payments tab > Generic gateway.
  3. Set the relevant payment method gateway IDs, and the gateway logo and label.
  4. For pay later methods, include the shopping cart in refunds.
Enabling recurring payments

You need to enable recurring payments in your MultiSafepay dashboard 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 dashboard 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 WordPress Developer Resources - Filters in Wordpress.  

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.