Stripe Integration

Overview

Stripe powers online-ordering customer payments -- via a per-profile Stripe connected account set up on the payment profile -- and is also used for platform subscription billing (kiosk devices, KDS screens, and online-ordering activations). Kiosk/in-person terminal payments are handled by Viva Wallet (or Square when connected).

Key Purpose: Process online-ordering customer payments and manage Upvendo platform subscription billing.

Note: Online-ordering customer payments run through Stripe (the per-profile connected account); kiosk/in-person terminal payments run through Viva Wallet. If Square POS is connected, Square handles all customer payments instead.

Purpose

This page lets you manage the merchant's Stripe configuration. On a payment profile, the Stripe connected account processes online-ordering customer payments; Stripe is also used for Upvendo platform subscription billing (kiosk, KDS, online-ordering activations). Stripe Terminal hardware can be registered for in-person scenarios where Stripe Terminal is used instead of Viva Wallet terminals.

Key Concepts

• Stripe Connect: Upvendo uses a per-profile Stripe connected account to process online-ordering customer payments (cards plus local methods like iDEAL and Bancontact). The same Stripe relationship also underpins platform subscription billing (kiosk, KDS, online-ordering activations).
• Subscription Billing: Stripe manages recurring subscription payments for platform services. Each kiosk device, KDS screen, and online ordering activation requires a Stripe subscription.
• SEPA Direct Debit: For EU merchants, Stripe supports SEPA Direct Debit as a subscription payment method, with automatic retry and mandate handling for failed payments.
• Live vs Test Mode: A toggle switches between Stripe's live and test environments; test mode uses Stripe's sandbox keys so no real charges are made.
• Stripe Terminal: An optional feature enabling in-person card payments via physical Stripe Terminal hardware, registered and managed from the backoffice. This is separate from Viva Wallet terminals.

Actions

Connect or Disconnect Stripe

Initiate the Stripe Connect flow to authorize your Stripe account for subscription billing. The flow redirects to Stripe for authorization and returns with the connected account ID.

Switch Between Live and Test Mode

Toggle between Stripe's live and test environments for subscription billing. Always test in test mode before switching to live.

Register Stripe Terminal Devices

Enable Stripe Terminal and register physical card reader devices for in-person payment scenarios (alternative to Viva Wallet terminals).

Location

• Backoffice Route: /settings/payments/stripe
• Backend Controller: app/Http/Controllers/Api/StripeController.php
• Vue Component: src/views/settings/payments/StripeComponent.vue

Fields

Stripe Connected

Property	Value
Field ID	connected
Label	Connected
Type	Display

Description: Whether Stripe account is connected.

---

Connect with Stripe

Property	Value
Action	Connect
Type	OAuth Flow

Description: Connect your Stripe account via Stripe Connect.

Flow:

1. Click "Connect with Stripe"
2. Redirect to Stripe
3. Authorize connection
4. Return to backoffice
5. Account connected

---

Account ID

Property	Value
Field ID	account_id
Label	Stripe Account ID
Type	Display

Description: Your connected Stripe account ID.

---

Live Mode

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

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

CRITICAL: Test thoroughly before enabling live mode!

---

Payment Methods

Card Payments

Property	Value
Field ID	card_enabled
Label	Accept Cards
Type	Toggle
Default	true

Description: Accept Visa, Mastercard, Amex, etc.

---

iDEAL (Netherlands)

Property	Value
Field ID	ideal_enabled
Label	Accept iDEAL
Type	Toggle
Default	false

Description: Dutch bank payment method.

---

Bancontact (Belgium)

Property	Value
Field ID	bancontact_enabled
Label	Accept Bancontact
Type	Toggle
Default	false

Description: Belgian debit card payments.

---

SOFORT

Property	Value
Field ID	sofort_enabled
Label	Accept SOFORT
Type	Toggle
Default	false

Description: Bank transfer (Germany, Austria).

---

Giropay

Property	Value
Field ID	giropay_enabled
Label	Accept Giropay
Type	Toggle
Default	false

Description: German online banking.

---

Apple Pay

Property	Value
Field ID	apple_pay_enabled
Label	Accept Apple Pay
Type	Toggle
Default	true

Description: Apple Pay on compatible devices.

---

Google Pay

Property	Value
Field ID	google_pay_enabled
Label	Accept Google Pay
Type	Toggle
Default	true

Description: Google Pay on compatible devices.

---

Stripe Terminal

Terminal Enabled

Property	Value
Field ID	terminal_enabled
Label	Enable Stripe Terminal
Type	Toggle
Default	false

Description: Use Stripe Terminal for in-person payments.

---

Terminals

Property	Value
Field ID	terminals
Label	Registered Terminals
Type	List

Description: Connected Stripe Terminal devices.

---

Business Logic

Subscription Billing Flow

Location enables online ordering / adds kiosk device
        |
        v
System creates Stripe subscription
        |
        v
Stripe charges merchant (card or SEPA)
        |
        v
Subscription active
        |
        v
Monthly renewal via Stripe

Stripe Terminal Payment Flow (when Stripe Terminal is used)

Customer at kiosk/POS
        |
        v
Stripe Terminal reader activated
        |
        v
