MplusKassa Integration Setup

Looking for guided setup? Start Emily in the backoffice for step-by-step guided setup.

Purpose

The MplusKassa integration connects Upvendo to MplusKassa POS systems commonly used in the Netherlands. It provides bidirectional menu sync (products, categories, modifiers, and images), order forwarding from Upvendo to MplusKassa, inventory sync from MplusKassa to Upvendo, and webhook-driven event handling for real-time POS events including external payment flows. This enables restaurants to accept orders via Upvendo channels (Kiosk, Online Ordering, Table QR) while keeping MplusKassa as the central POS for kitchen operations and fulfillment.

Key Concepts

Merchant-Scoped Integration

Unlike Hendrickx or Vanhoutte (which are location-specific), MplusKassa is merchant-scoped -- one connection covers all branches. When you connect MplusKassa with your credentials, Upvendo automatically imports your MplusKassa branches as Upvendo locations.

SOAP API via MplusQapi SDK

MplusKassa uses a SOAP-based API accessed through the MplusQapi SDK client. The backend communicates with MplusKassa's API server for all data operations (products, orders, stock, tables). The integration service orchestrates 35 specialized sub-services for different aspects of the POS communication.

The menu sync works in both directions:

Pull (MplusKassa to Upvendo): Import products, articles, images, preparation methods, article alterations, and nutritional data
Push (Upvendo to MplusKassa): Export categories, items, combos, and pricing changes made in Upvendo

Data mapping between the two systems:

MplusKassa	Upvendo	Direction
Product	Category	Bidirectional
Article	Item	Bidirectional
PreparationMethod	ModifierGroup	Pull only
ArticleAlteration	ModifierGroup	Pull only
Branch	Location	Pull only (auto-import)
Stock (amountFree)	Inventory	Pull only

Sync Markers (Incremental Sync)

Instead of fetching all data every time, MplusKassa uses sync markers to track what has changed since the last sync. Each sync call returns a new marker, and the next sync sends that marker to only receive changes. This keeps sync efficient for large catalogs.

Webhook Event Handling

MplusKassa sends webhooks to Upvendo when POS events occur. These are routed through the MplusKassaWebhookOrchestrator to specialized handlers:

Event	Action
`completeSession`	Creates a transaction in Upvendo
`cancelSession`	Cancels the corresponding transaction
`startExternalPayment`	Creates a pending payment record
`pollExternalPayment`	Returns current payment status to MplusKassa
`requestCancelExternalPayment`	Marks payment as cancellation requested
`cancelExternalPayment`	Cancels the payment
`startSession`, `addSessionLine`, `removeSessionLine`	Acknowledged (no action)
`creditSession`	Acknowledged only (refund processing not yet implemented)

External Payment Flow

MplusKassa supports a 4-step external payment flow for payments processed through Upvendo's payment providers (Stripe, Viva Wallet):

startExternalPayment -- MplusKassa initiates a payment, Upvendo creates a pending transaction
pollExternalPayment -- MplusKassa polls for status; Upvendo responds with pending, confirmed, or failed
Payment is processed by Stripe or Viva Wallet in parallel
When payment succeeds, the next poll returns confirmed with polling.finished = true, and MplusKassa completes the sale

Order Types

Type	MplusKassa Method	Use Case
Regular Order	`createOrder()`	Pickup, delivery
Table Order	`saveTableOrder()`	Dine-in, pay later
Table Order + Pay	`createAndPayTableOrder()`	Dine-in, pay now

Orders include an extOrderId (the Upvendo order number) for idempotency, branch and workplace numbers, employee number, VAT method (inclusive), order lines with article numbers and quantities, payment details, and optional delivery address or table number.

Key Backend Architecture

The MplusKassa integration is orchestrated by a main service (MplusKassaIntegrationService, approximately 3200 lines) that coordinates 35 specialized sub-services:

Service	Purpose
`ProductService`	Products and articles sync
`ArticleManagementService`	Modifiers, alterations, combos
`TableManagementService`	Tables, courses, dine-in
`StockService`	Inventory pull from MplusKassa
`BranchService`	Location/branch management
`RelationService`	Customer records
`MediaService`	Product image downloads
`ExternalPaymentService`	External payment flow handling
`OrderSyncService`	Order building and submission
`WebhookService`	Webhook event processing

