Payment Profiles

Overview

Payment profiles define how customers can pay for orders. A profile is created with a Name, a Country, and a choice of in-person payment provider (Stripe or Viva Wallet); you then complete provider onboarding on the profile detail page. Online-ordering payments always run through Stripe; the in-person (kiosk / card-reader) side runs through whichever provider you picked. 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, a country, and the in-person payment provider; onboarding for Stripe (online ordering) and for the chosen in-person provider is completed afterward on the profile's detail page, and determines how payments are processed at each location.

Key Concepts

Payment Profile: A named, country-scoped configuration that holds the merchant's Stripe (online ordering) connection plus its chosen in-person provider connection, assigned to locations
In-person payment provider (in_person_provider): Chosen when the profile is created — either stripe (Stripe Terminal: same Stripe account for online and in-person) or viva_wallet (a dedicated Viva Wallet account for in-person only). Required, and permanent — the dialog warns "This choice is permanent. You won't be able to change the in-person provider after the profile is created." (Verified: upvendo-backend app/Http/Requests/BackOffice/Settings/Payment/NewPaymentProfileRequest.php lines 47-54; upvendo-backoffice src/views/settings/Payments/NewPaymentProfileDialog.vue lines 33-46 and 171-229; src/plugins/i18n/locales/modules/en/payment-profiles.ts lines 40-58.)
Stripe: Payment provider for online ordering customer payments, via a per-profile Stripe connected account. By default, online ordering uses Stripe (when Square is not connected) — the online provider is set from configuration (ZESTIDOO_PAYMENT_PROVIDER, default stripe), and a Viva Wallet online-checkout path also exists. (Verified: upvendo-backend config/upvendo.php line 5.) Stripe can additionally be the in-person provider (Stripe Terminal) when selected at profile creation. Stripe is also used for platform subscription billing, but on payment profiles it processes customer payments.
Viva Wallet: The alternative in-person provider for kiosk / card-terminal payments. Set up per profile via a Viva Wallet connected account (ISV model). Profiles created before the provider choice existed default to viva_wallet. (Verified: upvendo-backoffice src/views/settings/Payments/PaymentProfileDetail.vue lines 86-91.)
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, pick a Country, choose the In-person payment provider (Stripe or Viva Wallet), and click "Setup Profile". You are then taken to the profile detail page to complete provider onboarding.

Edit Payment Profile

Open a profile to rename it, set it as default, and complete its Stripe (and, for Viva profiles, Viva Wallet) account setup. The in-person provider itself cannot be changed after creation — only name is accepted by the profile update request. (Verified: upvendo-backend app/Http/Requests/BackOffice/Settings/Payment/PaymentProfileRequest.php lines 31-41.)

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	Stripe Terminal or Viva Wallet	Whichever `in_person_provider` was chosen when the profile was created — physical card-terminal payments through that provider's 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 run through Stripe by default (the online provider is configurable, and a Viva Wallet online-checkout path also exists). Kiosk/in-person payments run through the profile's chosen in-person provider — Stripe Terminal or Viva Wallet — picked once at profile creation and not changeable afterward.

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 three inputs. There are no credential fields here — provider onboarding happens afterward on the detail page. (Verified: upvendo-backoffice src/views/settings/Payments/NewPaymentProfileDialog.vue lines 147-230.)

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)
In-person payment provider	`in_person_provider`	Radio cards	Yes	`stripe` (Stripe Terminal — "Use the same Stripe account for online and in-person") or `viva_wallet` ("Keep in-person payments in a separate Viva account"). Permanent — cannot be changed after the profile is created

The request also accepts an optional return_url, which is used internally for provider onboarding redirects and is not a visible form field. (Verified: upvendo-backend app/Http/Requests/BackOffice/Settings/Payment/NewPaymentProfileRequest.php lines 31-55.)

Viva Wallet account (in-person)

