Kiosk Setup

Overview

Kiosks are self-service ordering terminals placed in-store. Customers can browse the menu, customize items, and pay without staff assistance.

Key Purpose: Enable self-service ordering for in-store customers.

Purpose

This page lets you register, configure, and manage self-service kiosk devices that allow in-store customers to browse menus, place orders, and pay independently.

Key Concepts

Kiosk Device: A physical terminal (Android tablet) running the Upvendo kiosk application, registered to a specific location via an activation code.
Device Profile: A configuration template assigned to a kiosk that controls its menus, dining options, idle behaviour, screensaver, schedule, receipt options, customer-flow layout, and order-number display.
Activation Code: A time-limited code generated in the backoffice that pairs a new kiosk device to a location; subject to a resend cooldown (default 15 minutes, max 3 resends per window).
Idempotency Key: A unique identifier attached to each kiosk transaction to prevent duplicate orders during payment retries or network interruptions.
Subscription: Each kiosk device requires an active Stripe subscription; the first kiosk at a location may have a different price tier than additional kiosks.

Actions

Register a New Kiosk

Create a kiosk device in the backoffice, generate an activation code, and enter it on the physical terminal to pair and download menu data.

Assign a Payment Terminal

Pair a card terminal to the kiosk per device. Depending on the merchant's payment provider this is a Viva Wallet terminal, a Stripe Terminal reader, or a Square terminal (paired via a device code) so customers can pay by card directly at the device.

Configure a Device Profile

Set the profile's menus, dining options, idle settings, idle screensaver, schedule, receipt options, customer-flow layout, customer identification, and order-number display for the kiosk experience. (Upsell suggestions are configured separately as Upsell Groups, not in the device profile.)

Send Remote Commands

Send a remote-control command to a kiosk device from the backoffice. Supported commands are restart, logout, firmware_update, and update_apk; the command is delivered to the device over Firebase Cloud Messaging (FCM) and only applies to Kiosk-type devices.

Cancel a Kiosk Transaction

Cancel a pending kiosk payment, which aborts the active terminal session and publishes a cancellation or failure status to the device.

Location

Backoffice Route: /devices/kiosks
Backend Controller: app/Http/Controllers/Api/KioskController.php
Vue Component: src/views/devices/kiosks/index.vue
Kiosk App: upvendo-kiosk-testing-2

Concepts

Kiosk Device

Physical terminal running the kiosk application.

Device Profile

Configuration template applied to kiosks.

Kiosk Mode

Full-screen, locked-down ordering interface.

Kiosk Device Fields

Device Name

Property	Value
Field ID	`name`
Label	Device Name
Type	Text
Required	Yes
Validation	max: 50 characters

Description: Identifier for this kiosk device.

Examples:

"Kiosk 1 - Entrance"
"Kiosk 2 - Counter"
"Self-Order Terminal A"

Assigned Location

Property	Value
Field ID	`location_id`
Label	Location
Type	Select
Required	Yes

Description: Which location this kiosk belongs to.

Business Logic:

Kiosk uses this location's menu and settings
Orders created for this location
Receipts show this location's info

Device Profile

Property	Value
Field ID	`device_profile_id`
Label	Device Profile
Type	Select
Required	No

Description: Configuration profile applied to this kiosk. The profile is where the menu(s), dining options, idle behaviour, schedule, receipt options and other kiosk settings live. The menu is not set on the device itself.

Payment Terminal

Property	Value
Field ID	`viva_wallet_terminal_id` / `stripe_terminal_id` (reader) / `external_data.square`
Label	Reader / Terminal
Type	Per-device pairing
Required	No

Description: Card terminal paired to this device. The pairing differs by the merchant's payment provider: a Viva Wallet terminal id, a paired Stripe Terminal reader, or a Square terminal device code. There is no single "terminal" select with a "None" option — a device simply has no terminal paired until one is added.

Device Status

Property	Value
Field ID	`status` (derived)
Label	Status
Type	Display
Values	Online, Offline

Description: Current status of the kiosk device, derived from activation state and last-seen time.

Statuses:

Online: Activated and seen within the offline threshold (default 15 minutes / 900 seconds).
Offline: Not activated, never checked in, explicitly offline, or not seen within the offline threshold.

Device Profile Fields

Profile Name

Property	Value
Field ID	`name`
Label	Profile Name
Type	Text
Required	Yes

Description: Name for this configuration profile.

Location

Property	Value
Field ID	`location_id`
Label	Location
Type	Select
Required	Yes

