Gateway Square Terminal

Il gateway Square Terminal ti consente di incassare i pagamenti degli ordini WooCommerce sull'hardware Square Terminal direttamente da WCPOS. Il pagamento viene richiesto da WooCommerce e completato su un dispositivo Square Terminal associato, e il risultato viene riscritto sull'ordine.

Funzionalità

Integrazione hardware

Invia i pagamenti ai dispositivi Square Terminal associati e incassa pagamenti con carta presente

Connessione con un clic

Autorizza direttamente con Square — nessun token di accesso da creare o incollare

Completamento affidabile

I pagamenti vengono confermati tramite interrogazioni periodiche e un processo di riconciliazione in background, con i webhook a velocizzare il tutto

Transazioni sicure

Elaborazione con carta presente conforme allo standard PCI, gestita sull'hardware Square

Sandbox e produzione

Verifica il funzionamento nella Sandbox di Square prima di passare ai pagamenti reali

Come funziona

A differenza dei gateway basati su SDK del browser, Square Terminal utilizza la Terminal API lato server di Square. Quando avvii un pagamento, WooCommerce crea un Terminal Checkout per l'ordine e Square lo invia al dispositivo associato. Il cliente paga sul terminale e il risultato viene riscritto sull'ordine.

Come viene confermato un pagamento. Il POS interroga Square mentre il pagamento è in corso, e un processo di riconciliazione in background recupera tutto ciò che l'interrogazione non intercetta — per esempio una scheda del browser chiusa. I webhook di Square sono un'aggiunta facoltativa che riduce l'attesa; non sono obbligatori, e un sito che non li usa non perde mai un pagamento.

Il dispositivo Square Terminal deve essere online e collegato allo stesso account Square e alla stessa sede del plugin.

Configurazione

1

Installa Square Terminal for WooCommerce

Installalo da WP Admin > POS > Impostazioni > Estensioni, oppure scarica l'ultimo file zip del plugin (non lo zip o il tarball del codice sorgente di GitHub) dalla pagina delle release su GitHub e caricalo da Plugin > Aggiungi nuovo > Carica plugin.

2

Connettiti a Square

1. Vai su WP Admin > WooCommerce > Impostazioni > Pagamenti e apri Square Terminal
2. In Account Square, scegli l'Ambiente — Sandbox per i test, Production per i pagamenti reali
3. Fai clic su Connetti a Square e approva le autorizzazioni che Square ti mostra
4. Scegli il Location ID — la sede Square per la quale il Terminal incassa i pagamenti

Scegli l'ambiente prima di connetterti. Una connessione riguarda un solo ambiente; una connessione sandbox non potrà mai autorizzare pagamenti di produzione.

Utilizzi già il plugin ufficiale WooCommerce Square?

Ambiente e Location ID vengono precompilati a partire dalle sue impostazioni. Vengono letti solo questi due valori: nessuna credenziale viene condivisa tra i plugin e qui devi comunque connetterti o fornire un token di accesso.

Preferisci usare un tuo token di accesso?

Apri le Impostazioni avanzate e incolla un token di accesso per l'ambiente selezionato anziché connetterti. Tutto il resto funziona in modo identico.

3

Associa il tuo Square Terminal

In Terminal:

1. Fai clic su Create Device Code — compare un codice di associazione
2. Sul Square Terminal, apri la schermata di accesso tramite codice dispositivo e inserisci il codice. Se il Terminal è al momento collegato a Square POS o a un'altra integrazione, esci prima da quella: la schermata del codice dispositivo non è raggiungibile mentre il terminale è in uso altrove.
3. Fai clic su Check for readers per confermare che ora compare in Paired with this plugin

Un elenco vuoto prima dell'associazione è normale, non un guasto. L'API dei dispositivi di Square segnala solo i Terminal configurati per l'uso con la Terminal API: un Terminal su cui è in esecuzione Square POS non compare affatto finché non vi si inserisce un codice dispositivo.

