Viva Wallet Integration

Overview

Viva Wallet is the primary payment provider for both online ordering and kiosk terminal payments. For online ordering, Viva Wallet processes web-based payments via payment orders (cards, iDEAL, Bancontact, etc.). For kiosks, physical card terminals attached to kiosks use Viva Wallet for processing.

Key Purpose: Process all customer-facing payments (online ordering and kiosk terminals).

Note: If Square POS is connected, Square Payments is used instead of Viva Wallet for all payment flows.

Purpose

This page lets you configure Viva Wallet credentials, source codes, and terminal devices so customers can pay via online ordering checkout and via physical card terminals at your locations.

Key Concepts

ISV (Independent Software Vendor) Model: Upvendo connects to Viva Wallet as an ISV partner, using platform-level client credentials combined with per-merchant IDs to process payments on behalf of each restaurant.
Terminal Session: Each kiosk payment creates a terminal session identified by an idempotency key; the session is sent to the physical terminal, and its status is polled until the customer taps/inserts their card.
Source Code: A Viva Wallet-specific identifier that determines the payment source type (physical terminal vs online); each location has separate source codes for physical and online payments.
Merchant ID: The Viva Wallet merchant identifier that scopes all API calls to a specific restaurant account, stored per-location in the location settings.
Pre-authorization Capture: For certain channels, Viva Wallet supports pre-auth payments where the amount is held first and captured later, controlled by the isVivaWalletPreauth flag on the transaction.

Actions

Configure Viva Wallet Credentials

Enter the Merchant ID, API Key, API Secret, and Source Code provided by Viva Wallet to authenticate the integration for a specific location.

Register Terminal Devices

Enable the terminal integration and register physical Viva Wallet card readers so they can receive payment requests from kiosk devices.

Switch Between Live and Demo Mode

Toggle between Viva Wallet's production and demo (sandbox) environments. Demo mode uses test API endpoints so no real charges are processed.

Process Kiosk Terminal Payments

When a kiosk order is submitted, the system initiates a terminal sale via Viva Wallet's API, sending the payment amount and tip to the assigned physical terminal for customer card interaction.

When Viva Wallet is Used

Channel	Viva Wallet Used	Source Code Type
Online Ordering	Yes -- web payment orders	Online source code
Kiosk (physical terminal)	Yes -- terminal payments	Physical source code
Table QR Ordering	Yes -- web payment orders	Online source code

Location

Backoffice Route: /settings/payments/viva-wallet
Backend Controller: app/Http/Controllers/Api/VivaWalletController.php
Vue Component: src/views/settings/payments/VivaWalletComponent.vue

Fields

Viva Wallet Enabled

Property	Value
Field ID	`enabled`
Label	Enable Viva Wallet
Type	Toggle
Default	false

Description: Enable Viva Wallet as payment provider.

Merchant ID

Property	Value
Field ID	`merchant_id`
Label	Merchant ID
Type	Text
Required	Yes

Description: Your Viva Wallet merchant ID.

API Key

Property	Value
Field ID	`api_key`
Label	API Key
Type	Password
Required	Yes

Description: API key for authentication.

API Secret

Property	Value
Field ID	`api_secret`
Label	API Secret
Type	Password
Required	Yes

Description: API secret for authentication.

Source Code

Property	Value
Field ID	`source_code`
Label	Source Code
Type	Text
Required	Yes

Description: Payment source code from Viva Wallet.

Live Mode

Property	Value
Field ID	`live_mode`
Label	Live Mode
Type	Toggle
Default	false

Description: Use live (real) payments vs demo mode.

Terminal Settings

Terminal Integration

Property	Value
Field ID	`terminal_enabled`
Label	Enable Terminals
Type	Toggle
Default	false

Description: Use Viva Wallet payment terminals.

Terminals

Property	Value
Field ID	`terminals`
Label	Registered Terminals
Type	List

Description: Connected Viva Wallet terminal devices.

Business Logic

Payment Flow (Online Ordering)

Customer completes online order
        |
        v
System creates Viva Wallet payment order
(using online source code)
        |
        v
Customer redirected to Viva Wallet checkout page
(card, iDEAL, Bancontact auto-selected by country)
        |
        v
Payment confirmed via webhook
        |
        v
Order confirmed

Payment Flow (Kiosk Terminal)

Customer completes kiosk order
        |
        v
System initiates terminal sale
(using physical source code + terminal ID)
        |
        v
Card terminal activated
        |
        v
Customer taps/inserts card
        |
        v
Payment confirmed
        |
        v
Order confirmed

Business Rules

If Square POS integration is active (isSquareIntegrated() returns true), Viva Wallet is bypassed entirely and all payments (both online ordering and kiosk terminal) are routed through Square instead.
Terminal sale initiation uses an idempotency key per transaction; if a 409 conflict occurs (duplicate session), the system generates a new idempotency key and retries the sale automatically.
Payment amounts are converted to the smallest currency unit (cents) using ceil() before being sent to Viva Wallet, ensuring fractional amounts always round up.
The Viva Wallet API base URLs switch automatically between production (vivapayments.com) and demo (demo.vivapayments.com) based on the isProduction flag, which is derived from the application environment.
Each kiosk device stores a latest_idempotency_key that is updated after every terminal sale initiation, allowing the system to track and abort stale sessions if needed.

FAQs

Is Viva Wallet only used for kiosk terminals? No. Viva Wallet handles both online ordering web payments (via payment orders) and kiosk terminal payments (via terminal sales). Each channel uses a different source code: an online source code for web payments and a physical source code for terminal payments.
What happens if the customer does not tap their card? The terminal session remains pending until it times out on Viva Wallet's side. The kiosk can cancel the session and allow the customer to retry or choose a different payment method.
Can I use Viva Wallet and Square terminals at the same location? No, the system checks isSquareIntegrated() at payment time and routes to one provider exclusively. You must disconnect Square to use Viva Wallet.
What countries does Viva Wallet support? Viva Wallet supports EU and US markets. The system uses country-specific configuration (EU vs US client credentials) based on the location's country code.
How are tips handled? Tips are included as a separate tipAmount parameter in the terminal sale request, so the tip is captured as part of the same transaction alongside the order total.

Troubleshooting

Problem: Connection failed

Causes:

Invalid credentials
Wrong merchant ID
API key expired

Solutions:

Verify credentials
Check merchant ID
Generate new API key

Problem: Terminal not responding

Causes:

Terminal offline
Wrong terminal ID
Network issue

Solutions:

Check terminal power
Verify terminal assignment
Check network connection

Examples

Basic Setup

json

{
  "enabled": true,
  "merchant_id": "your-merchant-id",
  "api_key": "your-api-key",
  "api_secret": "your-api-secret",
  "source_code": "your-source-code",
  "live_mode": true,
  "terminal_enabled": true
}

Viva Wallet Integration ​

Overview ​

Purpose ​

Key Concepts ​

Actions ​

Configure Viva Wallet Credentials ​

Register Terminal Devices ​

Switch Between Live and Demo Mode ​

Process Kiosk Terminal Payments ​

When Viva Wallet is Used ​

Location ​

Fields ​

Viva Wallet Enabled ​

Merchant ID ​

API Key ​

API Secret ​

Source Code ​

Live Mode ​

Terminal Settings ​

Terminal Integration ​

Terminals ​

Business Logic ​

Payment Flow (Online Ordering) ​

Payment Flow (Kiosk Terminal) ​

Business Rules ​

FAQs ​

Troubleshooting ​

Problem: Connection failed ​

Problem: Terminal not responding ​

Examples ​

Basic Setup ​