Payment Provider Setup Guide

Overview

Upvendo supports multiple payment providers, each serving different use cases. This guide helps you choose the right provider and walk through setup for each.

Quick Decision Matrix

Question	Stripe	Viva Wallet	Square
Online card payments?	Yes	No	Yes
iDEAL (Netherlands)?	Yes	No	No
Bancontact (Belgium)?	Yes	No	No
Kiosk terminal payments?	Via Stripe Terminal	Yes (EU focus)	Yes
Full POS integration?	No	No	Yes
Subscription billing?	Yes	No	No
Region focus	Global	EU (esp. Greece, Southern Europe)	US, UK, EU

---

Stripe

When to Use

• You need online ordering payments (card, iDEAL, Bancontact)
• You need Stripe Terminal for in-store card readers
• You need to handle subscription billing for the Upvendo platform itself
• You are in the Netherlands or Belgium and need local payment methods

Prerequisites

• Stripe account (standard or connected account via Stripe Connect)
• Business verification completed in Stripe Dashboard
• Bank account linked for payouts

Setup Steps

1. Navigate to Settings > Payments > Stripe
2. Click Connect with Stripe
3. Complete the Stripe Connect OAuth flow
4. Authorize Upvendo to access your Stripe account
5. Verify the connection status shows "Connected"
6. Enable desired payment methods:
   • Card payments (Visa, Mastercard, etc.)
   • iDEAL (Netherlands bank transfers)
   • Bancontact (Belgium bank cards)

Configuration Options

Setting	Description	Default
Card Payments	Accept Visa, Mastercard, Amex	Enabled
iDEAL	Dutch bank transfer method	Disabled
Bancontact	Belgian bank card method	Disabled
Cash on Pickup	Allow cash for pickup orders	Disabled
Cash on Delivery	Allow cash for delivery orders	Disabled

How It Works

Customer places online order
    |
    v
Checkout shows enabled payment methods
    |
    v
Customer selects payment method
    |
    +---> Card: Stripe Payment Intent created
    +---> iDEAL: Redirect to bank
    +---> Bancontact: Redirect to bank
    |
    v
Payment confirmed via Stripe webhook
    |
    v
Order marked as paid, sent to kitchen/POS

Important Notes

• Stripe is the default payment provider for online ordering
• When Square is connected, Square Payments replaces Stripe for all channels
• Stripe handles the Upvendo platform subscription billing separately from merchant payments
• Payouts go directly to the merchant's connected Stripe account

---

Viva Wallet

When to Use

• You need kiosk terminal payments in the EU
• You are using a POS integration (Hendrickx, MplusKassa, Lightspeed) that does not include payment processing
• You prefer a European payment provider with strong EU presence
• You need in-store card terminal support without Stripe Terminal

Prerequisites

• Viva Wallet merchant account
• Viva Wallet API credentials (Merchant ID, API Key)
• Compatible card terminal hardware
• Terminal paired with Viva Wallet account

Setup Steps

1. Navigate to Settings > Payments > Viva Wallet
2. Enter your Merchant ID
3. Enter your API Key
4. Click Save to connect
5. Navigate to Devices > Kiosks to assign the terminal to a kiosk device
6. Pair the physical terminal from the Viva Wallet terminal management interface

Configuration Options

Setting	Description	Default
Merchant ID	Viva Wallet merchant identifier	Required
API Key	Viva Wallet API authentication key	Required
Terminal ID	Physical terminal identifier	Per device
Tips Enabled	Allow tips on terminal	Disabled

How It Works

Customer completes kiosk order
    |
    v
Kiosk shows "Tap or insert card"
    |
    v
Viva Wallet terminal activated
    |
    v
Customer taps/inserts card
    |
    v
Viva Wallet processes payment
    |
    v
Payment confirmed, receipt printed
    |
    v
Order sent to kitchen/KDS

Important Notes

• Viva Wallet is primarily for in-store terminal payments, not online payments
• When Square is connected, Square Payments replaces Viva Wallet
• Each kiosk device needs its own terminal assignment
• Terminal must be online and paired before accepting payments

---

Square

When to Use

• You want a complete POS integration with built-in payments
• You want one provider for both online and in-store payments
• You are migrating from or already using Square POS
• You need payments + menu sync + order management in one integration

Prerequisites

• Square merchant account
• Square POS set up with at least one location
• Menu items configured in Square (will be imported to Upvendo)

Setup Steps

1. Navigate to Integrations > Square
2. Click Connect with Square
3. Complete the Square OAuth flow
4. Authorize Upvendo to access your Square account
5. Square locations are automatically imported as Upvendo locations
6. Menu items synced from Square to Upvendo
7. Payment processing is automatically enabled (no separate payment profile needed)

Configuration Options

Setting	Description	Default
Sync Direction	Upvendo-to-Square, Square-to-Upvendo, or bidirectional	Square-to-Upvendo
Auto-sync Menu	Automatically sync menu changes	Enabled
Terminal Payments	Use Square Terminal for kiosk	Enabled
Online Payments	Use Square for online ordering checkout	Enabled

How It Works

Square connected via OAuth
    |
    v
Locations + Menu imported from Square
    |
    v
All payment channels route through Square:
    +---> Online Ordering: Square Web Payments SDK
    +---> Kiosk: Square Terminal API
    |
    v
Orders synced back to Square POS
    |
    v
Square handles payouts to merchant bank account

Important Notes

• Square replaces both Stripe and Viva Wallet when connected
• The isSquareIntegrated() check in PaymentService routes all payments through Square
• No separate payment profile setup is needed -- Square handles everything
• Menu sync is bidirectional: changes in either system can propagate

---

Choosing the Right Provider

Scenario 1: Online Ordering Only (Netherlands/Belgium)

Recommended: Stripe

• Supports iDEAL (popular in NL) and Bancontact (popular in BE)
• No in-store hardware needed
• Fast setup via Stripe Connect

Scenario 2: Kiosk with POS Integration (EU)

Recommended: Viva Wallet + POS Integration (Hendrickx/MplusKassa/Lightspeed)

• Viva Wallet handles kiosk terminal payments
• POS integration handles menu sync and order forwarding
• Stripe can be added alongside for online ordering

Scenario 3: All-in-One POS + Payments

Recommended: Square

• Single integration for payments, menu, and orders
• No need for separate Stripe or Viva Wallet setup
• Best when Square is already the primary POS

Scenario 4: Multiple Channels (Online + Kiosk) without POS

Recommended: Stripe (online) + Viva Wallet (kiosk terminals)

• Stripe for online card payments and local methods
• Viva Wallet for in-store terminal payments
• Both can coexist when Square is not connected

---

Common Issues

"Payment could not be processed"

• Check that the payment provider is connected and credentials are valid
• Verify the customer's payment method is enabled in settings
• Check the Stripe/Viva Wallet/Square dashboard for declined transactions

Terminal not responding (Kiosk)

• Verify the terminal is powered on and connected to the network
• Check terminal assignment in Devices > Kiosks
• Restart the terminal and re-pair if needed
• Confirm the terminal firmware is up to date

Missing payment methods at checkout

• Verify the payment methods are enabled in Settings > Payments
• Check that the correct payment provider is connected for the channel
• For Square merchants: ensure Square connection is active (replaces other providers)