Streaming Sync for Large Catalogs

To avoid memory exhaustion with large product catalogs, the sync uses streaming/chunked processing. Products and articles are fetched and processed in batches, ensuring the sync can handle thousands of items without running out of memory.

Actions

Connect MplusKassa

Route: /mpluskassa

Complete all prerequisites (see checklist below)
Click Connect or Add Channel
Enter your MplusKassa credentials:
- Username -- Your MplusKassa API username
- Password -- Your MplusKassa API password
Upvendo automatically imports your MplusKassa branches as locations

Post-Connection Location Setup

Once connected, MplusKassa automatically:

Imports your MplusKassa branches as Upvendo locations
Assigns the default billing profile's Stripe customer ID
Creates branding profiles for each location

Go to Settings -> Locations (/settings/locations) after import to complete any missing fields (address coordinates, business hours, delivery zones, etc.).

Click Sync Now to trigger a bidirectional menu sync. The sync:

Pulls new and updated products/articles from MplusKassa using sync markers
Maps MplusKassa Products to Upvendo Categories, Articles to Items
Downloads product images to Cloudflare Images
Imports preparation methods and article alterations as modifier groups
Pushes any Upvendo-side changes back to MplusKassa

Configure Tax Mapping

Map Upvendo tax rates to MplusKassa BTW codes:

21% -> BTW Hoog (standard rate)
9% -> BTW Laag (reduced rate, food and non-alcoholic drinks)
0% -> BTW Vrij (exempt)

Sync Inventory

Inventory sync is one-directional (MplusKassa to Upvendo). MplusKassa is the source of truth for stock levels. The sync pulls amountFree values per article per branch and updates Upvendo's inventory system.

Configure Daily Sync Time

Set a daily sync time to automatically sync menu and inventory changes from MplusKassa.

Business Rules

MplusKassa is the source of truth for stock levels. Inventory adjustments in Upvendo do not push back to MplusKassa.
When both sides have changed the same item, MplusKassa wins in webhook context; the most recent timestamp wins during manual sync.
Modifier groups (preparation methods and article alterations) are pull-only. Changes to modifier groups in Upvendo do not sync back to MplusKassa.
Orders flow one direction: Upvendo to MplusKassa. Orders placed on the MplusKassa POS terminal trigger webhooks that create transactions in Upvendo.
The extOrderId field uses the Upvendo order number and requires a configured or fallback relation number for customer tracking.
Branch-specific price deviations are supported -- if a MplusKassa article has a different price for a specific branch, that branch-specific price is used.
MplusKassa's combo/menu API uses merge behavior: you can add or update choices, but removing a choice must be done manually in the MplusKassa backoffice.
Webhook responses must include event-specific JSON (e.g., the external payment flow expects externalPayment and polling.finished fields). The controller returns response()->json($result) rather than a generic success response.
The creditSession webhook (refunds) is acknowledged but not yet processed. Refunds made on the POS are not reflected in Upvendo.
VAT method is always set to INCLUSIVE for orders sent to MplusKassa.

Prerequisites Checklist

Before integrating with MplusKassa, complete these steps in order:

1. Payment Profile Setup (Required)

Go to Settings -> Payments (/settings/payments)
Set up your payment providers:
- Viva Wallet for Kiosk payments (terminal-based)
- Stripe for Online Ordering payments
Configure payment methods:
- iDEAL (recommended for Netherlands)
- Card payments (Visa, Mastercard)
- Bancontact (if serving Belgian customers)

2. Billing Profile Setup (Required)

Go to Settings -> Billing (/settings/billing)
Complete your billing information
The Stripe customer ID from this profile is used for imported locations

3. Branding Profile Setup (Required)

Go to Settings -> Brand (/settings/brand)
Configure your store's branding (logo, colors, etc.)
A branding profile is created for each imported location

Order Flow

text

Upvendo (Kiosk / Online Ordering / Table QR)
            |
Customer places order and pays via Stripe or Viva Wallet
            |
Payment confirmed via webhook
            |
OrderSyncService builds order from transaction
  - Maps items to MplusKassa article numbers
  - Sets branch number, workplace, employee
  - Includes payment details and optional table/delivery info
            |
