Square Onboarding Flow

Overview

Square is a merchant-scoped POS integration that includes both order management AND payment processing. This makes setup simpler than other POS systems — no separate payment provider needed.

Key Differences from other integrations:

Payment Profile is NOT required — Square handles all payments (kiosk via Square Terminal, online via Square Web Payments SDK)
Locations are auto-imported during the first sync after connecting, including address, business hours, coordinates, timezone, currency, and social links
Menu sync is bidirectional — items can be created in either Square or Upvendo

Branding Profile is still required because Square does not provide colors, fonts, logos, or slogans. A default branding profile is auto-created per imported location with social links pre-filled from Square, but merchants should customize colors, logo, and fonts.

Integration Type

Scope: Merchant-scoped (connects entire merchant account, not per-location)
Payment Processing: Included — Square handles kiosk payments (Square Terminal) and online payments (Square Web Payments SDK)
Payment Profile: NOT required (skipped — Square manages all payments)
Menu Sync: Bidirectional (items, categories, modifiers, variant groups)
Order Sync: Bidirectional
Location Import: Automatic — all Square locations are imported on first sync with address, business hours, coordinates, timezone, currency, language, and social links
Inventory Sync: Bidirectional (stock levels synced between systems)

Location Import Details

When Square is connected, all Square locations are automatically imported into Upvendo. Unlike MplusKassa (which only imports branch names), Square provides rich location data:

Auto-filled from Square:

Name, full address, Google Maps address
Coordinates (latitude/longitude)
Business hours
Timezone, country code, currency, language
Phone number and email
Location type (Physical/Mobile)
Description
Social links (Facebook, X, Instagram) → saved to branding profile

Auto-created by Upvendo per location:

Branding profile (with defaults + Square social links)
Billing link (Stripe customer ID from default billing profile, if exists)

Still needs manual setup after import:

