SolutionsSystem status
Documentation
Create accountContact
  1. Integrations
  2. Our integrations

Lightspeed

Technical manual for MultiSafepay's free app.

⚠️

Important — action required:

The "MultiSafepay Payments" Lightspeed app will be fully deprecated soon. To prevent payment disruption, migrate to the new "MultiSafepay" Lightspeed app. After the deadline, the legacy application may no longer process payments and support will be limited to migration assistance.

Migration steps

  1. In your Lightspeed Backoffice, go to Apps > Purchased apps.
  2. Open MultiSafepay Payments and click Cancel App.
  3. Confirm the cancellation by selecting App is no longer required and entering your password.
  4. Go to Apps > App Store and search for MultiSafepay (not MultiSafepay Payments).
  5. Click Install, accept the permissions, and complete the configuration by entering your email, API key, environment (Test/Live), and preferred payment methods.
🗨️

Support

Contact MultiSafepay:


Prerequisites

Installation

💡

Tip!

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

User guide

API keys and environments

You can change your website API key or environment (live or test) after installation.

How to change API keys and environments

1. Sign in to the app.
2. Tap the hamburger menu and go to Environment.
3. Edit your API key and/or the Environment.


Checkouts

This app is tested using the default 1-step and 1-page checkout using the default theme.

How to order payment methods in your checkout

To change the order in which payment methods appear on your checkout page, follow these steps:

  1. Go to Settings > Payment method settings.
  2. Drag and drop the payment methods to the preferred order.
  3. Click Save.

How to set the payment method order per language

To set the payment method order for different languages, under the Payment method settings select a country/store language and set the order per language.

If no specific rule is set for a country, the Default order is used.


Internationalization

When changing internationalization in your Lightspeed eCom backend, do not change the primary language setting while installing the app.

Lightspeed eCom requires a language, an API key, and a cluster to validate API requests.

If you remove the language used during installation instead of deactivating it, the app cannot communicate with Lightspeed eCom services.


Lightspeed shop ID

How to view your shop ID

To view your shop ID, follow these steps:

  1. Sign in to the /admin area of your Lightspeed app.
  2. Click Help in the bottom-left corner.
  3. A popup appears containing your shop ID (also known as the store ID).

Order amounts

You can modify maximum and minimum order amounts:

Per payment method

To set a maximum/minimum order amount for a payment method to display on your checkout page, follow these steps:

  1. In the Payment methods ordering list, click the gear icon next to the relevant payment method. This will open a modal with all the details for that payment method, where you can adjust the order amount and other settings.
  2. Enter an amount in EUR cents in the:
    • Maximum field, e.g. A maximum value of 15 EUR means the payment method only appears on the checkout page if the total order amount is less than 15 EUR. If you don't want a maximum amount, leave it empty.
      OR
    • Minimum field, e.g. A minimum value of 15 EUR means the payment method only appears on the checkout page if the total order amount is more than 15 EUR.

Per language

To set different maximum/minimum order amounts for different languages, under the Payment methods ordering header > Country list, select a country and set the maximum/minimum amount per language.

If no specific rule is set for a language, Default language is used.

⚠️

Note:

Set order amount limits within the permitted range for each payment method to avoid failures. See each payment method's page for its specific amount limits.


Payment components

MultiSafepay Lightspeed app 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.
⚠️

Note:

Payment Components are supported only with the Lightspeed Legacy Checkout, including its Multi-step, One-page, and One-step checkout variations. They are not supported with the new eCom checkoute limited to migration assistance.

How to activate the payment component in your backend
  1. Sign in to your Lightspeed app.
  2. Go to Apps > Purchased apps > MultiSafepay.
  3. Click Go to app.
  4. In the Setup page:
    • Enter your email address, account ID and website API key.
    • Select Test or Live environment, and then click Save and continue.
      You are redirected to the Settings page.
  1. On the Payment method settings section:
    • Select the relevant Payment method settings.
    • To expand the payment method, click on the gear icon to open payment method settings.
    • In the Payment component dropdown select the Enabled, close the modal.

  1. Click Save.

  2. Make sure that MultiSafepay checkout script is enabled in the Settings page

Tokenization (One-click payments)

When payment components are enabled, returning customers can pay using saved payment details.
On their first payment, the customer's credentials are securely encrypted and stored. On subsequent purchases, the customer can complete payment in one click without re-entering their details.


