Payment Profiles

Overview

Payment profiles define how customers can pay for orders. A profile is created with just a Name and a Country; you then set up its payment providers on the profile detail page. Each profile can use Stripe (for online ordering payments) and/or Viva Wallet (for kiosk/in-person terminal payments). Profiles are assigned to locations. When Square POS is connected, Square handles payments and payment profiles are not used.

Purpose

This page lets you create and manage payment profiles. Creating a profile captures a name and country; the providers (Stripe for online ordering, Viva Wallet for kiosk) are configured afterward on the profile's detail page and determine how payments are processed at each location.

Key Concepts

Payment Profile: A named, country-scoped configuration that holds the merchant's Stripe (online ordering) and Viva Wallet (kiosk/in-person) connections, assigned to locations
Stripe: Payment provider for online ordering customer payments, via a per-profile Stripe connected account. Online ordering always uses Stripe (when Square is not connected). Stripe is also used for platform subscription billing, but on payment profiles it processes customer online-ordering payments.
Viva Wallet: Payment provider for kiosk / in-person card-terminal payments. Set up per profile via a Viva Wallet connected account (ISV model).
Square Payments: When Square POS is connected, payments are handled automatically by Square — no payment profile needed (the New Profile button and the Payments page configuration are hidden)
Test Mode: A per-location payment_test_mode flag (toggled on the profile detail page) that simulates payments for both Stripe and Viva without real charges

Route

Backoffice Route: /settings/payments (list)
Add Profile: opens the New Payment Profile modal dialog (no dedicated route)
Profile Detail: /settings/payments/profiles/:id
Payouts: /settings/payments/payouts/:id and /settings/payments/payouts/:id/detail/:payoutId

Actions

Create Payment Profile

Click "New Profile" to open the New Payment Profile dialog, enter a Name and Country, and click "Setup Profile". You are then taken to the profile detail page to set up Stripe and/or Viva Wallet.

Edit Payment Profile

Open a profile to rename it, set it as default, and configure its Stripe and Viva Wallet accounts.

Delete Payment Profile

Delete a profile if it's not assigned to any location.

Assign to Location

After creating a profile, assign it to locations via Settings → Locations → Payment Profile.

Payment Provider Architecture

Provider by Channel

Channel	Payment Provider	Notes
Online Ordering	Stripe	Customer web payments through a per-profile Stripe connected account (cards, iDEAL, Bancontact, Klarna, etc.)
Kiosk / In-Person	Viva Wallet	Physical card terminal payments through a per-profile Viva Wallet connected account
Square POS	Square Payments	Automatic — no profile needed (overrides Stripe and Viva Wallet when connected)

Note: When Square is not connected, online-ordering customer payments always run through Stripe and kiosk/in-person payments run through Viva Wallet. Both are configured per payment profile on the profile detail page.

Square Integration

When Square POS is connected, Square handles all payments automatically:

No payment profile creation required (the New Profile button and Payments configuration are hidden)
Payments processed through Square
Unified with Square POS system

Stripe (Online Ordering Payments)

Important: On a payment profile, Stripe processes customer online-ordering payments via a Stripe connected account. Stripe is set up on the profile detail page through a Stripe onboarding flow (no API keys are entered in the back office). The connected account also surfaces payouts, statement descriptors, a business-website field, and payment-method capabilities. (Stripe additionally powers platform subscription billing elsewhere, but on payment profiles it handles online-ordering payments.)

Fields

New Payment Profile dialog

The New Payment Profile dialog has only two inputs. There is no in-person-provider selector, no credential fields, and no toggles here — providers are configured afterward on the detail page.

Field	Field ID	Type	Required	Notes
Name	`name`	Text	Yes	Must be unique among the merchant's payment profiles
Country	`country`	Select	Yes	One of Upvendo's supported countries (United States is excluded from the list)

The request also accepts an optional return_url, which is used internally for provider onboarding redirects and is not a visible form field.

Viva Wallet account (kiosk / in-person)

Viva Wallet is set up on the profile detail page (Setup Viva Wallet Account), which creates a Viva Wallet connected account via Upvendo's ISV integration. Merchants complete onboarding on Viva's own dashboard; the back office displays read-only account details:

