The pos_multisafepay_cloud addon connects Odoo POS (Point of Sale) to a SmartPOS device with cloud mode enabled. It creates device payment requests, receives status notifications, supports cancellation and reversal flows, and processes full or partial refunds from Odoo POS.

This addon is independent of the e-commerce addons payment_multisafepay and payment_multisafepay_enhanced. Install those addons only when you also need MultiSafepay for online checkout or invoicing.

Prerequisites

• A MultiSafepay account.
• An activated SmartPOS device with cloud mode enabled. See how to set up your device.
• The terminal ID, terminal group ID, and terminal group API key provided for your terminal group in your LIVE account.
• Odoo 18.0 or 19.0 with the Point of Sale application installed.
• Python 3.9 or later.
• Administrator privileges to the Odoo instance.

Installation

The Cloud POS integration is provided by the pos_multisafepay_cloud addon in the official MultiSafepay Odoo repository.

Choose the installation method that matches your Odoo environment:

Self-hosted or Docker Odoo

Install the Python dependencies in the same Python environment used by Odoo:

pip install 'multisafepay==3.1.0' requests

1. Download a MultiSafepay Odoo release compatible with Odoo 18.0 or 19.0, or clone the 18.0 or 19.0 branch of the official repository.

2. Place the multisafepay directory in your custom addons location.

3. Make sure addons_path points to the directory that directly contains pos_multisafepay_cloud/:

   ini

   addons_path = /path/to/odoo/addons,/path/to/custom_addons/multisafepay

4. Restart Odoo:

   Bash

   # Docker
   docker compose restart odoo
   
   # Systemd
   sudo systemctl restart odoo

5. Sign in to the Odoo backend as an administrator.

6. Go to Apps and select Update Apps List.

7. Search for POS MultiSafepay Cloud and select Install.

Odoo.sh

1. Add the official MultiSafepay Odoo repository to the custom addons directory of your Odoo.sh project.
2. Make sure the directory that directly contains pos_multisafepay_cloud/ is included in addons_path.
3. Commit and push the changes. Wait for Odoo.sh to complete the build.
4. Sign in as an administrator and go to Apps > Update Apps List.
5. Search for POS MultiSafepay Cloud and select Install.

Configuration

Set up your device

Before connecting your SmartPOS device to Odoo:

1. Complete the initial device Hardware setup.
2. Activate your device in your MultiSafepay dashboard.
3. After your device is activated, enable the following features:
   • Cloud mode - Enables cloud mode on your device
   • Cancel Button - Adds a cancel button to the payment screen
   • Hide System Navigation - Disables your device's system navigation bar
4. In the MultiSafepay payment app home screen, access Cloud POS payments.

Payment requests sent to the device will display on its screen. To initiate payments, make sure the device screen is on.

Connect your SmartPOS device to Odoo

1. Sign in to the Odoo backend as an administrator.
2. Go to Point of Sale > Configuration > Payment Methods.
3. Click New to create a new Payment Method, or select an existing one from the list.
4. In the Payment Method creation screen, assign the following details:

   • Assign a Journal from the dropdown menu.

   • In the adjacent dropdown menus, select Terminal and choose MultiSafepay Cloud POS.

     Enter the your device credentials:

   • Terminal ID: The unique identifier of the device that receives the payment request.

   • Terminal group ID: The terminal group identifier that the device is linked to.

   • Terminal group API key: Authenticates API requests for that terminal group.

     How to retrieve your device credentials

     MultiSafepay dashboard MultiSafepay dashboard
5. Click Save manually.
6. Go to Configuration > Settings.
7. Next to Point of Sale, click the dropdown menu and select the Point of Sale you want to configure.
8. Under Payment, add your newly configured Payment Method.
9. Click Save.

Configure a separate Odoo Payment Method for each terminal ID and terminal group ID combination. Odoo rejects duplicate active configurations for the same device.

User guide

Process a payment

Before processing payments with Odoo POS, make sure that the MultiSafepay payment app is launched on your device. To initiate a payment:

1. Open a POS session configured with MultiSafepay Cloud POS.
2. Create the order and proceed to the payment screen.
3. Select the relevant Payment Method.
4. Click Send to initiate the payment.
5. Complete the payment on the device using a valid payment method.
6. Once the payment is completed, you are redirected to the completed screen, where the following payment details are displayed:
   • Item and number of units
   • Amount per unit and total amount
   • Payment Method name
   • Order ID

Once a payment is completed, a transaction is created and becomes available in both your Odoo backend and the Transactions section of your MultiSafepay dashboard.

You can access your completed orders:

Via your Odoo backend

1. Go to Orders.
2. In the search tool, filter by Paid orders.
3. All completed and refunded orders can be found here.

Via your dashboard

