Upvendo Knowledge Base

Appearance

Vanhoutte Integration Setup ​

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

Purpose ​

The Vanhoutte integration connects Upvendo to Vanhoutte POS registers via the Kassanet protocol -- the same protocol used by Hendrickx. It enables restaurants and hospitality businesses (primarily in Belgium) to accept orders through Upvendo channels (Kiosk, Online Ordering, Table QR) and have them appear directly on the Vanhoutte POS register for kitchen preparation and fulfillment. The integration also pulls the full product catalog from Vanhoutte so merchants do not need to re-enter their menu in Upvendo.

Key Concepts ​

Kassanet Protocol (Shared with Hendrickx) ​

Vanhoutte and Hendrickx both use the Kassanet communication protocol. They are handled by the same backend infrastructure (AbstractKassanetService), with only the provider identifier differing. All API calls follow the same pattern:

  1. The request body is serialized to JSON
  2. If encryption is enabled, the JSON is encrypted with Blowfish CBC using the merchant's encryption token and a null IV (8 zero bytes), then base64-encoded
  3. An HMAC-SHA256 signature is computed over the ISO 8601 date string concatenated with the (possibly encrypted) body, using the merchant's signature key
  4. The request is sent with headers: Date, Signature, Content-Type, and a unique request-id

Location-Specific Scope ​

Each Vanhoutte connection is tied to a single location. If a merchant has multiple locations each with its own Vanhoutte register, each location must be connected separately with its own set of credentials (Connection URL, Signature Key, Encryption Token).

One-Way Menu Sync (Vanhoutte to Upvendo) ​

Menu items must exist in Vanhoutte POS before connecting. Upvendo cannot create items in Vanhoutte -- it only reads the existing catalog. The sync imports:

  • Categories and subcategories from Vanhoutte product groups
  • Products with names, prices, and PLU codes
  • Modifier groups and modifiers (product variants/selections)
  • Display groups that control how items are organized in the Upvendo menu
  • Table numbers from the POS for table management

Order Forwarding (Upvendo to Vanhoutte) ​

After payment is confirmed, Upvendo sends orders to Vanhoutte using the CreateOrder endpoint. The order includes the table number, item article IDs, quantities, modifiers, and optional pickup time and notes. After order creation, Upvendo retrieves the bill (GetBill) and then marks the bill as paid (PayBill) using the configured webshop payment type.

Table Number Management ​

Vanhoutte supports two table assignment modes:

  • Non-physical tables -- Upvendo calls GetFreeTableNumber to get an available virtual table from the POS. A database lock prevents concurrent orders from claiming the same table.
  • Physical tables -- Upvendo allocates a table from a configured table section, checking each table's bill status to ensure it is free. Used table numbers are tracked per month to avoid collisions.

Both modes use distributed locking (MongoDB-based) to prevent race conditions when multiple orders arrive simultaneously.

Stock Tracking ​

After menu sync, Upvendo can pull stock levels from Vanhoutte using the GetCountdownPluState endpoint. Items with countdown PLUs have their inventory updated in Upvendo, enabling out-of-stock indicators on Kiosk and Online Ordering. A threshold parameter can be set to only return items below a certain stock level.

Available Kassanet API Endpoints ​

The following Kassanet endpoints are used by the Vanhoutte integration:

EndpointMethodPurpose
testGETTest connection and retrieve system info (including tipping settings)
GetAllProductsGETFetch the complete product catalog (categories, products, modifiers)
GetProductSelectionGETFetch product selections / display groups
TableNumbersGETFetch all configured table numbers
GetFreeTableNumberGETGet the next available virtual table number
GetBill?tableNumber=NGETRetrieve the current bill for a table
GetPaymentTypesGETFetch available payment types on the POS
CreateOrderPOSTSend an order to the POS register
PayBillPOSTMark a bill as paid with a specified payment type
PostDepositPOSTPost a deposit payment to a table
GetCountdownPluStateGETFetch stock levels for countdown PLU items

Connection Status and Auto-Reconnection ​

The integration tracks connection status per location. If an API call fails due to a timeout or server error, the location is marked as disconnected. A scheduled command (kassanet:check-and-requeue) periodically tests all disconnected locations and automatically restores them when the POS comes back online. Successfully reconnected locations have their queued orders automatically dispatched.

Actions ​

Connect Vanhoutte ​

Route: /vanhoutte

  1. Complete all prerequisites (see checklist below)
  2. Select the target location from the topbar
  3. Click Connect or Add Channel and select Vanhoutte
  4. Enter credentials:
    • Connection URL -- The Vanhoutte Kassanet API base URL (provided by Vanhoutte)
    • Signature Key -- The HMAC signing key for API authentication
    • Encryption Token -- The Blowfish encryption key for payload encryption
  5. Click Sync Now to import the menu
  6. Verify sync results in the Vanhoutte Logs

Sync Menu ​

Route: /vanhoutte