Order sent to MplusKassa via SOAP API
  - createOrder() for pickup/delivery
  - saveTableOrder() for dine-in pay-later
  - createAndPayTableOrder() for dine-in pay-now
            |
MplusKassa POS receives order for fulfillment

Netherlands-Specific Configuration

Payment Methods

For Dutch customers, enable these payment methods:

iDEAL -- Most popular in Netherlands
Card -- Visa, Mastercard
Bancontact -- For Belgian customers

Tax Rates (BTW)

Rate	Category	Examples
21%	Standard (BTW Hoog)	Most items
9%	Reduced (BTW Laag)	Food, non-alcoholic drinks
0%	Exempt (BTW Vrij)	Specific exempt items

Receipts

Ensure receipts show BTW number
Configure Dutch receipt format in Settings -> Receipts

FAQs

Q: Is MplusKassa bidirectional for menu data? A: Yes. Unlike Hendrickx/Vanhoutte, MplusKassa supports both pulling products from the POS and pushing changes from Upvendo back to MplusKassa. However, modifier groups are currently pull-only.

Q: Do I need to create locations manually? A: No. When you connect MplusKassa, your branches are automatically imported as Upvendo locations. You should then complete any missing fields (coordinates, hours, delivery zones) in Settings -> Locations.

Q: What happens if I change a price in Upvendo? A: The price change will be pushed to MplusKassa during the next sync. If MplusKassa also changed the price, the conflict resolution depends on context: MplusKassa wins in webhook context, the most recent timestamp wins during manual sync.

Q: How does the external payment flow work? A: MplusKassa initiates a payment via the startExternalPayment webhook, then polls for status. Meanwhile, the customer pays through Stripe or Viva Wallet. Once payment succeeds, the next poll returns confirmed and MplusKassa completes the sale.

Q: Can I use MplusKassa with iDEAL? A: Yes. iDEAL is the recommended payment method for Dutch customers and is configured through Stripe. Set it up in Settings -> Payments.

Q: Are refunds supported? A: Refunds made on the MplusKassa POS (creditSession webhook) are acknowledged but not yet processed in Upvendo. Refund processing is on the roadmap.

Q: Does the integration support table ordering? A: Yes. MplusKassa supports table management, courses, and dine-in ordering. Table orders can be created with immediate payment or as pay-later orders.

Q: What happens if the MplusKassa API is unreachable during sync? A: The sync job will retry. Check the Activity Log for specific error messages. The connection uses sync markers, so a subsequent successful sync will pick up where it left off.

Q: Can I stop orders from being sent automatically to MplusKassa so I can accept them first? A: No. There's no setting to hold orders for manual acceptance or to turn off forwarding to the POS. Once a customer's order is placed and paid (Kiosk, Online Ordering, or Table QR), Upvendo forwards it to MplusKassa automatically as part of order processing — orders are not queued for your approval. What you can control: whether the online channel accepts orders at all (the Accept online orders switch in Online Ordering), how late orders are accepted (the order cut-off time, e.g. until closing), and how many orders/items are accepted per time slot (Order Capacity in Online Settings). An internal skip_order_sync flag exists but is restricted to test environments and can't be used on a live store.

Troubleshooting

Orders not syncing

Check MplusKassa username and password are correct
Verify connection status shows "Connected" on the MplusKassa page
Check Activity Log for sync errors
Ensure the order has article numbers that exist in MplusKassa (items without a valid external_ids.mpluskassa mapping will fail)

Payment failing

Verify payment profile is assigned to the location
Check payment provider connection status (Stripe or Viva Wallet)
For iDEAL issues, verify the customer's bank is supported by Stripe
For external payment flow issues, check that the webhook endpoint is reachable and returning proper JSON responses

Stock not updating

Ensure Sync Stock is enabled for the integration
Check that article mapping is complete (items need external_ids.mpluskassa to match stock data)
Trigger manual sync: MplusKassa -> Sync Now
Stock sync is one-directional (MplusKassa to Upvendo only)

Tax mismatch

Verify tax mapping configuration matches your MplusKassa BTW setup
Check items have correct tax rates assigned in both systems
Ensure BTW codes (Hoog/Laag/Vrij) match between MplusKassa and Upvendo