On profiles whose in_person_provider is viva_wallet, 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.) On profiles whose in_person_provider is stripe, the Viva Wallet section is not shown at all — in-person payments use the same Stripe connected account as online ordering. (Verified: upvendo-backoffice src/views/settings/Payments/PaymentProfileDetail.vue lines 618-624 and 762-781.)

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 — i.e. the in_person_provider of the payment profile assigned to that location. (Verified: upvendo-backoffice src/views/devices/components/setup-device/reader-section/ReaderSection.vue lines 89 and 110.)

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 for online ordering, plus an in-person connection through the provider chosen at creation (Stripe Terminal on the same Stripe account, or a separate Viva Wallet connected account)
In-person provider is chosen once and is permanent: in_person_provider is a required field on the New Payment Profile request (stripe or viva_wallet) and is not accepted by the profile update request, so it cannot be changed later. To switch providers, create a new profile and re-point the location to it
One profile per location: Each location has exactly one payment profile assigned
Payment profile is editable, not write-once: The location's Payment Profile field can be changed after it's initially set (it's read-only if the backend marks it in the location's uneditable_fields, e.g. for accounts in a specific sync/merchant mode, and the server also refuses a cross-currency re-point — see the next rule). Re-pointing an already-assigned location to a different profile unpairs all of that location's card terminals (Stripe readers detached, Viva terminals cleared) and resets its Viva Wallet source codes to 'Default', because terminals and source codes are scoped to the old profile's connected account; staff must re-pair terminals under the new profile afterward
Re-points must stay within one currency: before anything is unpaired or saved, the backend compares the currency of the old and the new profile (derived from the profile's country) and refuses a mismatch with HTTP 409 This payment profile uses a different currency and cannot be assigned to this location. Changing processor (Viva ↔ Stripe) within the same currency is still allowed. In practice this is a backstop rather than a limit merchants hit: new profiles can only be created for Belgium, France or the Netherlands, which are all EUR, so a mismatch only arises from legacy or manually-seeded profiles. The check is skipped when a profile's country has no known currency, and skipped entirely when Square POS is connected. (Verified: upvendo-backend app/Services/BackOffice/Settings/LocationService.php lines 599-618 and 673-692; app/RawModels/PaymentProfile.php lines 70-73; app/Http/Requests/BackOffice/Settings/Payment/NewPaymentProfileRequest.php lines 42-46.)
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, but setAsDefault() only succeeds when external_data.viva_wallet.verified is true — otherwise it fails with "Payment profile is not verified". In practice this means only a Viva-verified profile can be made the default. (Verified: upvendo-backend app/Services/BackOffice/Settings/PaymentProfileService.php lines 236-249.)
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 — in-person provider: Stripe Terminal or 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 the profile's in-person provider — Stripe Terminal or 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) plus the in-person provider you chose when creating it (Stripe Terminal or a Viva Wallet connected account), 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, pick a Country, choose the In-person payment provider (Stripe or Viva Wallet), and click Setup Profile. On the profile detail page, complete Stripe onboarding for online ordering and, if you chose Viva Wallet, set up the Viva Wallet account. Then assign the profile to locations in Settings → Locations so it takes effect.
"What is Stripe used for?" On a payment profile, Stripe always processes your online-ordering customer payments through a Stripe connected account. If you also chose Stripe as the in-person provider, the same Stripe account handles kiosk and card-reader payments (Stripe Terminal); if you chose Viva Wallet, in-person payments go through Viva instead. (Stripe also powers Upvendo's platform subscriptions.) 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 three things: a Name, a Country, and the In-person payment provider. Click Setup Profile to create it, then complete provider onboarding 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, a country, and the in-person provider choice. 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?" Yes. The New Profile dialog asks you to choose between Stripe ("Stripe Terminal — use the same Stripe account for online and in-person") and Viva Wallet ("dedicated in-person account"). The dialog warns that this choice is permanent — you cannot change the in-person provider after the profile is created, so create a new profile if you need to switch. Online ordering always uses Stripe regardless of the choice.
"Which provider handles my online-ordering payments?" By default, online ordering runs through Stripe (via your profile's Stripe connected account) when Square is not connected; the online provider is configurable and a Viva Wallet online-checkout path also exists. Kiosk/in-person card payments run through the profile's chosen in-person provider (Stripe Terminal or Viva Wallet). If Square is connected, Square handles all payments.
"Can I switch a profile from Viva Wallet to Stripe for in-person payments?" Not on the existing profile — in_person_provider is set once at creation and is not editable afterwards (the profile update request only accepts name). Create a new payment profile with the provider you want and re-point the location to it in Settings → Locations; be aware that switching a location's profile unpairs its card terminals and they must be re-paired.
"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. This field stays editable after a profile has been assigned — you can switch it to a different profile later, as long as the new profile settles in the same currency as the one currently assigned (a profile's currency comes from its country). A cross-currency switch is rejected when you save, with This payment profile uses a different currency and cannot be assigned to this location.; the dropdown lists every profile without filtering, so the error only shows up on save. The field can also be marked read-only for you specifically. Changing an already-assigned profile shows a warning that the location's in-person terminals will be unpaired and need re-pairing under the new profile, so switch it deliberately. (The field is hidden entirely when your account is Square-integrated.)
"I changed the payment profile and got a warning — what does it mean?" Assigning a different payment profile to a location that already has one re-points the location to a new Stripe/Viva Wallet connected account. Because paired terminals (Stripe readers and Viva terminals) are scoped to the old profile's connected account, saving the change unpairs every device at that location — the local pairing is cleared (and the Stripe reader is detached on Stripe's side, best-effort) — and resets the location's Viva Wallet source codes to 'Default'. Staff must re-pair each device's terminal afterward (Device Management → Devices → open the device → Card Reader / Terminal). The Stripe Terminal Location itself is preserved per profile and re-syncs automatically.
"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 registration code, 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.
"How do I remove the Viva Wallet account from a payment profile? There is no button." There isn't one — that is the current product behaviour, not something you are missing. Once a Viva Wallet account has been created on a profile, the back office can only view it: the Edit Viva Wallet Account dialog shows the account ID and links you to Viva's own dashboard, and there is no action that detaches or replaces the account. If the profile should not carry Viva Wallet at all, delete the whole payment profile and create a new one — which means unassigning it from every location first. An unused Viva Wallet account on a profile is otherwise harmless: the in-person provider is what decides which one is charged.

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 in-person provider account (Viva Wallet verified, or Stripe onboarding complete), 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
No way to remove a Viva Wallet account from a profile → Expected: there is no detach action, only create and view. Delete the profile (after unassigning it from all locations) if it must not carry Viva Wallet
Square payments not working → Check Square POS connection in integrations
Terminal stopped working after switching payment profiles → Expected: changing a location's payment profile unpairs all its card terminals (Stripe readers and Viva terminals). Re-pair the reader/terminal in Device Management → Devices → open the device → Card Reader / Terminal

Assistant Guidance

When answering questions about payments:

Clarify the channel: online ordering always uses Stripe; kiosk/in-person uses the profile's chosen in_person_provider (Stripe Terminal or Viva Wallet); 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 profiles: direct them to Setup Viva Wallet Account; onboarding completes on Viva's dashboard. This section is not shown on Stripe-in-person profiles
The New Profile dialog asks for a Name, a Country, and the In-person payment provider — no credential fields. The provider choice is permanent, so say so before they create the profile
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
The location's Payment Profile field is editable after assignment (do NOT say it locks/can't be changed) — but warn that switching it unpairs the location's card terminals and requires re-pairing them under the new profile, and that the new profile must settle in the same currency as the current one. A profile's currency is derived from its country, so a different country is fine as long as the currency matches; a cross-currency re-point is refused with a 409, "This payment profile uses a different currency and cannot be assigned to this location." Every profile a merchant can create today is EUR (Belgium/France/Netherlands), so this is a backstop rather than something they will normally hit — do not present it as a routine obstacle. It applies only when re-pointing a location that already has a profile; the first assignment, and Square-integrated merchants, skip the check

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 on profiles whose in-person provider is Viva Wallet
Square Integration: When connected, overrides both Stripe and Viva Wallet for all payment flows

Affects

Online Ordering: Stripe checkout and available payment methods
Kiosk: In-person terminal payment options (Stripe Terminal or Viva Wallet)
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 (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 — in-person provider: Stripe Terminal or 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 (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 — in-person provider: Stripe Terminal or Viva Wallet)

Customer Impact

FAQs

Troubleshooting

Assistant Guidance

Relations

Depends On

Affects