Click Sync Now to manually trigger a full menu import. The sync runs as a background job chain:

  1. ImportKassanetMenuJob -- kicks off the import
  2. ImportKassanetCategoriesJob -- fetches GetAllProducts, processes categories and subcategories
  3. ImportKassanetProductsJob -- processes products and modifiers from the same data
  4. ImportKassanetDisplayGroupsJob -- processes display groups, syncs table numbers, merges modifier groups, syncs stock levels, and cleans up placeholder items

Each job retries up to 3 times with a 30-second backoff. The total import has a 5-minute timeout per job.

Configure Auto Sync ​

Set a daily sync time (e.g., 05:00) to automatically re-import menu changes from Vanhoutte. The time you set in the UI is in your location's timezone and is converted to UTC for scheduling. Disable by clearing the sync time field.

Test Connection ​

Click Test Connection to verify the Kassanet API is reachable. The test calls the /test endpoint, checks the IsSuccessStatusCode response field, and updates the connection status. If the POS was previously disconnected, a successful test automatically requeues any failed orders.

Delete Integration ​

Click Delete to remove the Vanhoutte integration from a location. This deletes all imported categories, display groups, items, modifiers, modifier groups, menus, table sections, and inventory records associated with Vanhoutte for that location.

View Logs ​

Route: /vanhoutte

The Vanhoutte Logs panel shows the most recent sync and order events. Each log entry includes:

  • Timestamp -- when the event occurred (ISO 8601 format)
  • Type -- success, error, or info
  • Message -- a description of what happened (e.g., "Successfully synced 42 products", "Failed to create order #1234")

Logs are capped at 100 entries per location. Duplicate consecutive entries (same type and message) are collapsed into one entry with the updated timestamp.

Business Rules ​

  • Menu items must exist in Vanhoutte POS before they can appear in Upvendo. There is no push from Upvendo to Vanhoutte for menu data.
  • Orders are only forwarded to Vanhoutte after payment is confirmed via Viva Wallet (Kiosk) or Stripe (Online Ordering).
  • If the Vanhoutte register is offline when an order is placed, the order is flagged with need_requeue = true. When the POS comes back online (detected via the periodic kassanet:check-and-requeue command or a manual test), flagged orders are automatically requeued.
  • Each API request includes a unique request-id header for traceability.
  • API requests time out after 15 seconds (with a 10-second connection timeout). Retryable errors (timeouts, 5xx responses) trigger exponential backoff retries (0.2s, 0.4s, 0.8s).
  • Table number locks expire after 5 minutes to prevent permanent table lockout if a process fails.
  • The integration logs up to 100 recent entries per location, with the newest first. Duplicate consecutive log entries are collapsed by updating the timestamp.
  • The in-house:auto-sync artisan command runs on a schedule to trigger automatic daily syncs for all configured Vanhoutte integrations.
  • If a bill total from Vanhoutte does not match the Upvendo transaction total, a mismatch is logged but the order still proceeds.
  • Vanhoutte and Hendrickx integrations cannot be active on the same location simultaneously -- each location is tied to one Kassanet provider.
  • When encryption is enabled on the integration, the URL path includes a SEC1 segment between the base URL and the endpoint name. This signals the Kassanet server to expect encrypted payloads.
  • The sync cleans up placeholder items after import. Items with a kitchen name of "zz" or matching the pattern * pager * or items where the kitchen name equals a numeric product name are automatically removed.
  • After a successful import, the guided setup progress is automatically updated for the merchant.

Prerequisites Checklist ​

Before integrating with Vanhoutte, complete these steps in order:

1. Payment Profile Setup (Required) ​

  1. Go to Settings -> Payments (/settings/payments)
  2. Set up your payment providers:
    • Viva Wallet for Kiosk payments (terminal-based)
    • Stripe for Online Ordering payments
  3. Configure payment methods (Card, Bancontact, etc.)

2. Billing Profile Setup (Required) ​

  1. Go to Settings -> Billing (/settings/billing)
  2. Complete your billing information

3. Branding Profile Setup (Required) ​

  1. Go to Settings -> Brand (/settings/brand)
  2. Configure your store's branding (logo, colors, etc.)

4. Location Creation (Required) ​

  1. Go to Settings -> Locations (/settings/locations)
  2. Create your location with:
    • Business name and address
    • Business hours
    • Contact information
  3. Select this location from the topbar before connecting Vanhoutte

Order Flow ​

Orders are created in Upvendo (via Kiosk, Online Ordering, or Table QR) and pushed to Vanhoutte after payment is confirmed.

Three-Step POS Flow ​

text
1. CreateOrder    ->  Sends items + table number to Vanhoutte POS
         |
2. GetBill        ->  Retrieves the bill total for the table
         |
3. PayBill        ->  Marks the bill as paid with the webshop payment type

Kiosk Flow ​

text
Customer submits order on Kiosk
            |
Viva Wallet terminal prompts for payment
            |
Customer pays the prompted amount
            |
Upvendo receives successful payment webhook
            |
ProcessOrderJob dispatches CreateOrder to Vanhoutte
            |
GetKassanetBillJob retrieves the bill
            |
PayKassanetBillJob marks the bill as paid

Online Ordering Flow ​

text
Customer submits order online
            |
Payment processed (Bancontact redirect or card details via Stripe)
            |