4

Abilitalo in WCPOS

1. Vai su WP Admin > POS > Impostazioni > Checkout
2. Individua il gateway Square Terminal e abilitalo per il POS
3. Salva le impostazioni

nota

La casella Abilita/Disabilita nella schermata delle impostazioni di WooCommerce controlla soltanto il checkout del negozio online. WCPOS utilizza automaticamente questo gateway una volta configurato, indipendentemente dal fatto che la casella sia selezionata.

Associare un Terminal

Un Square Terminal deve essere associato a questo plugin prima che un cassiere possa selezionarlo. L'associazione crea un Device Code della Terminal API, ed è l'unico modo con cui il plugin può indirizzare il dispositivo.

Nella sezione Terminal della schermata delle impostazioni:

• Create Device Code — genera un codice da inserire sul Terminal. Ha vita breve: generane uno nuovo se scade.
• Check for readers — elenca ciò che Square riesce a vedere, in due gruppi:
  • Paired with this plugin — selezionabile al checkout
  • Other devices Square can see at this location — configurati da un'altra applicazione, quindi non selezionabili qui finché non vengono associati a questo plugin
• Validate Settings — verifica le credenziali e la sede presso Square

Perché un Terminal di tua proprietà potrebbe non essere selezionabile

I Device Code appartengono all'applicazione che li ha creati, quindi un Terminal configurato da un'altra integrazione Terminal API compare in Other devices Square can see ma non può essere selezionato qui. Un Terminal su cui è in esecuzione Square POS non compare affatto.

In entrambi i casi la soluzione è la stessa: disconnetti il Terminal da ciò a cui è attualmente associato, quindi inserisci un nuovo codice generato con Create Device Code qui.

Webhook

I webhook sono facoltativi. Riducono il tempo necessario alla conferma di un pagamento. Le interrogazioni periodiche e il processo di riconciliazione in background confermano comunque ogni pagamento, quindi un sito senza una sottoscrizione webhook funziona correttamente lo stesso — solo con qualche istante in più per la conferma.

Non disponibile se hai usato Connetti a Square

Una sottoscrizione webhook appartiene a un'applicazione Square e per aggiungerne una serve l'accesso a quell'applicazione nella Square Developer Dashboard. Se ti sei connesso con Connetti a Square, stai autorizzando l'applicazione WCPOS anziché una tua, quindi non esiste una dashboard in cui aggiungere una sottoscrizione né una chiave di firma da copiare.

I pagamenti vengono comunque confermati normalmente, tramite le interrogazioni periodiche e la riconciliazione. I passaggi seguenti valgono solo se hai configurato il plugin con un tuo token di accesso nelle Impostazioni avanzate.

Per aggiungerne uno, usando una tua applicazione Square:

1. Nella schermata delle impostazioni, in Terminal → Webhooks, fai clic su Copy per copiare l'URL del webhook
2. Nella Square Developer Dashboard, apri la tua applicazione e vai su Webhooks
3. Aggiungi una sottoscrizione per l'evento terminal.checkout.updated, incollando quell'URL come URL di notifica
4. Copia la Webhook Signature Key da Square nelle Impostazioni avanzate del plugin

La riga Webhooks indica quindi se è arrivato un webhook con firma verificata, e quando.

L'URL deve corrispondere esattamente

Square firma ogni webhook sull'URL di notifica che gli è stato indicato. Se l'URL impostato in Square differisce anche di un solo carattere da quello del plugin, ogni consegna fallisce la verifica. Usa il pulsante Copy anziché digitarlo.

Perché questo passaggio è manuale

L'API Webhook Subscriptions di Square è associata all'applicazione, non ai singoli venditori, e non può essere chiamata con un token di accesso del venditore. Il plugin non può quindi creare la sottoscrizione al posto tuo.

Se i webhook non superano più la verifica

La riga Webhooks mostra Not verified yet quando nessun webhook è arrivato e stato verificato con le impostazioni attuali. Se sono già stati eseguiti dei pagamenti, controlla in quest'ordine:

