Problemi comuni e risoluzione
Sintomi, cause e soluzioni per i problemi che possiamo verificare nel prodotto.
Se il tuo problema non è qui, scrivi a support@rowie.io allegando screenshot e l'ID transazione (o ID sessione, o numero di fattura) quando possibile.
"Setup required" su Banking o Tap to Pay
La schermata Account del POS mobile mostra un badge Setup required sulla riga Banking, e Tap to Pay / Terminal Readers sono disabilitati, finché Stripe Connect non ha completato l'onboarding e gli incassi non sono abilitati.
- Portale vendor → Banking (sidebar → gruppo FINANCE) → verifica lo stato.
- Se l'onboarding non è completo, segui il form ospitato di Stripe — ti dirà esattamente cosa manca (ID, dati bancari, info aziendali).
- Le configurazioni iniziali possono richiedere 1–2 giorni perché Stripe verifichi i dati.
Il controllo "pronto per incassare" nel codice dell'app è connectStatus.hasConnectedAccount && connectStatus.chargesEnabled — entrambi devono essere true.
"Cannot delete location — it still has …"
Il portale blocca la disattivazione di una location se ci sono record dipendenti. Il messaggio esatto elenca cosa sta bloccando. I controlli (rowie-api/src/routes/locations.ts):
- Table sessions aperte o in corso — saldale o annullale prima.
- Menu, floor plans, bookings attive, booking pages — riassegnale a un'altra location o eliminale prima.
- Unica location nell'organizzazione — non puoi eliminare l'ultima rimasta.
Sposta le dipendenze, poi riprova.
"Cannot delete menu with open sessions or tabs"
Un menu (catalog) non si elimina finché ci sono sessioni o tab ancora aperte su di esso. Saldale o annullale sulla pagina Tables, poi riprova l'eliminazione. Lo stesso pattern vale per:
- Floor plans / tables con sessioni attive.
- Eventi / ticket tiers con biglietti venduti.
- Vendor subscription plans con abbonati attivi (annullali o migrali prima).
- Tip pools non in draft (puoi eliminare i pool solo finché sono in draft).
"Authentication failed" o schermata bloccata dopo lunga inattività
I token di autenticazione scadono dopo 15 minuti; l'app mobile e il portale vendor li rinnovano automaticamente su un 401. Se il refresh fallisce (es. il refresh token è scaduto dopo 7 giorni, oppure hai fatto login su un altro dispositivo e sei stato espulso), vedrai un toast "Authentication failed" e tornerai alla schermata di login.
- Solo mobile: quando fai login su un secondo dispositivo, il primo dispositivo riceve SESSION_KICKED e viene disconnesso forzatamente — questo è voluto (protezione anti-furto del telefono).
- Il portale vendor non impone la sessione singola — puoi tenere più tab aperti.
Se sei bloccato a metà schermata: esci e rientra.
Chiusura di una tab fallita / "Payment failed"
Quando una carta salvata viene addebitata off-session per chiudere una tab e Stripe la rifiuta, la sessione torna a open così puoi riprovare. Cause comuni:
- La carta richiede una nuova autenticazione / 3DS per ogni addebito.
- Regola antifrode dell'emittente sugli addebiti off-session.
- Fondi insufficienti.
Limitazione nota: le chiavi di idempotenza di Stripe per il close-tab sono stabili per 24 ore. Se il primo tentativo di close-tab è stato rifiutato, ripetere con la stessa carta restituisce subito lo stesso intent rifiutato. Workaround: accetta un pagamento Tap to Pay nuovo invece di chiudere con la carta salvata, oppure chiedi al cliente di salvare una nuova carta.
"Payment setup required" al checkout
Il POS mobile mostra questo messaggio quando provi a incassare ma Stripe Connect non è completamente configurato. Stessa soluzione del badge "Setup required" qui sopra — completa l'onboarding di Banking.
Ricevute: invio e re-invio
Le ricevute Tap to Pay devono essere inviate esplicitamente — Stripe non le invia automaticamente per le transazioni card_present.
- Sulla schermata Payment Result subito dopo un addebito, inserisci l'email del cliente e tocca Send receipt.
- In seguito, apri qualsiasi transazione in History → Send receipt.
Se le ricevute non arrivano, controlla prima lo spam, poi verifica che l'email sulla transazione sia corretta.
I dati in tempo reale sembrano vecchi
L'app usa Socket.IO per spingere gli aggiornamenti (ordini, sessioni, tab, menu, prenotazioni, fatture, pay run). TanStack Query è configurato con stale time infinito e nessun polling — le invalidazioni arrivano dagli eventi socket.
Se qualcosa sembra vecchio:
- Fai pull-to-refresh sulla schermata (mobile) o ricarica la pagina (portale vendor).
- Esci e rientra per forzare una nuova connessione socket.
- Verifica che l'URL dell'API sia raggiungibile dal tuo dispositivo.
Il socket del portale vendor si riconnette automaticamente con token freschi (dynamic auth callback). Il client mobile tenta fino a 10 riconnessioni con backoff tra 1 e 5 s.
Rate-limited (HTTP 429) sulle pagine pubbliche menu / table / booking
L'API limita la creazione pubblica di preorder, session e booking per IP + session ID per mitigare le frodi (introdotto dopo l'incidente di aprile 2026). Il traffico cliente normale non lo attiva. Se un test di carico o un loop accidentale di retry lo innesca, attendi che la finestra si svuoti (un minuto) e riprova.
Il pulsante Tap to Pay è grigio
- Entitlement Apple Tap to Pay: la prima volta su un nuovo account Stripe Connect, Apple impiega 1–2 giorni per abilitare il dispositivo.
- Banking non attiva: vedi "Setup required" sopra.
- Dispositivo sbagliato: Tap to Pay richiede iPhone XS o più recente con iOS 16.4+ e codice di sblocco, oppure Android NFC-capable (SDK 26+).
Account segnalato per revisione
Quando le euristiche antifrode si attivano (tasso di addebiti bloccati o falliti sopra le soglie), il review_status dell'account passa a needs_review e i payout automatici vengono sospesi. Contatta il supporto — una volta che lo staff Rowie approva l'account dalla coda admin, i payout riprendono. L'uso in sola lettura del prodotto continua a funzionare.