1. Log in to your MultiSafepay dashboard.
2. Go to Transactions > Transaction overview.
3. Filter the transactions by Terminal ID.
4. All transactions linked to that Terminal ID are displayed here.

Match Odoo payments with MultiSafepay transactions

To match an Odoo payment with a transaction in your MultiSafepay dashboard, compare the Receipt Number in the Odoo Orders list with the transaction's Order ID (order_id) in your MultiSafepay dashboard. Make sure to include the retry suffix, when applicable.

The Receipt Number is automatically generated based on the following parameters:

• Register number
• Current register session number
• The order number created in that session

Example

00002-005-00012

Here, 00002 is the number associated with the register or POS, 005 is the register session number, and 00012 is the order number.

Each retry receives a numeric suffix, such as OrderSequence-1 or OrderSequence-2, so that each payment attempt remains identifiable.

Example

00002-005-00012-1, 00002-005-00012-2

While a payment is pending, Odoo checks the status every two seconds.

Cancel a pending payment

Via your Odoo backend

1. In the Odoo payment screen, click Cancel.
2. Confirm Force Cancel when Odoo asks whether the payment attempt should be canceled.
3. Wait for Odoo to confirm the cancellation before retrying the payment.

Via the device

You can enable the Cancel Button on your device to cancel a payment in the MultiSafepay payment app. For more information, see Features - Cancel Button

1. On your device, on the payment screen, click the cancel button ❌.
2. Wait for Odoo to confirm the cancellation before retrying the payment.

A completed payment cannot be canceled. Use the Odoo refund flow instead.

Process a refund

The addon supports full and partial refunds for completed Cloud POS payments. Refunds must be processed with an open register. To process a refund:

1. In the open register, click Actions > Refund.
2. Select the relevant order.
3. Check the refund details and click Refund.
4. Click Payment.
5. If Odoo displays multiple eligible payments, select the original Payment Method used to process the payment.
6. Click Send to process the refund.
7. The order will be refunded.

Only a completed payment can be refunded. A fully refunded payment cannot be refunded again. Odoo stores the resulting status (Refunded or Partially Refunded) together with the remote refund transaction ID.

Payment statuses

To learn about POS payment statuses, see POS - Payment statuses.

Limitations and recommendations

• Odoo POS payments require an active internet connection. The addon does not support offline device payments.
• Odoo POS refunds must be processed within the Odoo POS register with an open session.
• Payment completion depends on notifications reaching the public Odoo URL. Keep the POS open while a payment is pending.
• Add tips in Odoo POS before starting the payment. Terminal-side tips can make the terminal amount differ from the Odoo order and accounting data.
• Shopping-cart validation is disabled by default. It is unsuitable when a Cloud POS payment covers only part of an order.
• Configure a separate Odoo Payment Method for each terminal ID and terminal group ID combination. Odoo rejects duplicate active configurations for the same terminal.

Troubleshooting

The terminal does not receive the payment

• Verify the terminal ID, terminal group ID, and terminal group API key.
• Confirm that the Payment Method is assigned to the active POS configuration.
• Check that Odoo can connect to the MultiSafepay Cloud POS API.

Odoo remains on a pending payment

• Verify the public Odoo base URL.
• Confirm that /pos_multisafepay_cloud/notification is reachable over HTTPS.
• Check reverse-proxy and firewall logs for blocked POST requests.
• Compare the Odoo receipt reference with the order in your MultiSafepay dashboard.

Odoo reports that the device is already configured

Another active Payment Method uses the same terminal ID and terminal group ID. Archive the duplicate method or configure a different terminal.

A payment cannot be canceled

Completed payments cannot be canceled. Start a refund from the original POS order.

A refund cannot find the original payment

Start the refund from the original Odoo POS order and select its MultiSafepay Cloud POS payment. Confirm that the original payment reached Paid or Completed status.

Updates

Before updating, back up the Odoo database. After updating, test the integration using your LIVE environment before reopening the POS to cashiers.

If you are using self-hosted or Docker Odoo:

1. Replace the existing addon files with the files from the new version.

2. Update the Python dependencies:

   Bash

   pip install 'multisafepay==3.1.0' requests --upgrade

3. Restart Odoo.

4. Upgrade the addon from Apps, or run:

   Bash

   odoo-bin -u pos_multisafepay_cloud -d your_database_name

5. Run a payment, cancellation, and refund test before reopening the POS to cashiers.

If you are using Odoo.sh:

1. Update the MultiSafepay Odoo module in your Odoo.sh project by pulling or merging the latest version of the MultiSafepay repository into your project.

2. Upgrade the addon from Apps, or run:

   Bash

   odoo-bin -u pos_multisafepay_cloud -d your_database_name

3. Run a payment, cancellation, and refund test before reopening the POS to cashiers.