1. La Webhook Signature Key nelle Impostazioni avanzate corrisponde a quella presente in Square
2. L'URL di notifica in Square corrisponde esattamente all'URL mostrato nel plugin
3. L'evento terminal.checkout.updated è sottoscritto
4. Il tuo sito è raggiungibile pubblicamente via HTTPS — controlla i tentativi di consegna nella Square Dashboard

Modificare l'ambiente, l'URL del webhook o la chiave di firma azzera questa riga fino all'arrivo del webhook successivo. È voluto: una consegna verificata con le vecchie impostazioni non dice nulla sulle nuove.

Riferimento delle impostazioni

La schermata delle impostazioni è ordinata secondo la sequenza della configurazione.

Sezione	Contiene
Account Square	Ambiente, Connetti a Square, Location ID
Terminal	Controlli di associazione, elenco dei lettori, stato dei webhook
Comportamento del checkout	Salta la schermata della ricevuta, raccogli la firma, log di debug
Impostazioni avanzate	Token di accesso, chiave di firma dei webhook, override dell'URL dei webhook

Le Impostazioni avanzate sono chiuse per impostazione predefinita. Contengono i token di accesso manuali — necessari solo se non ti connetti — e la chiave di firma dei webhook. L'override dell'URL dei webhook dovrebbe restare vuoto, a meno che il tuo URL pubblico non differisca da quello ricavato dal plugin, per esempio dietro un proxy o con un dominio personalizzato.

Utilizzo

Elaborazione dei pagamenti

1. Aggiungi articoli: aggiungi i prodotti al carrello nel POS
2. Seleziona il gateway: scegli "Square Terminal" come metodo di pagamento
3. Scegli il dispositivo: seleziona il terminale associato dall'elenco Terminal Device
4. Avvia il pagamento: fai clic su Start Payment — Square invia il checkout al dispositivo
5. Pagamento del cliente: il cliente avvicina, inserisce o striscia la propria carta sul Square Terminal
6. Completamento: lo stato si aggiorna in tempo reale durante l'attesa e l'ordine viene contrassegnato come pagato non appena Square conferma il pagamento

In Sandbox, l'elenco dei dispositivi contiene gli ID dei dispositivi di test documentati da Square, così ogni esito — riuscita, timeout, offline — può essere provato senza hardware.

Controlli di pagamento

• Start Payment: invia una nuova richiesta di pagamento al terminale selezionato
• Cancel Payment: annulla un pagamento attualmente in corso sul terminale
• Check Status: chiede immediatamente a Square lo stato attuale
• Release Payment: scollega un terminale che non risponde, così l'ordine può essere pagato in un altro modo; il checkout abbandonato viene comunque riconciliato in background
• Payment Log: un registro facoltativo per singolo ordine che annota ogni passaggio Square e il relativo esito

Gestione degli ordini

• Completamento verificato: gli ordini vengono contrassegnati come pagati solo dopo che il pagamento è stato verificato rispetto all'oggetto Payment di Square — mai su un segnale non verificato
• Tracciamento dei pagamenti: gli identificatori Square e un registro dei pagamenti vengono memorizzati sull'ordine, e i passaggi principali vengono scritti nelle note dell'ordine
• Generazione delle ricevute: le ricevute POS standard vengono generate dopo i pagamenti riusciti

Requisiti

Account Square: Account venditore Square attivo

Sede Square: Una sede Square e il relativo Location ID

Hardware compatibile: Un dispositivo Square Terminal, online e collegato alla stessa sede Square

Sito HTTPS pubblico: Necessario solo se vuoi usare i webhook; senza di essi i pagamenti vengono confermati tramite interrogazioni periodiche

WCPOS: Versione Pro necessaria per il checkout POS

Compatibilità hardware

Requisiti di connettività