Account ID (viva_wallet.accountId)
Merchant ID (viva_wallet.merchantId)
Email, Acquiring Enabled, Legal Name, VAT Number

There are no merchant-entered Viva merchant-ID/API-key/source-code fields in the back office; these are managed on Viva's side. (Per-location Viva source codes are deprecated — see Business Rules.)

Card Terminals (Pairing a Reader to a Device)

Physical card terminals are paired to a device (such as a kiosk), not to the payment profile. This is how you "add a terminal to a kiosk".

Where: Device Management → Devices → open the device → Card Reader / Terminal section → Add Terminal (labelled Pair Reader for Stripe in-person).

The pairing method depends on the location's in-person payment provider:

Viva Wallet: Choose Assign Viva Terminal, then select the terminal from the list of terminals available on your Viva account and save. The device then takes card payments through that Viva terminal.
Stripe (in-person): Choose Pair Reader, enter the reader's registration code (and an optional label), and pair. You can later rename or unpair the reader.
Square: When Square is connected, pair a Square Terminal using the device code shown in the dialog.

After pairing, the device's Card Reader section shows the terminal ID and its status. Each device can have one paired reader at a time.

Business Rules

A terminal is paired per device — a kiosk takes payments through the reader paired to it.
The available pairing method follows the location's in-person provider (Viva Wallet, Stripe in-person, or Square).
Requires the edit devices permission.

Test Mode (per location)

Test mode is not a payment-profile field — it is a per-location flag, toggled from the profile detail page's Locations list.

Property	Value
Field ID	`payment_test_mode` (on the location)
Type	Toggle (per location)
Default	false

Description: When enabled for a location, payments run in test/simulation mode for both Stripe and Viva — no real charges are made, but orders still process normally. A "TEST MODE" badge is shown.

Tips

Tips are not configured on the payment profile. Tip collection lives on the location/device Collect Tips settings, where you enable tip collection, set the percentage options (default 10 / 15 / 20), and choose whether tips are calculated after or before taxes. See the Locations feature for details.

Business Rules

Two channels per profile: A profile holds a Stripe connected account (online ordering) and a Viva Wallet connected account (kiosk/in-person); each is set up separately on the detail page
One profile per location: Each location has exactly one payment profile assigned
Square overrides both: When Square POS is connected (isSquareIntegrated() returns true), Square handles payments automatically — Stripe and Viva Wallet are bypassed, and the New Profile button / Payments configuration are hidden
Unique name: A profile name must be unique among the merchant's profiles
Test mode is per location: The payment_test_mode flag is set per location (on the detail page), not on the profile
Default profile: A profile can be marked as default; it must be Viva-verified to be set as default
Viva Wallet ISV model: Upvendo connects to Viva Wallet as an ISV partner, using platform-level client credentials with per-merchant connected accounts
Viva source codes deprecated: Per-location Viva online/physical source codes are no longer generated; existing values are preserved and new locations use the 'Default' source code
Profile deletion: Cannot delete a profile that's assigned to a location
Changes take effect:
- Online Ordering: Immediately on next page load
- Kiosk: After app sync/reload

Logic Flows

Payment Flow (Online Ordering — Stripe)

Customer completes order
        │
        ▼
Stripe payment created on the profile's connected account
        │
        ▼
Customer pays via Stripe (cards + local methods)
├── Card → Enter card details
├── iDEAL (NL)
├── Bancontact (BE)
├── Klarna (DE)
│
        ▼
Payment confirmed / verified
        │
        ▼
Order confirmed

Note: For free orders (total = 0), no payment provider is involved and the order is marked complete automatically. If Square is connected, online-ordering payments go through Square instead of Stripe.

Payment Flow (Kiosk with Viva Wallet)

Customer completes order
        │
        ▼
Card Terminal activated
        │
Customer taps/inserts card
        │
Payment processed
        │
Receipt printed

Customer Impact

Online Ordering: Stripe checkout (or Square if connected); available methods depend on the connected account's enabled capabilities
Kiosk: Card terminal payment via Viva Wallet (or Square if connected)
Receipts: Payment method and transaction ID printed
Tips: Tip selection shown if enabled at the location/device level