Branding customization (logo, colors, fonts — Square doesn't provide these)
Delivery zones (if doing delivery)
Online ordering URL (configured during online ordering setup)

Discovery Flow (JSON - for deterministic parsing)

discovery_questions

[
  {
    "id": "channels",
    "text": "What channels do you want to set up with Square?",
    "options": ["Kiosk only", "Online ordering only", "Both"]
  },
  {
    "id": "menu_ready",
    "text": "Do you already have your menu set up in Square?",
    "options": ["Yes, my menu is in Square", "No, I need to create it"]
  }
]

setup_steps

{
  "Kiosk only": [
    {"id": "branding_profile", "title": "Set up Store Branding", "route": "/settings/brand", "required": true, "note": "Square imports social links but not colors/fonts/logo. Customize your brand identity."},
    {"id": "connect_pos", "title": "Connect Square and Sync Now", "route": "/square", "modal_type": "SquareConnectDialog", "required": true, "note": "OAuth connects your Square account. Locations, menu, and inventory are imported automatically after connecting."},
    {"id": "complete_location", "title": "Review Imported Locations", "route": "/settings/locations", "required": true, "note": "Verify imported location details. Most fields are pre-filled from Square. Add delivery zones if needed."},
    {"id": "setup_menu_kiosk", "title": "Set up Menu for Kiosk", "route": "/menus", "required": true},
    {"id": "in_house_settings", "title": "Set up In-House Settings", "route": "/in-house/settings", "required": true},
    {"id": "device_profile", "title": "Set up Device Profile", "route": "/device-management/profiles", "required": true},
    {"id": "configure_kiosk", "title": "Configure Kiosk and Pair Square Terminal", "route": "/device-management/devices", "required": true, "note": "Pair your Square Terminal device for payment processing. Generate a device code in Upvendo and enter it on the terminal."},
    {"id": "billing_profile", "title": "Set up Billing Profile", "route": "/settings/billing", "required": false, "note": "For Upvendo platform billing. Not related to customer payments (Square handles those)."},
    {"id": "test_kiosk", "title": "Test Kiosk", "required": false}
  ],
  "Online ordering only": [
    {"id": "branding_profile", "title": "Set up Store Branding", "route": "/settings/brand", "required": true, "note": "Square imports social links but not colors/fonts/logo. Customize your brand identity."},
    {"id": "connect_pos", "title": "Connect Square and Sync Now", "route": "/square", "modal_type": "SquareConnectDialog", "required": true, "note": "OAuth connects your Square account. Locations, menu, and inventory are imported automatically after connecting."},
    {"id": "complete_location", "title": "Review Imported Locations", "route": "/settings/locations", "required": true, "note": "Verify imported location details. Most fields are pre-filled from Square. Add delivery zones if needed."},
    {"id": "setup_menu_online", "title": "Set up Menu for Online Ordering", "route": "/menus", "required": true},
    {"id": "online_settings", "title": "Set up Online Settings", "route": "/online-settings", "required": true},
    {"id": "configure_online_ordering", "title": "Configure Online Ordering", "route": "/online/online-ordering", "required": true, "note": "Online payments are handled by Square Web Payments SDK — no Stripe or Viva Wallet setup needed."},
    {"id": "billing_profile", "title": "Set up Billing Profile", "route": "/settings/billing", "required": false, "note": "For Upvendo platform billing. Not related to customer payments (Square handles those)."},
    {"id": "test_online_ordering", "title": "Test Online Ordering", "required": false}
  ],
  "Both": [
    {"id": "branding_profile", "title": "Set up Store Branding", "route": "/settings/brand", "required": true, "note": "Square imports social links but not colors/fonts/logo. Customize your brand identity."},
    {"id": "connect_pos", "title": "Connect Square and Sync Now", "route": "/square", "modal_type": "SquareConnectDialog", "required": true, "note": "OAuth connects your Square account. Locations, menu, and inventory are imported automatically after connecting."},
    {"id": "complete_location", "title": "Review Imported Locations", "route": "/settings/locations", "required": true, "note": "Verify imported location details. Most fields are pre-filled from Square. Add delivery zones if needed."},
    {"id": "setup_menu_kiosk", "title": "Set up Menu for Kiosk", "route": "/menus", "required": true},
    {"id": "setup_menu_online", "title": "Set up Menu for Online Ordering", "route": "/menus", "required": true},
    {"id": "in_house_settings", "title": "Set up In-House Settings", "route": "/in-house/settings", "required": true},
    {"id": "device_profile", "title": "Set up Device Profile", "route": "/device-management/profiles", "required": true},
    {"id": "configure_kiosk", "title": "Configure Kiosk and Pair Square Terminal", "route": "/device-management/devices", "required": true, "note": "Pair your Square Terminal device for payment processing. Generate a device code in Upvendo and enter it on the terminal."},
    {"id": "online_settings", "title": "Set up Online Settings", "route": "/online-settings", "required": true},
    {"id": "configure_online_ordering", "title": "Configure Online Ordering", "route": "/online/online-ordering", "required": true, "note": "Online payments are handled by Square Web Payments SDK — no Stripe or Viva Wallet setup needed."},
    {"id": "billing_profile", "title": "Set up Billing Profile", "route": "/settings/billing", "required": false, "note": "For Upvendo platform billing. Not related to customer payments (Square handles those)."},
    {"id": "test_kiosk", "title": "Test Kiosk", "required": false},
    {"id": "test_online_ordering", "title": "Test Online Ordering", "required": false}
  ]
}

Payment Flow

Kiosk Payments (Square Terminal)

Square Terminal replaces Viva Wallet for in-person payments. The terminal is paired via a device code generated in Upvendo.

Customer Order → Upvendo Kiosk → Square Terminal Checkout → Payment on Terminal → Webhook confirms payment

Online Ordering Payments (Square Web Payments SDK)

Square Web Payments SDK replaces Stripe for online payments. The frontend tokenizes the card, and the backend processes the payment via Square Payments API.

Customer Order → Online Ordering → Square Web Payments SDK (card tokenization) → Square Payments API → Webhook confirms payment

No Payment Profile, Stripe, or Viva Wallet configuration is needed.

Troubleshooting

"OAuth connection failed"

Verify the merchant has an active Square account
Ensure they have owner or admin permissions on the Square account
Try disconnecting and reconnecting from the Square page (/square)

"Locations not appearing after connecting"

The first sync runs automatically after OAuth — check the sync status on the Square page
If sync is stuck, click Sync Now on the status tab
Check the sync logs for errors

Trigger a manual sync: go to Square page → Status tab → Sync Now
Menu sync is bidirectional — items created in either system will sync
Check that the daily sync time is configured in Settings tab

"Square Terminal not connecting"

Ensure the terminal is powered on and connected to the internet
Generate a new device code in Upvendo (Device Management → device → Square Terminal section)
Enter the code on the terminal within 5 minutes (codes expire)
The terminal must be signed into the same Square account that's connected to Upvendo

"Online payments not working"

Verify the location is synced with Square (check for Square location ID in location settings)
Ensure the Square account has payment processing enabled
Check Square Dashboard for any account holds or verification requirements

Square Onboarding Flow ​

Overview ​

Integration Type ​

Location Import Details ​

Discovery Flow (JSON - for deterministic parsing) ​

Payment Flow ​

Kiosk Payments (Square Terminal) ​

Online Ordering Payments (Square Web Payments SDK) ​

Troubleshooting ​

"OAuth connection failed" ​

"Locations not appearing after connecting" ​

"Menu items not syncing" ​

"Square Terminal not connecting" ​

"Online payments not working" ​