Square Terminal utilizza la Terminal API lato server di Square: il checkout viene creato dal tuo sito e consegnato al dispositivo associato da Square. Il terminale deve essere online e collegato allo stesso account Square e alla stessa sede del plugin.

Terminali supportati

• Square Terminal ✅ — il terminale da banco dedicato di Square per il pagamento con carta

Ambito e limitazioni

Ambito attuale

• È incentrato sui flussi POS / pagamento dell'ordine. La disponibilità nel checkout del negozio online rivolto al cliente è disattivata per impostazione predefinita e va abilitata esplicitamente.
• Incassa solo i pagamenti — i rimborsi non sono ancora supportati. Gli identificatori Square vengono memorizzati sull'ordine, così il supporto ai rimborsi potrà essere aggiunto in seguito.
• Le sottoscrizioni webhook vanno aggiunte manualmente in Square; vedi Webhook.

Risoluzione dei problemi

Problemi comuni

L'elenco Terminal Device è vuoto

• Il Terminal deve prima essere associato a questo plugin — usa Create Device Code e inserisci il codice sul dispositivo
• Un Terminal associato tramite la Square Dashboard o l'app Square POS non comparirà finché non viene associato qui
• Fai clic su Check for readers: se compare in Other devices Square can see, esiste ma non è associato a questo plugin
• Verifica che il Location ID corrisponda alla sede a cui il Terminal è collegato

Il dispositivo non si associa

• Assicurati di aver inserito il Device Code prima della sua scadenza — generane uno nuovo con Create Device Code
• Verifica che il terminale sia online e collegato allo stesso account Square e allo stesso Location ID del plugin
• Controlla che l'Ambiente corrisponda all'account a cui il terminale è collegato

Validate Settings non riesce

• Se sei connesso, controlla che la riga Account Square mostri ancora Connected to Square; se ti chiede di riconnetterti, l'autorizzazione è decaduta
• Se usi un token di accesso, verifica che corrisponda all'Ambiente selezionato — un token Sandbox non funzionerà in Production, e viceversa
• Verifica che il Location ID appartenga a quell'account

Il pagamento si completa sul terminale ma l'ordine tarda ad aggiornarsi

• È esattamente ciò che risolvono i webhook. Senza di essi, l'ordine si aggiorna alla successiva riconciliazione da parte delle interrogazioni periodiche o del processo in background
• Controlla la riga Webhooks: se indica Not verified yet dopo che sono stati eseguiti dei pagamenti, segui Se i webhook non superano più la verifica
• L'ordine non va mai perso: il processo di riconciliazione recupera qualsiasi pagamento sfuggito all'interrogazione

Il pagamento non parte

• Verifica che sia selezionato un terminale e che il dispositivo sia associato e online
• Controlla che il dispositivo sia collegato al Location ID configurato
• Consulta il Payment Log e WooCommerce > Stato > Log per i messaggi dell'API Square

Viene indicato che è necessaria una riconnessione a Square

Le autorizzazioni Square vengono rinnovate automaticamente. Se un rinnovo non può essere completato, il plugin chiude l'autorizzazione anziché lasciarla in uno stato inutilizzabile, e la schermata delle impostazioni ti chiede di riconnetterti. Fai clic su Riconnetti a Square — non serve modificare altro.

Ottenere assistenza

Per il supporto tecnico:

• Visita il repository GitHub per segnalare problemi
• Consulta la documentazione della Square Terminal API per indicazioni su hardware e API
• Contatta l'assistenza Square per i problemi relativi ad account e hardware

I log vengono scritti in WooCommerce > Stato > Log sotto l'handle sqtwc, e registrano ogni ricerca di dispositivo e ogni esito dei webhook.

Screenshot

Gli screenshot verranno aggiunti in un aggiornamento futuro per mostrare:

• Le sezioni Account Square, Terminal e Impostazioni avanzate
• L'abilitazione del gateway nelle impostazioni WCPOS
• Il flusso di elaborazione dei pagamenti nel checkout del POS