Customer pays the prompted amount
            |
Upvendo receives successful payment webhook
            |
ProcessOrderJob dispatches CreateOrder to Vanhoutte
            |
GetKassanetBillJob retrieves the bill
            |
PayKassanetBillJob marks the bill as paid

Order Payload Structure ​

Each order sent to Vanhoutte includes:

  • TableNumber -- the assigned table (physical or virtual)
  • TableText -- order channel, order number, pager ID (if any), customer name, phone, email
  • Items[] -- each item has ArticleId, Text, Quantity, optional InfoText (notes), and nested Variants[] for modifiers
  • PickupTime -- for non-dine-in orders, formatted as HH:mm in the location's timezone

FAQs ​

Q: What is the difference between Vanhoutte and Hendrickx? A: Both use the same Kassanet protocol and share the same backend integration code. The only difference is the provider name and the specific POS hardware/software. If you have a Vanhoutte POS, use this integration; if you have a Hendrickx POS, use the Hendrickx integration.

Q: Can I create menu items in Upvendo and push them to Vanhoutte? A: No. The Vanhoutte integration is one-way for menu data. Items must be created in the Vanhoutte POS first, then synced to Upvendo via the Sync Now button or auto-sync schedule.

Q: What happens if the Vanhoutte POS is turned off when an order comes in? A: The order is saved with a need_requeue flag. A background command (kassanet:check-and-requeue) periodically checks disconnected locations and automatically requeues failed orders when the POS comes back online. You can also manually click Test Connection to trigger a requeue.

Q: Can I connect multiple Vanhoutte registers to one Upvendo location? A: No. Each location supports one Vanhoutte integration. If you have multiple registers, they should share the same Kassanet connection endpoint.

Q: Does the integration support tipping? A: Yes. If the Vanhoutte system has the tip calculator activated (tipCalculatorActivated in the test response), tipping is enabled in Upvendo. Tip amounts are included in the PayBill request.

Q: How often does auto-sync run? A: Auto-sync runs once per day at the configured sync time. The time you set in the UI is in your location's timezone and is converted to UTC for scheduling. If no sync time is set, auto-sync is disabled.

Q: Can I switch from Hendrickx to Vanhoutte on the same location? A: Yes. First delete the existing Hendrickx integration from the location, then connect Vanhoutte with the new credentials. The menu will need to be re-synced.

Q: What is a PLU code? A: PLU stands for Price Look-Up. It is a unique identifier assigned to each product in the Vanhoutte POS. Upvendo uses PLU codes (stored as ArticleId) to reference items when creating orders and tracking stock levels.

Q: Does the integration support order notes or special instructions? A: Yes. Per-item notes are sent as InfoText in the order payload. These appear on the kitchen display or receipt in the Vanhoutte POS.

Troubleshooting ​

Orders not syncing to Vanhoutte ​

  • Verify the Vanhoutte register is powered on and connected to the internet
  • Go to /vanhoutte and click Test Connection to check the current status
  • Check Vanhoutte Logs for specific error messages
  • If the connection status shows "disconnected", the POS may be offline. Orders will automatically requeue when the connection is restored

"Connection test failed" error ​

  • Double-check the Connection URL -- it should be the full Kassanet API base URL without a trailing slash
  • Verify the Signature Key is correct -- an incorrect key produces HMAC signature mismatches
  • Verify the Encryption Token is correct -- an incorrect token causes Blowfish decryption error or Invalid JSON response: possibly incorrect encryption token
  • Ensure the Vanhoutte register's firewall allows incoming connections from Upvendo's servers

"No free table numbers available" error ​

  • This means all virtual or physical tables are occupied or locked
  • Check if there are stale table locks (they auto-expire after 5 minutes)
  • For physical tables, verify the table section is properly configured and has enough tables
  • Check if the table number range in the Vanhoutte POS matches the Upvendo configuration
  • Verify the Vanhoutte POS has products configured
  • Check if the API returns data by clicking Test Connection first
  • Review the Vanhoutte Logs for errors during the import job steps
  • If the sync was interrupted, try clicking Sync Now again -- each job retries up to 3 times

Bill total mismatch warning in logs ​

  • This occurs when the bill total from Vanhoutte does not match the Upvendo transaction total
  • Common causes: price differences between Upvendo and Vanhoutte (menu not recently synced), rounding differences, or modifier pricing discrepancies
  • Run a menu sync to ensure prices are up to date
  • The order still proceeds despite the mismatch, but the warning should be investigated

Orders stuck in "error" status ​

  • Check the external_data.vanhoutte.errMessage field on the transaction for the specific error
  • Common causes: POS was offline during order creation, invalid article IDs (item removed from POS but still in Upvendo menu), or table assignment failure
  • If the POS is now online, click Test Connection to trigger automatic requeue of failed orders
  • Blowfish decryption error -- the encryption token is likely incorrect. Re-enter the correct token from your Vanhoutte provider
  • Invalid base64 input -- the response from Vanhoutte was not properly encrypted. Check if encryption is enabled on both sides
  • If you recently changed the encryption token in Vanhoutte, update it in Upvendo as well