FAQs

"What is a payment profile?" A payment profile in Upvendo is a named, country-scoped configuration that holds your Stripe connected account (for online-ordering payments) and your Viva Wallet connected account (for kiosk/in-person payments), and is assigned to one or more locations. It determines how payments are processed at each location.
"How do I add a payment profile?" Go to Settings → Payments, click "New Profile", enter a Name and Country, and click Setup Profile. On the profile detail page, set up Stripe (online ordering) and/or Viva Wallet (kiosk). Then assign the profile to locations in Settings → Locations so it takes effect.
"What is Stripe used for?" On a payment profile, Stripe processes your online-ordering customer payments through a Stripe connected account. (Stripe also powers Upvendo's platform subscriptions, but on payment profiles it handles online-ordering payments.) Kiosk/in-person payments use Viva Wallet, and when Square is connected Square handles everything.
"Why don't I see payment settings for Square?"
When Square POS is connected, Square handles payments automatically and the Payments page does not expose detailed Square configuration. In that case, you typically do not create payment profiles for Square; you manage payments directly in Square.
"How do I enable iDEAL for Dutch customers?" For online ordering, iDEAL and other local methods are enabled through your Stripe connected account's capabilities for the country. (Viva Wallet has its own per-country default method via getDefaultPaymentMethodByCountryCode — iDEAL for NL — for any Viva-driven checkout.)
"Can I have different payment methods per location?"
Yes. Create multiple payment profiles and assign the appropriate profile to each location in Settings → Locations. Each location can have exactly one active payment profile at a time.
"How do I enable tips?"
Tips are not part of the payment profile. Enable them under the location/device Collect Tips settings, where you turn on tip collection, set the percentage options (default 10 / 15 / 20), and choose whether tips are calculated before or after taxes.
"What's the difference between test and live mode?"
Test mode is a per-location setting (payment_test_mode), toggled on the profile detail page's Locations list. When enabled, payments are simulated for both Stripe and Viva — no real charges — while orders still process normally. Verify your setup in test mode before switching the location to live.
"How do I create a payment profile?" Go to Settings → Payments and click "New Profile" (the button is hidden if your account is integrated with Square). In the New Payment Profile dialog you set two things: a Name and a Country. Click Setup Profile to create it, then configure Stripe and/or Viva Wallet on the profile detail page.
"Where do I enter my Viva Wallet merchant ID, API key, and source codes?" You don't enter those in the payment profile form — the New Profile dialog only captures a name and country. Viva Wallet onboarding happens on Viva's own dashboard (the back office shows read-only Account ID and Merchant ID details), and per-location source codes are deprecated (new locations use 'Default').
"Do I have to pick the in-person provider when creating a profile?" No. The New Profile dialog only asks for a name and country — there is no in-person-provider choice there. Online ordering uses Stripe and kiosk/in-person uses Viva Wallet; each is set up afterward on the profile detail page (Setup Stripe Account / Setup Viva Wallet Account).
"Which provider handles my online-ordering payments?" Online ordering runs through Stripe (via your profile's Stripe connected account) when Square is not connected. Kiosk/in-person card payments run through Viva Wallet. If Square is connected, Square handles all payments.
"How do I assign a payment profile to a location?" Go to Settings → Locations, open the location, and choose the profile in the Payment Profile field. Once a location has a saved payment profile, the field locks to that profile in this screen, so set it carefully. (It's hidden entirely when your account is Square-integrated.)
"How do I pair a card reader to a kiosk?" Go to Device Management → Devices, open the device, and use the Reader section. The flow follows the location's in-person provider: Pair reader for Stripe (enter the reader's three-word registration code like pheno-blue-kayak, plus an optional label), Assign Viva Terminal for Viva (pick a terminal from the list), or Pair Square Terminal for Square (generate a code and enter it on the Square device).
"Why don't I see the New Profile button or payment settings?" If your account is integrated with Square, the back office hides the New Profile button and shows a "Square Payment Integration Active" notice — payment-profile setup isn't required because Square handles payments directly.
"How do I turn on tips for my customers?" Tips aren't part of the payment profile. They're configured under the location's/device's Collect Tips settings, where you enable tip collection, set the percentage options (default 10 / 15 / 20), and choose whether tips are calculated after or before taxes.
"Can I test payments before going live?" Yes. Each location has a payment test mode setting; when enabled, transactions run in test/simulation mode for Stripe and Viva without real charges. Verify your setup in test mode before switching the location to live.
"What payment method will Dutch / Belgian customers see by default in Viva online checkout?" For Viva Wallet online checkout the default method is pre-selected by country: iDEAL for the Netherlands, Bancontact for Belgium, Klarna for Germany, and Multibanco for Portugal; other countries default to card.
"What happens to a €0 order?" Free orders (total of 0) skip the payment provider entirely — no Stripe/Viva/Square charge is attempted, and the order is marked complete automatically.

Troubleshooting

Online payments failing → Check that the profile's Stripe connected account has completed onboarding and has no outstanding requirements
Kiosk/terminal payments failing → Check the profile's Viva Wallet account is verified, and check the location's test-mode setting
iDEAL / local methods not showing online → Confirm the corresponding capability is active on the Stripe connected account
Tips not appearing → Tips are enabled at the location/device Collect Tips settings, not in the payment profile
Can't delete profile → Unassign from all locations first
Square payments not working → Check Square POS connection in integrations

Assistant Guidance

When answering questions about payments:

Clarify the channel: online ordering uses Stripe, kiosk/in-person uses Viva Wallet, and Square overrides both when connected
For Square users: explain that payments are automatic, no profile needed
For Stripe (online ordering): direct them to the Setup Stripe Account flow on the profile detail page; no API keys are entered in the back office
For Viva Wallet (kiosk): direct them to Setup Viva Wallet Account; onboarding completes on Viva's dashboard
The New Profile dialog only asks for a Name and Country — do NOT describe an in-person-provider selector or credential fields there
Tips and test mode live at the location level, not on the payment profile
Always mention that profiles must be assigned to locations to take effect

Relations

Depends On

Locations: Payment profiles are assigned to locations
Stripe Account: A per-profile Stripe connected account is required for online-ordering customer payments
Viva Wallet Account: A per-profile Viva Wallet connected account is required for kiosk/in-person payments
Square Integration: When connected, overrides both Stripe and Viva Wallet for all payment flows

Affects

Online Ordering: Stripe checkout and available payment methods
Kiosk: Viva Wallet terminal payment options
Transactions: Payment records and refunds
Reports: Payment method breakdown

Payment Profiles ​

Overview ​

Purpose ​

Key Concepts ​

Route ​

Actions ​

Create Payment Profile ​

Edit Payment Profile ​

Delete Payment Profile ​

Assign to Location ​

Payment Provider Architecture ​

Provider by Channel ​

Square Integration ​

Stripe (Online Ordering Payments) ​

Fields ​

New Payment Profile dialog ​

Viva Wallet account (kiosk / in-person) ​

Card Terminals (Pairing a Reader to a Device) ​

Business Rules ​

Test Mode (per location) ​

Tips ​

Business Rules ​

Logic Flows ​

Payment Flow (Online Ordering — Stripe) ​

Payment Flow (Kiosk with Viva Wallet) ​

Customer Impact ​

FAQs ​

Troubleshooting ​

Assistant Guidance ​

Relations ​

Depends On ​

Affects ​

Payment Profiles

Overview

Purpose

Key Concepts

Route

Actions

Create Payment Profile

Edit Payment Profile

Delete Payment Profile

Assign to Location

Payment Provider Architecture

Provider by Channel

Square Integration

Stripe (Online Ordering Payments)

Fields

New Payment Profile dialog

Viva Wallet account (kiosk / in-person)

Card Terminals (Pairing a Reader to a Device)

Business Rules

Test Mode (per location)

Tips

Business Rules

Logic Flows

Payment Flow (Online Ordering — Stripe)

Payment Flow (Kiosk with Viva Wallet)

Customer Impact

FAQs

Troubleshooting

Assistant Guidance

Relations

Depends On

Affects