Payment links

When you generate a payment link in your MultiSafepay dashboard, you cannot update the transaction status or link it to a transaction in Lightspeed via our app. This is by design in Lightspeed.


Payment methods

By default, any payment method you activate in your MultiSafepay account will be available for your backend. Newly activated payment methods must be enabled manually in your backend settings.

To use MultiSafepay payment method icons, see GitHub MultiSafepay icons .

Payment methods logos in your website footer

By default, the app does not support adding payment methods logos to your website footer. We provide a script for this, or you can ask your developer to add the logos to your theme. Themes can differ and you may need to make some changes for it to function.

How to add logos via our script

How to add logos via our script

  1. Sign in to your Lightspeed app.
  2. Go to Apps > Purchased apps > MultiSafepay.
  3. Click Go to app.
  4. In the Setup page:
    • Enter your email address, account ID and website API key.
    • Select Test or Live environment, and then click Save and continue.
      You are redirected to the Settings page.

  1. On the Storefront payment icons section, click Copy code.

  2. In your Lightspeed admin area, go to Settings > Web extras and custom Javascript.

  3. Paste the script into the Javascript textbox, and set the status to Enable.

  4. Click Save.

    The logos appear in the footer.

Display order

Depending on the storefront, the display order of the logos is determined by the settings at the time of generation. If you update these settings, you must update the script as well.

Size

By default the logos are 16 px high. In most themes, footer logos are found in the "div.payment-methods p". If needed, you can change the selector based on the theme.

How to resize logos

  • In your JavaScript file, locate the following img element near the end of the script to display logos:

    <img src="${msplt[e]}" alt="${e}" />

  • Specify the height and width in pixels as required, e.g.:

    <img height="16" width="37" src="${msplt[e]}" alt="${e}" />
How to add missing logos

Logos may be missing due to your website theme settings.

To add missing payment method logos, follow these steps:

  1. Download the logos from our Github repo .
  2. Rename the file with upper case formatting, e.g applepay.png > APPLEPAY.png.
  3. Sign in to your Lightspeed app.
  4. Go to Design > Theme editor > Advanced > Edit code > Assets, and drop in the logos.

The logos won't appear instantly. It takes a little time.

JavaScript

For the best user experience, we provide some Javascript and images, e.g. to add a dropdown for iDEAL and MultiSafepay icons for other payment methods.

Some user-added themes or scripts may cause issues, e.g. missing images for payment methods.

For assistance, ask your developer.

All payment methods still work if you don't use the Javascript files.

How to order payment methods in your checkout

To change the order in which payment methods appear on your checkout page, follow these steps:

  1. Go to Settings > Payment method settings.
  2. Drag and drop the payment methods to the preferred order.
  3. Click Save.

Setting payment method order per language

To set the payment method order for different languages, under the Payment method settings select a country / store language and set the order per language.

If no specific rule is set for a country, the Default order is used.

How to enable payment methods

You can enable or disable all payment methods at once in the Payment Methods section by clicking the Enable all or Disable all buttons.
Additionally, each payment method includes its own toggle, allowing you to enable or disable it individually.

To disable payment methods for specific languages, follow these steps:

  1. Sign in to your Lightspeed app.
  2. Select the relevant storefont.
  3. For each language, disable the relevant payment methods.

If no specific language rule-set is found, Default is used.

Missing payment methods

By default, newly activated payment methods for your MultiSafepay account are disabled in the Lightspeed app's MultiSafepay settings. You need to enable them in both environments.

If a payment method is missing:

  1. Sign in to your MultiSafepay dashboard .
  2. Go to Settings > Payment methods, and check that the payment method is enabled.
  3. Sign in to your Lightspeed app, go to Settings, and then enable the payment method again.
How to remove payment methods

Payment methods may still appear in your checkout even after disabling them for your account. Follow the steps below to remove them.

Step 1: Ensure the payment method is enabled

  1. Sign in to your MultiSafepay dashboard .
  2. Go to Settings > Payment methods.
  3. Enable the payment method if it is not already enabled.

Step 2: Sync the change in Lightspeed

  1. Sign in to your Lightspeed app.
  2. Go to Apps > Purchased apps > MultiSafepay.
  3. Click Go to app.
  4. Select the relevant store view (if applicable).
  5. Toggle the payment method on, then off, and save your changes.