Customer taps/inserts card
        |
        v
Payment confirmed via webhook
        |
        v
Order confirmed

Note: Customer-facing online ordering payments are processed by Viva Wallet, not Stripe. See Viva Wallet for the online ordering payment flow.

---

Business Rules

• Stripe processes online-ordering customer payments (via the per-profile connected account) and is also used for platform subscription billing (kiosk, KDS, online-ordering activations). Kiosk/in-person terminal payments are handled by Viva Wallet, or Square when connected.
• Stripe connection uses OAuth (Stripe Connect); the merchant's Stripe Account ID is stored after authorization and used for subscription billing API calls.
• Subscription payments support both card and SEPA Direct Debit. For SEPA, the system handles mandate data and automatic retries when payments fail.
• If a SEPA subscription payment fails and the subscription is deleted, the system automatically attempts to recreate the subscription with proper mandate handling.
• Stripe Terminal is an optional feature for in-person payments via physical readers; it is separate from Viva Wallet terminal payments and is handled via the StripeWebhookOrchestrator.

FAQs

• When is Stripe used vs Viva Wallet? Stripe processes online-ordering customer payments; Viva Wallet handles kiosk/in-person terminal payments. Both are set up per payment profile. If Square is connected, Square handles all customer payments instead. (Stripe is additionally used for Upvendo platform subscription billing.)
• Does Stripe process customer order payments? Yes -- online-ordering customer payments run through the payment profile's Stripe connected account (cards plus local methods like iDEAL and Bancontact). Kiosk/in-person terminal payments use Viva Wallet (or Square when connected).
• What happens if my Stripe account is not verified? If Stripe still has outstanding verification requirements, the payment profile shows an "Action required" or "Verification upcoming" status under Settings -> Payments. Your account is treated as verified once Stripe enables both charges and payouts; until then, online-ordering payments and payouts can be disrupted. Complete the verification steps in the embedded Stripe panel / notification banner to resolve it.
• How do I link Upvendo to Apple Wallet? Apple Pay is accepted at checkout via Stripe (enable it under the Stripe payment methods). Separately, Upvendo can issue Apple Wallet passes -- but only as customer loyalty/member cards, not as a way to link your merchant account to Apple Wallet. Customize how that member card looks under Settings -> Branding (Apple Wallet program name and strip image), and send a card to a customer from their profile using Send Member Card.
• What happens if I switch from test to live mode mid-day? The toggle takes effect immediately; any new subscription charges will use live Stripe keys.
• Can I use Stripe Terminal and Viva Wallet terminals at the same time? No, terminal payments are routed through one provider at a time based on the integration configuration.
• What is SEPA Direct Debit? SEPA is a European bank transfer method used for subscription billing. The system handles mandate data and automatically retries failed SEPA payments.

Troubleshooting

Problem: Payments failing

Causes:

1. Card declined
2. Stripe not connected
3. Test mode vs live mode
4. Payment method not enabled

Solutions:

1. Customer tries different card
2. Reconnect Stripe
3. Check mode setting
4. Enable payment method

---

Problem: iDEAL not showing

Causes:

1. iDEAL not enabled
2. Customer not in Netherlands
3. Stripe account not configured

Solutions:

1. Enable iDEAL
2. iDEAL only for NL customers
3. Configure in Stripe dashboard

---

Problem: Stripe account not verified / pending / restricted

A payment profile's Stripe account can be flagged as needing attention when Stripe has outstanding verification requirements. The Payments page shows this as one of two states:

• Action required -- the account is blocked: charges or payouts are disabled, or Stripe has set a disabled_reason. Payments and payouts may be disrupted until resolved.
• Verification upcoming -- Stripe will need more information soon (a future deadline), but nothing is blocking yet.

Causes:

1. Stripe onboarding was never completed (details_submitted is false).
2. Stripe has outstanding requirements (requirements.currently_due) -- e.g. ID verification, business details, or a bank account.
3. The account is restricted, so charges_enabled and/or payouts_enabled are false.
4. A deadline is approaching for items Stripe will eventually need (eventually_due).

Solutions:

1. Open the payment profile under Settings -> Payments and complete the Stripe verification steps shown in the embedded Stripe panel / notification banner.
2. Provide every item Stripe lists as outstanding (identity, business, and bank details) before the stated deadline.
3. Once Stripe enables both charges and payouts (and the transfers capability is active), the account is verified and the profile can accept online-ordering payments and receive payouts.

---

Examples

Netherlands Setup

{
  "connected": true,
  "live_mode": true,
  "card_enabled": true,
  "ideal_enabled": true,
  "bancontact_enabled": false,
  "apple_pay_enabled": true,
  "google_pay_enabled": true
}

Belgium Setup

{
  "connected": true,
  "live_mode": true,
  "card_enabled": true,
  "ideal_enabled": false,
  "bancontact_enabled": true,
  "apple_pay_enabled": true,
  "google_pay_enabled": true
}

Germany Setup

{
  "connected": true,
  "live_mode": true,
  "card_enabled": true,
  "sofort_enabled": true,
  "giropay_enabled": true,
  "apple_pay_enabled": true,
  "google_pay_enabled": true
}