Locations not imported correctly

Check that your MplusKassa account has active branches configured
After import, complete missing fields in Settings -> Locations (coordinates, hours, delivery zones)
If a branch was added after initial connection, run a sync to detect new branches

Modifier groups not syncing back to MplusKassa

This is a known limitation. Modifier groups (preparation methods and article alterations) are currently pull-only
Changes to modifier groups must be made in the MplusKassa backoffice and then synced to Upvendo
Bidirectional modifier group sync is planned for a future update

Webhook events not being received

Verify the webhook URL is correctly registered in MplusKassa's configuration
Check that the endpoint /webhook/mpluskassa/{event} is accessible from the internet
Review server logs for any incoming requests that may be failing silently
Ensure the MplusKassa integration record exists and is active for the vendor

This is an API limitation of MplusKassa's UpdateArticleMenuRequest, which uses merge behavior
You can add or update choices from Upvendo, but removing a choice must be done manually in the MplusKassa backoffice

MplusKassa Integration Setup

Purpose

Key Concepts

Merchant-Scoped Integration

SOAP API via MplusQapi SDK

Bidirectional Menu Sync

Sync Markers (Incremental Sync)

Webhook Event Handling

External Payment Flow

Order Types

Key Backend Architecture

Streaming Sync for Large Catalogs

Actions

Connect MplusKassa

Post-Connection Location Setup

Sync Menu

Configure Tax Mapping

Sync Inventory

Configure Daily Sync Time

Business Rules

Prerequisites Checklist

1. Payment Profile Setup (Required)

2. Billing Profile Setup (Required)

3. Branding Profile Setup (Required)

Order Flow

Netherlands-Specific Configuration

Payment Methods

Tax Rates (BTW)

Receipts

FAQs

Troubleshooting

Orders not syncing

Payment failing

Stock not updating

Tax mismatch

Locations not imported correctly

Modifier groups not syncing back to MplusKassa

Webhook events not being received

Combo/menu choices cannot be removed

MplusKassa Integration Setup ​

Purpose ​

Key Concepts ​

Merchant-Scoped Integration ​

SOAP API via MplusQapi SDK ​

Bidirectional Menu Sync ​

Sync Markers (Incremental Sync) ​

Webhook Event Handling ​

External Payment Flow ​

Order Types ​

Key Backend Architecture ​

Streaming Sync for Large Catalogs ​

Actions ​

Connect MplusKassa ​

Post-Connection Location Setup ​

Sync Menu ​

Configure Tax Mapping ​

Sync Inventory ​

Configure Daily Sync Time ​

Business Rules ​

Prerequisites Checklist ​

1. Payment Profile Setup (Required) ​

2. Billing Profile Setup (Required) ​

3. Branding Profile Setup (Required) ​

Order Flow ​

Netherlands-Specific Configuration ​

Payment Methods ​

Tax Rates (BTW) ​

Receipts ​

FAQs ​

Troubleshooting ​

Orders not syncing ​

Payment failing ​

Stock not updating ​

Tax mismatch ​

Locations not imported correctly ​

Modifier groups not syncing back to MplusKassa ​

Webhook events not being received ​

Combo/menu choices cannot be removed ​

Related Documentation ​

MplusKassa Integration Setup

Purpose

Key Concepts

Merchant-Scoped Integration

SOAP API via MplusQapi SDK

Bidirectional Menu Sync

Sync Markers (Incremental Sync)

Webhook Event Handling

External Payment Flow

Order Types

Key Backend Architecture

Streaming Sync for Large Catalogs

Actions

Connect MplusKassa

Post-Connection Location Setup

Sync Menu

Configure Tax Mapping

Sync Inventory

Configure Daily Sync Time

Business Rules

Prerequisites Checklist

1. Payment Profile Setup (Required)

2. Billing Profile Setup (Required)

3. Branding Profile Setup (Required)

Order Flow

Netherlands-Specific Configuration

Payment Methods

Tax Rates (BTW)

Receipts

FAQs

Troubleshooting

Orders not syncing

Payment failing

Stock not updating

Tax mismatch

Locations not imported correctly

Modifier groups not syncing back to MplusKassa

Webhook events not being received

Combo/menu choices cannot be removed

Related Documentation