# Gateway Square Terminal Il gateway Square Terminal consente di riscuotere i pagamenti degli ordini WooCommerce sull'hardware [Square Terminal](https://squareup.com/hardware/terminal) direttamente da WCPOS. Il pagamento viene richiesto da WooCommerce e completato su un dispositivo Square Terminal associato; il risultato viene poi registrato nell'ordine. ## Funzionalità[​](#features "Collegamento diretto a Funzionalità") #### Integrazione hardware Invia i pagamenti ai dispositivi Square Terminal associati e riscuoti pagamenti con carta presente #### Associazione semplice Associa i terminali da WooCommerce utilizzando un codice dispositivo Square temporaneo #### Conferma tramite webhook I webhook Square verificati confermano il completamento, con aggiornamento dello stato in tempo reale durante l'attesa #### Transazioni sicure Elaborazione dei pagamenti con carta presente, conforme allo standard PCI, gestita dall'hardware Square #### Sandbox e Produzione Effettuare la validazione nella Square Sandbox prima di passare ai pagamenti in produzione ## Come funziona[​](#how-it-works "Collegamento diretto a Come funziona") A differenza dei gateway basati su SDK nel browser, Square Terminal utilizza la **Terminal API lato server** di Square. Quando si avvia un pagamento, WooCommerce crea un Terminal Checkout per l'ordine e Square lo invia al dispositivo associato. Il cliente effettua il pagamento sul terminale e Square notifica il sito tramite un webhook firmato. Il webhook è il segnale di completamento autorevole; il POS effettua anche un polling in modo che lo stato si aggiorni durante l'attesa. Ciò significa che il dispositivo Square Terminal deve essere online e connesso allo stesso account e alla stessa sede Square, e il sito deve essere raggiungibile pubblicamente tramite HTTPS affinché Square possa recapitare i webhook. ## Installazione[​](#installation "Collegamento diretto a Installazione") 1 #### Installare Square Terminal for WooCommerce Installare da `WP Admin > POS > Impostazioni > Estensioni`, oppure scaricare l'ultimo **file zip del plugin** (non lo zip del codice sorgente o il tarball di GitHub) dalla [pagina delle release su GitHub](https://github.com/wcpos/square-terminal-for-woocommerce/releases) e caricarlo tramite `Plugin > Aggiungi Nuovo > Carica plugin`. 2 #### Configurare le impostazioni di Square 1. Navigare in `WP Admin > WooCommerce > Impostazioni > Pagamenti` 2. Trovare **Square Terminal** nell'elenco dei metodi di pagamento e selezionarlo per aprire le impostazioni 3. Scegliere l'**Ambiente** (`Sandbox` per i test, `Production` per i pagamenti reali) 4. Inserire il proprio **Access Token** per l'ambiente selezionato (Sandbox o Production), disponibile nella [Square Developer Dashboard](https://developer.squareup.com/apps) 5. Inserire il proprio **Location ID** — la sede Square in cui vengono effettuati i pagamenti tramite terminale 6. Inserire la propria **Webhook Signature Key** e il **Webhook Notification URL** (vedere il passaggio successivo) 7. Fare clic su **Convalida impostazioni** per verificare che le credenziali funzionino, quindi salvare nota Non è necessario abilitare il gateway Square Terminal nelle impostazioni di WooCommerce. Verrà abilitato specificamente per il POS in un passaggio successivo. 3 #### Configurare i webhook in Square Square invia un webhook firmato al termine di un pagamento tramite terminale, ed è questo che contrassegna l'ordine come pagato. 1. Nella [Square Developer Dashboard](https://developer.squareup.com/apps), aprire la propria applicazione e andare alla sezione **Webhook** 2. Aggiungere una sottoscrizione per l'evento **`terminal.checkout.updated`** 3. Impostare l'URL di notifica sull'**URL di notifica Webhook** mostrato nelle impostazioni del plugin — deve corrispondere **esattamente** 4. Copiare la **Chiave di firma Webhook** nelle impostazioni del plugin per consentire la verifica degli eventi in arrivo Importante L'URL di notifica Webhook in Square deve corrispondere esattamente al valore nelle impostazioni del plugin e la Chiave di firma Webhook deve essere corretta. In caso di mancata corrispondenza, i pagamenti Square verranno completati sul dispositivo ma l'ordine WooCommerce non verrà aggiornato. 4 #### Associare il Square Terminal 1. Nella stessa pagina delle impostazioni, fare clic su **Crea codice dispositivo** 2. Viene generato e visualizzato un codice di associazione 3. Sul Square Terminal, accedere e inserire il codice nella schermata di associazione del dispositivo 4. Una volta associato, il terminale è collegato alla sede configurata. Prendere nota del suo **ID dispositivo** — sarà necessario inserirlo al momento del pagamento Importante Il terminale deve essere associato correttamente e online prima di poter elaborare i pagamenti. Assicurarsi che l'associazione sia completata prima di procedere. 5 #### Attivare in WCPOS 1. Andare su `WP Admin > POS > Impostazioni > Pagamento` 2. Trovare il gateway **Square Terminal** nell'elenco 3. Attivare il gateway per l'utilizzo nel POS 4. Salvare le impostazioni ## Utilizzo[​](#usage "Collegamento diretto a Utilizzo") ### Elaborazione dei pagamenti[​](#processing-payments "Collegamento diretto a Elaborazione dei pagamenti") 1. **Aggiungere articoli**: Aggiungere i prodotti al carrello nel POS 2. **Selezionare il gateway**: Scegliere "Square Terminal" come metodo di pagamento 3. **Scegliere il dispositivo**: Inserire l'**ID dispositivo terminale** del terminale associato che deve ricevere il pagamento 4. **Avviare il pagamento**: Fare clic su **Avvia pagamento** — Square invia il checkout al dispositivo 5. **Pagamento del cliente**: Il cliente avvicina, inserisce o striscia la carta sul Square Terminal 6. **Completamento automatico**: Quando il webhook verificato di Square conferma il pagamento, l'ordine viene contrassegnato come pagato. Lo stato si aggiorna in tempo reale durante l'attesa. ### Controlli di pagamento[​](#payment-controls "Collegamento diretto a Controlli di pagamento") Quando si utilizza il gateway Square Terminal, sono disponibili le seguenti opzioni: * **Avvia pagamento**: Invia una nuova richiesta di pagamento al terminale selezionato * **Annulla pagamento**: Annulla un pagamento attualmente in corso sul terminale * **Stato del pagamento**: Un'area di stato in tempo reale mostra lo stato corrente del pagamento * **Registro pagamenti**: Un registro per ogni ordine tiene traccia di ogni passaggio e risultato significativo di Square ### Gestione degli ordini[​](#order-management "Collegamento diretto a Gestione degli ordini") * **Completamento tramite webhook**: Gli ordini vengono contrassegnati come pagati solo quando un webhook verificato di Square conferma il pagamento dal terminale * **Tracciamento dei pagamenti**: Gli identificativi Square e un registro dei pagamenti vengono salvati nell'ordine, e i passaggi principali vengono scritti nelle note dell'ordine * **Generazione ricevute**: Le ricevute POS standard vengono generate dopo i pagamenti avvenuti con successo ## Requisiti[​](#requirements "Collegamento diretto a Requisiti") Account Square : Account venditore Square attivo Credenziali API : Access Token, Location ID e Webhook Signature Key dalla Square Developer Dashboard Hardware compatibile : Un dispositivo Square Terminal, online e connesso alla stessa sede Square Sito HTTPS pubblico : Il sito deve essere raggiungibile tramite HTTPS affinché Square possa recapitare i webhook WCPOS : Versione Pro necessaria per il checkout POS ## Compatibilità hardware[​](#hardware-compatibility "Collegamento diretto a Compatibilità hardware") Requisiti di connettività Square Terminal utilizza l'API Terminal lato server di Square: il checkout viene creato dal sito e inviato al dispositivo associato da Square. Il terminale deve essere online e connesso allo stesso account e alla stessa sede Square, e il sito deve ricevere i webhook di Square tramite HTTPS affinché gli ordini vengano aggiornati. ### Terminali supportati[​](#supported-terminals "Collegamento diretto a Terminali supportati") * **Square Terminal** ✅ — Terminale dedicato da banco per pagamenti con carta di Square ## Ambito e limitazioni[​](#scope-and-limitations "Collegamento diretto a Ambito e limitazioni") Ambito v0.1 * Questa versione iniziale è incentrata sui flussi **POS / pagamento ordine**. La disponibilità nel checkout lato cliente è disattivata per impostazione predefinita e deve essere abilitata esplicitamente. * Supporta **solo l'incasso dei pagamenti** — i rimborsi non sono ancora disponibili. Gli identificatori Square vengono salvati nell'ordine per consentire l'aggiunta del supporto ai rimborsi in futuro. ## Risoluzione dei problemi[​](#troubleshooting "Collegamento diretto a Risoluzione dei problemi") ### Problemi comuni[​](#common-issues "Collegamento diretto a Problemi comuni") Il dispositivo non si associa * Assicurarsi di aver inserito il codice dispositivo prima della scadenza — generarne uno nuovo con **Crea codice dispositivo** se necessario * Verificare che il terminale sia online e connesso allo stesso account Square e **ID posizione** del plugin * Verificare che l'**Ambiente** (Sandbox/Produzione) e il **Token di accesso** corrispondano all'account a cui è connesso il terminale La convalida delle impostazioni non riesce * Verificare che il **Token di accesso** corrisponda all'**Ambiente** selezionato (un token Sandbox non funziona in Produzione e viceversa) * Verificare che l'**ID posizione** appartenga a quell'account * Copiare nuovamente il token dalla Square Developer Dashboard in caso di caratteri estranei Il pagamento viene completato sul terminale ma l'ordine non si aggiorna * L'**URL di notifica webhook** in Square deve corrispondere **esattamente** all'impostazione del plugin * Assicurarsi che l'evento **`terminal.checkout.updated`** sia sottoscritto nella Square Developer Dashboard * Verificare che la **Chiave di firma webhook** nel plugin corrisponda a quella in Square * Assicurarsi che il sito sia raggiungibile pubblicamente tramite HTTPS; verificare i tentativi di consegna dei webhook nella Square Dashboard Il pagamento non si avvia * Verificare che sia inserito un **ID dispositivo terminale** valido e che il dispositivo sia associato e online * Verificare che il dispositivo sia connesso all'**ID sede** configurato * Consultare il **Registro pagamenti** e i log degli errori di WordPress per i messaggi dell'API Square ### Ottenere assistenza[​](#getting-help "Collegamento diretto a Ottenere assistenza") Per supporto tecnico: * Visitare il [repository GitHub](https://github.com/wcpos/square-terminal-for-woocommerce) per segnalare problemi * Consultare la [documentazione dell'API Square Terminal](https://developer.squareup.com/docs/terminal-api/overview) per indicazioni sull'hardware e sulle API * Contattare il supporto Square per problemi relativi all'account e all'hardware ## Screenshot[​](#screenshots "Collegamento diretto a Screenshot") Gli screenshot verranno aggiunti in un aggiornamento futuro per mostrare: * Configurazione delle credenziali Square, del webhook e dell'abbinamento del dispositivo * Abilitazione del gateway nelle impostazioni di WCPOS * Flusso di elaborazione del pagamento nella cassa del POS