Step 3: Disable the payment method

  1. Return to your MultiSafepay dashboard.
  2. Disable the payment method under Settings > Payment methods.

Payment reminders

The Lightspeed app doesn't support Second Chance emails because Lightspeed orders expire after 12 hours.

Lightspeed offers a functionality that lets you configure payment reminders and emails for orders with Pending status. For more information and instructions, see Lightspeed – Configuring payment reminders .


Refunds

Full and partial refunds and credit notes are supported in your MultiSafepay dashboard and backend.
You can't refund more than the original amount in your backend.

How to enable refunds in your backend

  1. Sign in to your Lightspeed app.
  2. Go to Apps > Purchased apps > MultiSafepay.
  3. Click Go to app.
  4. In the Setup page:
    • Enter your email address, account ID and website API key.
    • Select Test or Live environment, and then click Save and continue.
      You are redirected to the Settings page.
  1. In the Refunds section:
    • Use Enable refunds to disable or enable refunds.
    • Under Refund trigger, choose when a refund is created in MultiSafepay:
      • Only create a refund when the credit invoice status is unpaid.
      • Always create a refund, regardless of the credit invoice status.
⚠️

Notes:

  • If you use Lightspeed eCom linked to Lightspeed Retail to process refunds via MultiSafepay, you must enable the Always create a refund, no matter the status setting.

  • When creating a credit memo, set the status to Not paid. If the Always create a refund, no matter the status setting is not enabled, MultiSafepay ignores Paid status.

Known issues

For refunds created in your Lightspeed backend, a short message appears in the Notes section of the order where any errors are explained.

  • Refunds created in your MultiSafepay dashboard are not reported back to Lightspeed. Under Notification history, an error appears: "Already a completed transaction".
  • Some BNPL orders:
    • Require product IDs for each refunded item. When using product variants, make sure each variant has a unique identifier. If you provide duplicate IDs, we cannot distinguish which items to refund.
    • Do not let you refund a partial amount and a full item in a single request, e.g. a shopping cart contains 3 items for a total of 1.70 EUR. If you refund 1 item and 0.40 EUR, it fails. Make sure you refund items and amounts separately.
  • You cannot issue multiple refunds for the same amount within 5 minutes of each other, even for different items.

Single sign-on

Lightspeed single sign-on lets you sign in to the app's Settings directly from the Lightspeed eCom store. You don't need to click or tap the Login button.

How to use Lightspeed single sign-on

  1. Sign in to the Admin section of your Lightspeed store.
  2. In the sidebar, click Apps.
  3. Click Purchased apps.
  4. In the sidebar, click Apps.
  5. Click MultiSafepay, or to take you straight to the store page, paste /admin/store/apps/1517 after the base URL of your store.
  6. On the store page, click Go to app / Ga naar app.

Shipping orders

When you ship BNPL orders, you need to change the order status from Completed to Shipped. This prevents the order expiring and triggers invoicing.


Surcharges

How to apply surcharges

  1. Sign in to your Lightspeed app.
  2. Go to App > Purchased app > MultiSafepay app.
  3. Select the payment method you want to apply a surcharge to.
  4. Enter the surcharge amount as a:
    • Fixed amount under Flat payment fee, or
    • Percentage under Dynamic payment fee.
  5. Click Save.
⚠️

Attention 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).


Updates

You don't need to manually update the app.


Upgrades

We recommend upgrading from our deprecated core integration to the Lightspeed app.

How to upgrade to the new app

1. In the Lightspeed app manual, follow the steps to install the app.
2. Place a test order to make sure it's working properly.
3. Open the core integration, and then disable the payment provider.

To access the MultiSafepay app Settings page:

  • You are automatically redirected after installing the app, or
  • Select the MultiSafepay app, and then click Go to app.

How to disable the core integration

  1. Sign in to your Lightspeed backend.
  2. Go to Settings > Payment providers > MultiSafepay.
  3. At the top of the screen, click Disable this payment provider.

Troubleshooting

Payment methods not displayed correctly

Checks you can do:

  • Are you using the correct API key and environment combination?
  • Are the payment methods activated for your account?
  • In Payment method settings, check that you have modified your preferences for the correct / all store languages. Check also: current setting is set to enabled.

💬

Support

Contact MultiSafepay: