Technical manual for MultiSafepay's free plugin.



✅   Tip! We recommend first installing the plugin in a test environment, following the WooCommerce installation procedure. Always make a backup.

There are two ways to install the plugin:

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 Install now.

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 Plugin_WooCommerce_x.x.x.zip file.


  1. Sign in to your WooCommerce backend.
  2. Go to WooCommerce > MultiSafepay settings
  3. On the Account tab, enter your 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. Go to WooCommerce > Settings > Payments.
  7. Enable the relevant payment methods and confirm the settings.

User guide

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: 4.5.0, March 31 2021.

How to configure generic gateways
  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 BNPL orders, include the shopping cart in refunds.

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 BNPL orders), and backend orders.


MultiSafepay payment pages and messages to customers (e.g. Second Chance emails, links, order confirmations) are supported 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).

How to change language

The plugin sets the language for payment pages and messages based on the Wordpress locale code get_locale() 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;


If you use the TranslatePress plugin for translations, to configure it for payment pages, follow these steps:

  1. Sign in to your WooCommerce backend.
  2. Go to Settings > TranslatePress > Advanced.
  3. Scroll down and click Exclude gettext string.
  4. In the Domain field, enter multisafepay.
  5. Click Add.


MultiSafepay webhook

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

The webhook is triggered when the order status 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.

Order requests

How to modify order requests

To change something in an OrderRequest before a transaction is processed, use the multisafepay_order_request filter hook in the 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;

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.
Supported payment methods
How to activate payment components
  1. Sign in to your Wordpress backend.
  2. Go to WooCommerce > MultiSafepay settings > Payment methods >
  3. Select the relevant payment methods, and click Manage.
  4. Select the checkbox for the Payment components.
  5. Click Save changes.

💬 Support: If you're new to accepting credit card payments, email a request to activate them to [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.

Payment links

Payment methods

Supported payment methods

Recurring payments

You need to activate recurring payments and then enable it in the plugin settings.

How to activate recurring payments
  1. Sign in to your Wordpress backend.
  2. Go to WooCommerce > MultiSafepay settings > Payment methods
  3. Select relevant credit cards, and then click Manage.
  4. Select the checkbox for Payment components and Tokezation.
  5. Click Save changes.

📘 Note: To activate recurring payments, ensure that the Payment component is enabled.


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

Shipping orders

For BNPL orders, after shipment, you must change the order status from Completed to Shipped. This prevents the order expiring and triggers invoicing.

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


You can apply surcharges in the plugin when combined with a relevant third-party package.


Attention Dutch merchants

We strongly recommend not applying surcharges to BNPL 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).

How to apply surcharges with third-party packages

Third-party packages 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.


You can update the plugin in your backend and the CMS marketplace, or via SFTP.

How to update in your backend

✅   Tip! Make sure you have a backup of your production environment, and that you test the plugin in a staging environment.

  1. Download the plugin again above.
  2. Follow the Installation and configuration instructions from step 2.



Contact MultiSafepay:

Top of page