Square Integration

Overview

Square integration connects Upvendo with Square POS for unified sales tracking, inventory management, and payment processing.

Key Purpose: Sync with Square POS system and use Square Payments.

IMPORTANT: When Square is connected, Square Payments replaces both Stripe (Online Ordering) and Viva Wallet (Kiosk terminals).

Purpose

This page lets you connect your Square POS account to Upvendo so that menu items, orders, inventory, and payments are synchronized between both systems.

Key Concepts

• Square Integration Service: The central backend class (SquareIntegrationService) that manages the OAuth connection, sync operations, and terminal checkouts using the official Square SDK.
• Sync Direction: Controls the flow of data -- Upvendo to Square, Square to Upvendo, or bidirectional -- determining which system is the source of truth for items, orders, and inventory.
• Payment Provider Override: When Square is connected, an isSquareIntegrated() check in PaymentService routes all terminal and online payments through Square instead of Viva Wallet or Stripe.
• Square Terminal Checkout: For kiosk payments, the system creates a TerminalCheckout on the Square API, sends it to the assigned Square Terminal device, and monitors its status (pending, completed, cancelled).
• Sync Logs: The integration maintains a rolling log of the last 100 sync operations with timestamps, types, and messages, deduplicating consecutive identical entries.

Actions

Connect or Disconnect Square Account

Initiate the OAuth flow to authorize Upvendo to access your Square account. Disconnecting removes the stored credentials and disables all sync operations.

Configure Sync Settings

Choose which data types to synchronize (menu items, orders, inventory) and set the sync direction for each. Bidirectional sync keeps both systems in parity.

Map Square Location

Select which Square location to pair with the current Upvendo location. All synced data flows through this specific Square location ID.

Process Square Terminal Payments

When Square is the active payment provider, kiosk devices create terminal checkouts on the Square API. The system handles retry logic for existing pending checkouts and creates new ones for cancelled or failed attempts.

Payment Provider Override

Square POS Connected?
├── Yes → ALL payments through Square
│         ├── Online Ordering → Square Payments
│         ├── Kiosk Terminal → Square Terminal
│         └── Table QR → Square Payments
│
└── No → Default providers
          ├── Online Ordering → Stripe
          └── Kiosk Terminal → Viva Wallet

Location

• Backoffice Route: /integrations/square
• Backend Controller: app/Http/Controllers/Api/SquareController.php
• Vue Component: src/views/integrations/SquareComponent.vue

Fields

Square Connected

Property	Value
Field ID	connected
Label	Connected
Type	Display

Description: Whether Square account is connected.

---

Connect with Square

Property	Value
Action	Connect
Type	OAuth Flow

Description: Connect your Square account.

---

Location ID

Property	Value
Field ID	location_id
Label	Square Location
Type	Select
Required	Yes

Description: Which Square location to sync with.

---

Sync Settings

Sync Menu Items

Property	Value
Field ID	sync_items
Label	Sync Menu Items
Type	Toggle
Default	true

Description: Sync menu items between systems.

---

Sync Orders

Property	Value
Field ID	sync_orders
Label	Sync Orders
Type	Toggle
Default	true

Description: Send orders to Square.

---

Sync Inventory

Property	Value
Field ID	sync_inventory
Label	Sync Inventory
Type	Toggle
Default	false

Description: Sync stock levels.

---

Sync Direction

Property	Value
Field ID	sync_direction
Label	Sync Direction
Type	Select
Options	upvendo_to_square, square_to_upvendo, bidirectional
Default	upvendo_to_square

Description: Which direction data flows.

---

Business Logic

Sync Flow

Change in Upvendo
        |
        v
Sync enabled for this data type?
|-- No --> Skip
|-- Yes --> Continue
        |
        v
Transform to Square format
        |
        v
Send to Square API
        |
        v
Confirm sync

---

Business Rules

• When Square is connected, the isSquareIntegrated() trait check causes PaymentService to route all terminal payments through processSquarePayment instead of Viva Wallet, and all online payment orders through createPaymentOrder via Square.
• Square Terminal checkout creation requires a valid squareDeviceId on the kiosk device record; if it is missing, the system throws an exception before contacting Square.
• If an existing terminal checkout is still in "PENDING" status, the system returns the current transaction without creating a duplicate checkout.
• Terminal checkout cancellation is attempted via the Square API; failures are logged but do not throw exceptions, ensuring the Upvendo transaction can still be updated.
• Sync logs are capped at 100 entries and duplicate consecutive log entries (same message and type) are collapsed by updating the timestamp instead of adding a new row.

FAQs

• Does connecting Square automatically disable Stripe and Viva Wallet? Yes, the payment routing logic checks isSquareIntegrated() at runtime and bypasses both Stripe and Viva Wallet when Square is active.
• Can I sync inventory from Square into Upvendo? Yes, set the sync direction to "square_to_upvendo" or "bidirectional" and enable the inventory sync toggle.
• What happens if the Square API is down during a payment? The system logs the error and throws an exception with the Square error message; the kiosk will show a payment failure and allow retry.
• Can I connect multiple Upvendo locations to the same Square account? Yes, each Upvendo location maps to a specific Square location ID, and multiple Upvendo locations can use different locations within the same Square account.
• How do I check sync history? The integration logs are accessible in the backoffice and show the last 100 sync operations with timestamps and status messages.

Troubleshooting

Problem: Sync failing

Causes:

1. Connection expired
2. API rate limit
3. Data format issue

Solutions:

1. Reconnect Square
2. Wait and retry
3. Check data validity

---

Problem: Items not syncing

Causes:

1. Sync disabled
2. Item not mapped
3. Conflict detected

Solutions:

1. Enable item sync
2. Map items manually
3. Resolve conflict

---

Examples

Basic Setup

{
  "connected": true,
  "location_id": "square-location-id",
  "sync_items": true,
  "sync_orders": true,
  "sync_inventory": false,
  "sync_direction": "upvendo_to_square"
}