Description: Location this profile belongs to. Devices assigned to the profile serve this location's data.

Property	Value
Field ID	`default_menu_id` (with `custom_default_menu`)
Label	Default Menu
Type	Select

Description: The menu always served to kiosks using this profile. When custom_default_menu is off the profile falls back to the location's in-house default menu; when on, the profile's own default_menu_id is used.

Extra Menus

Property	Value
Field ID	`extra_menu_ids`
Label	Extra Menus
Type	Multi-select

Description: Additional menus, each scheduled for specific days/times, served alongside the default menu.

Idle Timeout

Property	Value
Field ID	`idle_timeout_type`, `idle_timeout_seconds`, `show_warning_for_seconds`
Label	Idle Timeout
Type	Radio (Standard / Custom) + Number (seconds)
Options	`standard`, `custom`
Default	`standard`

Description: Ends an in-progress session and clears entered data after inactivity, returning the kiosk to the home screen.

Business Logic:

Standard: warning given after 45 seconds and shown for 15 seconds (these are the values returned by the backend for the standard type).
Custom: you set "give warning after" (idle_timeout_seconds) and "show warning for" (show_warning_for_seconds), in seconds (minimum 1).

Idle Screensaver

Property	Value
Field ID	`idle_screensaver.enabled`, `idle_screensaver.minutes`, `screensaver_image` (stored as `screensaver_content_id`)
Label	Idle Screensaver
Type	Toggle + Number (minutes) + Image upload
Default	Off

Description: An optional full-screen image shown on an idle kiosk. This is separate from Idle Timeout: the timeout resets the order to the welcome screen, while the screensaver displays your uploaded image after a set period of inactivity.

Setup (Device Management → Profiles → edit profile → Idle settings):

Turn Idle Screensaver on.
Set the minutes of inactivity before the screensaver appears.
Upload the screensaver image.
Save.

Business Logic:

Requires an uploaded image when enabled.
Shown on the kiosk after the configured idle minutes; touching the screen returns to ordering.

Property	Value
Field ID	`menu_item_columns`
Label	Menu Item Columns
Type	Select
Options	2, 3
Default	2

Description: Number of columns used to lay out menu items in the customer flow.

Order Number Display

Property	Value
Field ID	`order_number_display`
Label	Order Number Display
Type	Radio
Options	`queue_number`, `order_number`, `both`
Default	`both`

Description: Which identifier is shown to the customer after an order is placed — the queue number, the order number, or both.

Customer Identification

Property	Value
Field ID	`allow_customer_identification`, `customer_identification_methods`
Label	Allow Customer Identification
Type	Toggle + method toggles
Methods	`member_code`, `email`, `phone`

Description: When enabled, customers can identify themselves at the kiosk using the enabled methods; with loyalty active, identified customers see their points and rewards.

Sell Without Stock

Property	Value
Field ID	`sell_without_stock`
Label	Sell Without Stock
Type	Toggle
Default	false

Description: Whether out-of-stock items can still be ordered at the kiosk.

Property	Value
Field ID	`use_pager`, `pager_instructions`
Label	Use Pager
Type	Toggle + instructions

Description: Whether the kiosk hands out a pager and the instructions shown to the customer.

Reset Language On Order Complete

Property	Value
Field ID	`reset_language_on_order_complete`
Label	Reset Language On Order Complete
Type	Toggle
Default	false

Description: Whether the kiosk resets to the default language after an order completes.

Upsell Suggestions

Upsell suggestions on the kiosk are not a device-profile toggle. They are configured separately as Upsell Groups (Marketing → Upsell Groups). Active groups for the location are served to the kiosk and suggested during ordering. See the Upsell Groups feature for setup, triggers, and display surfaces.

Note on tipping: Tip collection is not a device-profile field. Tipping is read from the location's in-house settings (collect_tips) and surfaced to the kiosk from there.

Dining Options

Each profile has two dining-option slots, dining_option_1 and dining_option_2, each a select from For Here, Takeout, or None. Setting a slot to None means customers are not asked to choose and all kiosk orders are labelled with the other option.

Dining Option 1

Property	Value
Field ID	`dining_option_1`
Label	Dining Option 1
Type	Select
Options	For Here, Takeout, None
Required	Yes

Dining Option 2

Property	Value
Field ID	`dining_option_2`
Label	Dining Option 2
Type	Select
Options	For Here, Takeout, None
Required	Yes

Custom Dining Option Pictures

