Upvendo Knowledge Base

Appearance

Hendrickx Integration Setup ​

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

Purpose ​

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

Key Concepts ​

Kassanet Protocol ​

Hendrickx uses the Kassanet communication protocol, a proprietary API standard shared with Vanhoutte POS systems. Both providers are handled by the same backend service (AbstractKassanetService) and differ only in the provider identifier. All API calls follow this 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 Hendrickx connection is tied to a single location. If a merchant has multiple locations each with its own Hendrickx register, each location must be connected separately with its own set of credentials (Connection URL, Signature Key, Encryption Token).

One-Way Menu Sync (Hendrickx to Upvendo) ​

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

  • Categories and subcategories from Hendrickx product groups
  • Products with names, prices, and PLU (Price Look-Up) 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 Hendrickx) ​

After payment is confirmed, Upvendo sends orders to Hendrickx 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 ​

Hendrickx 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 Hendrickx 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 Hendrickx 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 Hendrickx ​

Route: /hendrickx

  1. Complete all prerequisites (see checklist below)
  2. Select the target location from the topbar
  3. Click Connect or Add Channel and select Hendrickx
  4. Enter credentials:
    • Connection URL -- The Hendrickx Kassanet API base URL (provided by Hendrickx)
    • 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 Hendrickx Logs

Sync Menu ​

Route: /hendrickx

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 Hendrickx. The sync time is stored in UTC and converted based on the location's timezone. 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 Hendrickx integration from a location. This deletes all imported categories, display groups, items, modifiers, modifier groups, menus, table sections, and inventory records associated with Hendrickx for that location.

View Logs ​

Route: /hendrickx

The Hendrickx 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 Hendrickx POS before they can appear in Upvendo. There is no push from Upvendo to Hendrickx for menu data.
  • Orders are only forwarded to Hendrickx after payment is confirmed via Viva Wallet (Kiosk) or Stripe (Online Ordering).
  • If the Hendrickx 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 Hendrickx integrations.
  • If a bill total from Hendrickx does not match the Upvendo transaction total, a mismatch is logged but the order still proceeds.
  • 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 Hendrickx, 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 Hendrickx

Order Flow ​

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

Three-Step POS Flow ​

text
1. CreateOrder    ->  Sends items + table number to Hendrickx 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 Hendrickx
            |
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 Hendrickx
            |
GetKassanetBillJob retrieves the bill
            |
PayKassanetBillJob marks the bill as paid

Order Payload Structure ​

Each order sent to Hendrickx 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: Can I create menu items in Upvendo and push them to Hendrickx? A: No. The Hendrickx integration is one-way for menu data. Items must be created in the Hendrickx POS first, then synced to Upvendo via the Sync Now button or auto-sync schedule.

Q: What happens if the Hendrickx 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 Hendrickx registers to one Upvendo location? A: No. Each location supports one Hendrickx integration. If you have multiple registers, they should share the same Kassanet connection endpoint.

Q: Does the integration support tipping? A: Yes. If the Hendrickx 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: What encryption does the integration use? A: The integration uses Blowfish CBC encryption with an 8-byte null IV. The encryption token provided by Hendrickx serves as the Blowfish key. If encryption is enabled on the integration, all request bodies are encrypted before sending and all responses are decrypted after receiving.

Q: Can I use Hendrickx with both Kiosk and Online Ordering at the same location? A: Yes. Both channels send orders through the same Hendrickx integration. Kiosk orders use Viva Wallet for payment and Online Ordering uses Stripe.

Q: What is a PLU code? A: PLU stands for Price Look-Up. It is a unique identifier assigned to each product in the Hendrickx 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 Hendrickx POS.

Troubleshooting ​

Orders not syncing to Hendrickx ​

  • Verify the Hendrickx register is powered on and connected to the internet
  • Go to /hendrickx and click Test Connection to check the current status
  • Check Hendrickx 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 Hendrickx 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 Hendrickx POS matches the Upvendo configuration
  • Verify the Hendrickx POS has products configured
  • Check if the API returns data by clicking Test Connection first
  • Review the Hendrickx Logs for errors during the ImportKassanetCategoriesJob or ImportKassanetProductsJob 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 Hendrickx does not match the Upvendo transaction total
  • Common causes: price differences between Upvendo and Hendrickx (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.hendrickx.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 Hendrickx provider
  • Invalid base64 input -- the response from Hendrickx was not properly encrypted. Check if encryption is enabled on both sides
  • If you recently changed the encryption token in Hendrickx, update it in Upvendo as well