Property	Value
Field ID	`use_custom_pictures_for_dining_options`
Label	Use Custom Pictures
Type	Toggle
Default	false

Description: When enabled, you can upload a custom image for each non-None dining option; otherwise default plate/shop images are used.

Business Logic

Kiosk Order Flow

Customer approaches kiosk
        │
        ▼
Welcome / home screen (language selection)
        │
        ▼
Dining option: "For Here" / "Takeout"
(skipped if a slot is set to None)
        │
        ▼
Browse categories
        │
        ▼
Select item → Customize (modifiers)
        │
        ▼
Add to cart → Continue or Checkout
        │
        ▼
Review order
        │
        ▼
Tips (if enabled on the location's in-house settings)
        │
        ▼
Payment:
├── Card → Terminal activated
│         Customer taps/inserts card
│         Payment processed
│
└── Cash → Receipt printed
          Pay at counter
        │
        ▼
Order confirmation
- Order number displayed
- Receipt printed
        │
        ▼
Order sent to KDS
        │
        ▼
Return to welcome screen

Device Registration

New kiosk device
        │
        ▼
Install kiosk app
        │
        ▼
Enter registration code (from backoffice)
        │
        ▼
Device registered and configured
        │
        ▼
Download menu and settings
        │
        ▼
Ready for customers

Offline Mode

Network disconnected
        │
        ▼
Kiosk enters offline mode:
- Cached menu still available
- Orders queued locally
- Card payments may fail
        │
        ▼
Network restored
        │
        ▼
Queued orders synced

Customer Impact

Kiosk Experience

Welcome: Language selection, start order
Dining: Choose "For Here" or "Takeout" (skipped if a slot is set to None)
Menu: Browse categories, view items
Item: See details, select modifiers
Cart: Review, modify quantities
Checkout: Tips (if enabled on the location), payment
Confirmation: Queue/order number, receipt

Accessibility

Large touch targets
Multiple languages
Clear visual feedback

Relations

Depends On

Locations: Kiosk serves a location's data
Device Profiles: Profile supplies the kiosk's menu(s) and settings
Menus: Served via the device profile (default + extra menus)
Payment Terminals: For card payments

Affects

Transactions: Orders created
KDS: Orders sent to kitchen
Inventory: Stock decremented
Reports: Kiosk sales tracked

Business Rules

A kiosk device cannot be deleted while it has an active subscription; the subscription must be cancelled first and deletion is only possible the following billing cycle.
Activation code resend is rate-limited: after 3 resends within the cooldown window (default 15 minutes), further requests are blocked until the cooldown expires.
If a completed transaction already exists for a given idempotency key, the system returns the existing order details instead of creating a duplicate.
Kiosk orders use optimistic locking on the payment flow, publishing status updates (Submitting, Processing, Succeeded, Failed, Canceled) to the device in real time via Firebase.
Tip validation enforces that a request cannot specify both a tip percentage and a tip amount simultaneously; only one is accepted per transaction.

FAQs

"How does a kiosk connect to the backend?" The kiosk app is activated by entering a one-time activation code from the backoffice, which registers the device and downloads location-specific menu data and settings.
"Can different kiosks at the same location show different menus?" Yes. Menus live on the device profile (default menu plus scheduled extra menus), so assigning kiosks to different profiles gives them different offerings and settings.
"What happens if the network drops during a kiosk payment?" The system tracks payment sessions via idempotency keys; when connectivity returns, it checks session status with the payment provider and either completes or cancels the transaction accordingly.
"How is kiosk pricing structured?" The first kiosk at a location has a specific subscription price tier; each additional kiosk uses a separate (typically lower) per-unit price tier, both managed through Stripe.
"Can I remotely restart a kiosk?" Yes. The backoffice can send remote-control commands (restart, logout, firmware update, update APK) to a Kiosk device; the command is delivered over Firebase Cloud Messaging (FCM).
"How do I activate a new kiosk after creating it in the back office?" Create the kiosk device in Device Management, then generate an activation code. On the kiosk tablet, enter that activation code to pair the device; you can copy the code or send it by email/phone from the activation dialog.
"I keep getting an error when resending the activation code — why?" Activation-code resends are rate-limited. After 3 resends within the cooldown window (15 minutes by default), further resends are blocked and the back office tells you how many minutes remain.
"Where do I assign which menu shows on a kiosk?" Menus are set on the device profile, not the device itself. In Device Management → Profiles → edit profile → Menus, add a default menu (always available), then optionally add extra menus scheduled for specific days/times.
"Can two kiosks at the same location run different menus or settings?" Yes. Each kiosk is assigned a device profile, and the profile controls its menus, dining options, idle behaviour and more, so kiosks pointed at different profiles behave differently.
"How do I connect a card terminal to a kiosk?" Card terminals are paired per device in the device's Reader / Terminal section. Depending on your payment provider you pair a Stripe Terminal reader (enter the code shown on the reader, e.g. pheno-blue-kayak), assign a Viva Wallet terminal from the list, or generate a pairing code to enter on a Square Terminal.
"How do I unpair or rename a Stripe Terminal reader from a kiosk?" Open the device's Reader section and choose Edit. There you can rename the reader's label or Unpair it; unpairing removes it from Stripe and the device needs a new pairing before it can take card payments again.
"What's the difference between Idle Timeout and the Idle Screensaver?" They're separate settings in the profile's Idle Settings. Idle Timeout ends an in-progress session and clears entered data after inactivity (returning to the home screen), while the Idle Screensaver displays custom content on an untouched home screen until someone taps it.
"How do I set the idle timeout, and can I keep the default?" In Device Management → Profiles → edit profile → Idle Settings, choose Standard (warning after 45 seconds, shown for 15 seconds) or Custom, where you set your own "give warning after" and "show warning for" seconds.
"How do I turn on the screensaver and how soon does it appear?" In the profile's Idle Settings, enable Idle Screensaver, set the Show after value in minutes, and upload a Screensaver Image. It appears on the idle home screen after that many minutes and disappears when someone interacts with the kiosk.
"What dining options can customers pick at the kiosk?" Each profile has two dining-option slots configured in Dining Options, chosen from For Here, Takeout, or None. Setting an option to None means customers aren't asked to choose, and all kiosk orders are labelled with the other option.
"Can I schedule when a kiosk powers on and off?" Yes, in the profile's Schedule section. Choose Default to match your location's operating hours, Custom to set your own on/off times, or deactivate the schedule to keep the device on 24/7. A 10-minute buffer is applied before opening and after closing.
"Why does my kiosk show as Offline even though it seems on?" A kiosk is treated as Offline if it isn't activated, hasn't checked in, or hasn't been seen within the offline threshold (15 minutes by default). Check the device's network/connectivity and confirm it's powered on and connected.
"Can customers identify themselves at the kiosk for loyalty?" Yes, if you enable Allow customer identification in the profile's Customer Flow settings. You choose which methods are available — member code, email, or phone — and when loyalty is active, identified customers see their points and rewards.

Troubleshooting

Causes:

No device profile assigned, or the profile has no default menu
Menu has no items
Network connectivity issue
App needs update

Solutions:

Assign a device profile and set its default menu
Add items to the menu
Check network connection
Update kiosk app

Problem: Payment terminal not working

Causes:

Terminal not paired
Terminal offline
Wrong terminal assigned
Payment provider issue

Solutions:

Pair terminal in settings
Check terminal power/network
Verify terminal assignment
Check Stripe/Viva dashboard

Problem: Receipts not printing

Causes:

Printer offline
Paper out
Receipt options disabled on the profile
Connection issue

Solutions:

Check printer power/status
Refill paper
Enable the print receipt option / auto-print on the device profile
Check USB/network connection

Problem: Kiosk keeps resetting

Causes:

Idle timeout too short
App crashing
Network drops

Solutions:

Use the Standard idle setting, or raise the Custom "give warning after" value
Check app logs, update app
Improve network stability

Problem: Orders not appearing in KDS

Causes:

KDS not configured
Network issue
Order not completing

Solutions:

Set up KDS for location
Check network
Verify order completes (payment success)

Examples

Basic Kiosk Setup

json

{
  "device": {
    "name": "Kiosk 1 - Entrance",
    "location_id": "loc-123",
    "device_profile_id": "profile-main",
    "viva_wallet_terminal_id": "viva-term-1"
  },
  "profile": {
    "name": "Main Kiosk Profile",
    "location_id": "loc-123",
    "custom_default_menu": true,
    "default_menu_id": "menu-main",
    "extra_menu_ids": [],
    "dining_option_1": "For Here",
    "dining_option_2": "Takeout",
    "use_custom_pictures_for_dining_options": false,
    "idle_timeout_type": "standard",
    "idle_timeout_seconds": 45,
    "show_warning_for_seconds": 15,
    "idle_screensaver": { "enabled": false, "minutes": null },
    "menu_item_columns": 2,
    "order_number_display": "both"
  }
}

Fast Food Profile (Custom Idle, Both Numbers)

json

{
  "profile": {
    "name": "Fast Food",
    "dining_option_1": "For Here",
    "dining_option_2": "Takeout",
    "idle_timeout_type": "custom",
    "idle_timeout_seconds": 60,
    "show_warning_for_seconds": 15,
    "menu_item_columns": 3,
    "order_number_display": "both",
    "sell_without_stock": false
  }
}

Takeout-Only Profile (No "For Here")

json

{
  "profile": {
    "name": "Takeout Only",
    "dining_option_1": "Takeout",
    "dining_option_2": "None",
    "idle_timeout_type": "standard",
    "menu_item_columns": 2,
    "order_number_display": "queue_number"
  }
}

Profile with Idle Screensaver + Customer Identification

json

{
  "profile": {
    "name": "Cafe Kiosk",
    "dining_option_1": "For Here",
    "dining_option_2": "Takeout",
    "idle_timeout_type": "standard",
    "idle_screensaver": { "enabled": true, "minutes": 5 },
    "screensaver_content_id": "content-screensaver-1",
    "menu_item_columns": 2,
    "order_number_display": "order_number",
    "allow_customer_identification": true,
    "customer_identification_methods": { "member_code": true, "email": false, "phone": false }
  }
}

Kiosk Setup ​

Overview ​

Purpose ​

Key Concepts ​

Actions ​

Register a New Kiosk ​

Assign a Payment Terminal ​

Configure a Device Profile ​

Send Remote Commands ​

Cancel a Kiosk Transaction ​

Location ​

Concepts ​

Kiosk Device ​

Device Profile ​

Kiosk Mode ​

Kiosk Device Fields ​

Device Name ​

Assigned Location ​

Device Profile ​

Payment Terminal ​

Device Status ​

Device Profile Fields ​

Profile Name ​

Location ​

Default Menu ​

Extra Menus ​

Idle Timeout ​

Idle Screensaver ​

Menu Item Columns ​

Order Number Display ​

Customer Identification ​

Sell Without Stock ​

Pager ​

Reset Language On Order Complete ​

Upsell Suggestions ​

Dining Options ​

Dining Option 1 ​

Dining Option 2 ​

Custom Dining Option Pictures ​

Business Logic ​

Kiosk Order Flow ​

Device Registration ​

Offline Mode ​

Customer Impact ​

Kiosk Experience ​

Accessibility ​

Relations ​

Depends On ​

Affects ​

Related Features ​

Business Rules ​

FAQs ​

Troubleshooting ​

Problem: Kiosk showing blank/no menu ​

Problem: Payment terminal not working ​

Problem: Receipts not printing ​

Problem: Kiosk keeps resetting ​

Problem: Orders not appearing in KDS ​

Examples ​

Basic Kiosk Setup ​

Fast Food Profile (Custom Idle, Both Numbers) ​

Takeout-Only Profile (No "For Here") ​

Profile with Idle Screensaver + Customer Identification ​

Kiosk Setup

Overview

Purpose

Key Concepts

Actions

Register a New Kiosk

Assign a Payment Terminal

Configure a Device Profile

Send Remote Commands

Cancel a Kiosk Transaction

Location

Concepts

Kiosk Device

Device Profile

Kiosk Mode

Kiosk Device Fields

Device Name

Assigned Location

Device Profile

Payment Terminal

Device Status

Device Profile Fields

Profile Name

Location

Default Menu

Extra Menus

Idle Timeout

Idle Screensaver

Menu Item Columns

Order Number Display

Customer Identification

Sell Without Stock

Pager

Reset Language On Order Complete

Upsell Suggestions

Dining Options

Dining Option 1

Dining Option 2

Custom Dining Option Pictures

Business Logic

Kiosk Order Flow

Device Registration

Offline Mode

Customer Impact

Kiosk Experience

Accessibility

Relations

Depends On

Affects

Related Features

Business Rules

FAQs

Troubleshooting

Problem: Kiosk showing blank/no menu

Problem: Payment terminal not working

Problem: Receipts not printing

Problem: Kiosk keeps resetting

Problem: Orders not appearing in KDS

Examples

Basic Kiosk Setup

Fast Food Profile (Custom Idle, Both Numbers)

Takeout-Only Profile (No "For Here")

Profile with Idle Screensaver + Customer Identification