VibeFox Square for WooCommerce — Guida

Requisiti

WordPress: 6.0 o successivo.

WooCommerce: 7.0 o successivo, installato e attivo. Il plugin non si attiva senza di esso.

PHP: 8.0 o successivo.

Valuta del negozio: la valuta della tua sede Square: USD, CAD, AUD, JPY, GBP o EUR. Per le altre valute il metodo di pagamento viene nascosto al checkout. Square supporta venditori negli Stati Uniti, in Canada, Australia, Giappone, Regno Unito, Irlanda, Francia e Spagna.

Account Square: ti serve un'applicazione nel Square Developer Dashboard. Da lì copi l'Application ID e l'Access Token (pagina Credentials) e il Location ID (pagina Locations). Sandbox e Production hanno valori separati. Non serve alcun webhook: il plugin ottiene l'esito del pagamento direttamente dalla risposta di Square.

Chiave di licenza VibeFox: si acquista su vibefox.net. Una chiave funziona su un dominio.

Installazione

1. In WordPress vai su Plugins > Add New > Upload Plugin, scegli il file ZIP del plugin e clicca su Install Now. Puoi anche caricare la cartella wcp_square_gateway in /wp-content/plugins/ via FTP.

2. Clicca su Activate.

3. Apri le impostazioni: WooCommerce > Settings > Payments > Square > Manage, oppure clicca su Settings sotto il nome del plugin nella pagina Plugins.

4. Inserisci la tua chiave di licenza VibeFox nel blocco licenza in cima alla pagina e clicca su Activate.

5. Lascia attivo Sandbox Mode e inserisci l'Application ID, l'Access Token e il Location ID di sandbox (vedi Configurazione). Salva: il plugin verifica le credenziali con Square.

6. Attiva Enable/Disable e prova un pagamento con le carte di test della guida al test in sandbox di Square. Poi deseleziona Sandbox Mode, inserisci le credenziali di produzione e salva di nuovo.

Configurazione

Tutte le impostazioni sono in un'unica pagina: WooCommerce > Settings > Payments > Square. Sopra i campi la pagina mostra Square Gateway è attualmente in modalità SANDBOX. Non verrà effettuato alcun addebito reale. finché la modalità sandbox è attiva. Ti avvisa quando Square è abilitato ma manca l'Application ID, l'Access Token o il Location ID della modalità selezionata (il metodo di pagamento viene quindi nascosto al checkout), e quando Square non può gestire la valuta del negozio. Nell'elenco dei metodi di pagamento, Square mostra un badge «Test mode» finché la modalità sandbox è attiva.

Al salvataggio il plugin verifica le credenziali della modalità selezionata con Square. Vedi un errore se Square rifiuta l'Access Token, se il Location ID non viene trovato per questo token, se le credenziali non possono essere verificate, o se la valuta della sede è diversa dalla valuta del negozio. Square può addebitare solo nella valuta della sede: il plugin ricorda la valuta della sede verificata e nasconde il metodo di pagamento al checkout per qualsiasi altra valuta, e la pagina delle impostazioni continua a mostrare l'avviso. Ti avvisa anche se un Application ID di sandbox viene usato in modalità live o viceversa.

General

Enable/Disable: Enable Square Payment Gateway attiva o disattiva il metodo di pagamento. Predefinito: off.

Title: il titolo del metodo di pagamento che il cliente vede al checkout. Predefinito: Credit / debit card.

Description: la descrizione del metodo di pagamento che il cliente vede al checkout. Predefinito: Pay securely with your credit or debit card via Square.

Square account

Apri il Square Developer Dashboard, scegli la tua applicazione e copia l'Application ID e l'Access token dalla pagina Credentials (Sandbox e Production hanno valori separati) e il Location ID dalla pagina Locations. La valuta della sede deve corrispondere alla valuta del tuo negozio. La pagina mostra solo i campi delle credenziali della modalità selezionata: i campi sandbox mentre Sandbox Mode è attivo, i campi live quando è disattivato.

Sandbox Mode: Enable sandbox (test) mode. I pagamenti vengono inviati alla sandbox di Square e non viene addebitato denaro reale. Usa le carte di test di Square. Predefinito: on.

Sandbox Application ID: il tuo Application ID Square di sandbox (inizia con sandbox-sq0idb-).

Sandbox Access Token: il tuo Access Token Square di sandbox.

Sandbox Location ID: il tuo Location ID Square di sandbox.

Live Application ID: il tuo Application ID Square di produzione (inizia con sq0idp-).

Live Access Token: il tuo Access Token Square di produzione.

Live Location ID: il tuo Location ID Square di produzione.

Advanced

Debug log: Log API requests and responses. Gli errori vengono sempre registrati. Attivalo per registrare anche ogni richiesta, senza dati di carta o chiavi. I log si trovano in WooCommerce > Status > Logs, origine wcp_square_gateway. Predefinito: off.

Delete data on uninstall: Remove all plugin data when the plugin is deleted. Elimina le impostazioni del gateway e i file di log quando elimini il plugin. I dati di pagamento degli ordini vengono conservati. Predefinito: off.

Checkout

Il cliente sceglie il metodo di pagamento (per impostazione predefinita Credit / debit card) e inserisce la carta nel modulo Square mostrato sotto la descrizione. In modalità sandbox il checkout mostra un avviso sandbox. Quando il cliente clicca su Place order, la carta viene tokenizzata nel browser con verifica dell'acquirente (3-D Secure / SCA): importo, valuta e contatto di fatturazione vengono inviati a Square, e la banca del cliente può chiedere una conferma. Il tuo server riceve solo un token monouso.

Il plugin addebita quindi il token tramite la Square Payments API per il totale dell'ordine nella valuta dell'ordine, con l'ID dell'ordine come riferimento, una nota Order # con il numero dell'ordine e il nome del tuo sito, e l'e-mail di fatturazione. Il pagamento viene acquisito immediatamente. L'ordine viene segnato come pagato solo dopo la conferma di Square: la risposta di Square deve mostrare un pagamento COMPLETED per esattamente il totale dell'ordine, la valuta, l'ID dell'ordine e la sede. Poi il cliente va alla pagina di conferma dell'ordine. Se il pagamento non è COMPLETED o un valore non corrisponde, l'ordine viene messo in attesa con una nota e il cliente va comunque alla pagina di conferma dell'ordine.

Per ogni ordine è in corso un solo tentativo di pagamento alla volta. Se il cliente clicca due volte o paga in due schede, il secondo tentativo mostra Questo ordine è già in fase di pagamento. Attendi un momento e controlla la tua e-mail prima di riprovare. Le richieste sono idempotenti: lo stesso ordine, token e importo non creano mai un secondo pagamento.

Se Square non risponde (problema di rete, timeout, errore del server), la richiesta viene ripetuta una volta con la stessa chiave di idempotenza. Se non arriva ancora risposta, il cliente vede Non è stato possibile ottenere una conferma dal fornitore di pagamenti. Attendi un minuto e riprova: se la tua carta è già stata addebitata, il pagamento verrà riconosciuto e non ti verrà addebitato due volte. La nota dell'ordine ti invita a controllare il Square Dashboard. Al tentativo successivo il plugin cerca prima su Square il pagamento precedente di questo ordine e completa l'ordine con quello, invece di addebitare di nuovo la carta.

Quando la banca rifiuta la carta, il cliente vede un breve messaggio in base al codice di errore di Square, per esempio La tua carta è stata rifiutata. Usa un'altra carta o un altro metodo di pagamento., Il codice di sicurezza della carta (CVV) non è corretto. Controllalo e riprova. oppure La tua banca richiede una verifica aggiuntiva (3-D Secure). Inserisci di nuovo la carta e completa la verifica. Il motivo tecnico finisce nelle note dell'ordine e nel log. Il cliente può riprovare con un'altra carta, anche più tardi dalla pagina Pay for order.

Il metodo di pagamento funziona nel checkout classico, nel blocco Checkout e nella pagina Pay for order. È compatibile con WooCommerce High-Performance Order Storage (HPOS).

Il plugin accetta solo pagamenti con carta, acquisiti immediatamente. Non prevede carte salvate o profili cliente, WooCommerce Subscriptions o Pre-Orders, Apple Pay, Google Pay, Cash App Pay, Afterpay, ACH o gift card Square, pagamenti solo autorizzati, webhook Square, né sincronizzazione di prodotti o giacenze con Square. Le contestazioni si gestiscono nel Square Dashboard.

Ordini e rimborsi

Stati dell'ordine

Pending payment: l'ordine è stato creato e non è ancora stato pagato, per esempio dopo una carta rifiutata o una risposta persa da Square.

Processing: Square ha confermato un pagamento COMPLETED del totale dell'ordine. Questo è lo stato standard di WooCommerce dopo il pagamento (gli ordini con soli prodotti virtuali scaricabili diventano Completati). La nota dell'ordine mostra l'ID del pagamento Square, il marchio della carta con le ultime 4 cifre e la modalità (sandbox o live). L'ID della transazione è l'ID del pagamento Square e, nella schermata dell'ordine, rimanda al pagamento nel Square Dashboard.

On hold: Square ha risposto con un pagamento non COMPLETED, oppure con importo, valuta, riferimento o sede diversi. La nota Square payment needs review mostra l'ID del pagamento, lo stato e gli importi. Verifica l'acquisizione, l'importo e la valuta nel Square Dashboard prima di evadere l'ordine.

Il plugin salva sull'ordine l'ID del pagamento Square, il marchio della carta e le ultime 4 cifre, l'ambiente e la sede. I numeri di carta non vengono mai memorizzati.

Rimborsi

Apri l'ordine, clicca su Refund, inserisci l'importo e clicca su Refund via Credit / debit card (il pulsante mostra il tuo Title). Sono supportati rimborsi totali e parziali. Il rimborso viene inviato all'ambiente (sandbox o produzione) e alla sede in cui è stato effettuato il pagamento, quindi deve essere impostato l'Access Token di quella modalità. Le richieste di rimborso sono idempotenti e vengono ripetute una volta se Square non risponde. Un rimborso accettato da Square (stato PENDING o COMPLETED) viene aggiunto alle note dell'ordine con l'ID del rimborso Square. Se Square lo rifiuta, WooCommerce mostra l'errore e non viene registrato alcun rimborso.

Square completa i rimborsi dal proprio lato. Un rimborso che Square rifiuta in seguito non viene comunicato a WooCommerce, e i rimborsi effettuati nel Square Dashboard non compaiono in WooCommerce.

Chiave di licenza

Il plugin funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza si trova in cima a WooCommerce > Settings > Payments > Square. Incolla la chiave in License key e clicca su Activate. Il blocco mostra lo stato, per esempio la data fino alla quale la licenza è attiva, e il tuo dominio. Usa Check now per ricontrollare lo stato, Change key per inserire un'altra chiave e Remove key per rimuoverla da questo sito. Il link Manage licenses and domains in your account apre il tuo account vibefox.net.

Una chiave funziona su un dominio. Rimuovere la chiave da un sito non libera il suo slot di dominio. Libera lo slot nel tuo account vibefox.net.

Senza una chiave attiva, Square non viene mostrato ai clienti al checkout. Se un pagamento viene avviato comunque, il cliente vede Questo metodo di pagamento non è disponibile. Scegline un altro. I gestori del negozio con accesso effettuato vedono ancora il metodo di pagamento, contrassegnato con (unlicensed — visible to admins only), così puoi configurare e provare il plugin prima di acquistare una chiave. Un promemoria compare nella pagina Plugins e nelle pagine di WooCommerce. Gli ordini esistenti non sono interessati: gli ordini pagati restano pagati, e i rimborsi funzionano.

Quando una licenza scade, il plugin continua a funzionare, ma aggiornamenti e supporto richiedono un rinnovo. Lo stato viene verificato di nuovo automaticamente in background.

Risoluzione dei problemi

Square non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo e che Application ID, Access Token e Location ID della modalità corrente siano compilati. Verifica che la valuta del negozio (o la valuta dell'ordine nella pagina Pay for order) sia USD, CAD, AUD, JPY, GBP o EUR e corrisponda alla valuta della tua sede Square. La pagina delle impostazioni mostra un avviso per ciascuno di questi problemi.

Il modulo della carta non si carica: il cliente vede Non è stato possibile caricare il modulo della carta. Ricarica la pagina o scegli un altro metodo di pagamento. Verifica che Application ID e Location ID appartengano alla modalità selezionata (gli ID sandbox iniziano con sandbox-). Se il cliente clicca troppo presto, compare Il modulo della carta è ancora in caricamento. Attendi un momento e riprova.

I pagamenti vengono rifiutati anche se la carta è valida: la valuta della sede deve coincidere con la valuta del negozio. Salva le impostazioni per vedere il risultato della verifica delle credenziali; dopo una verifica riuscita il metodo viene nascosto per le altre valute.

Square ha rifiutato l'Access Token della modalità selezionata: il token appartiene all'altra modalità oppure è errato. Copialo di nuovo dalla pagina Credentials della tua applicazione e controlla Sandbox Mode.

Il Location ID non è stato trovato per questo Access Token: copia il Location ID dalla pagina Locations della stessa applicazione e della stessa modalità.

Il cliente ha visto «Non è stato possibile ottenere una conferma dal fornitore di pagamenti»: Square non ha risposto. Leggi la nota dell'ordine e controlla i pagamenti di questa sede nel Square Dashboard (riferimento = ID dell'ordine). Se il cliente riprova, il plugin cerca prima il pagamento precedente e completa l'ordine con quello, invece di addebitare di nuovo.

L'ordine è On hold: leggi la nota Square payment needs review. Il pagamento non era COMPLETED, oppure il suo importo, la valuta o la sede differivano dall'ordine. Verificalo nel Square Dashboard, poi evadi l'ordine o rimborsa il pagamento.

Il rimborso non riesce con un messaggio sulla modalità: il pagamento è stato effettuato in modalità sandbox o live, e l'Access Token di quella modalità non è impostato. Inseriscilo e riprova.

Altri errori: attiva Debug log e controlla WooCommerce > Status > Logs, origine wcp_square_gateway.

Il blocco licenza mostra un errore: segui il messaggio nel blocco. Per esempio, se la chiave è già usata su un altro dominio, libera uno slot nel tuo account vibefox.net e clicca su Check now. Se l'indirizzo del sito è cambiato, clicca su Check now per attivare la chiave per il nuovo dominio. Se il server delle licenze non è raggiungibile, il plugin continua a funzionare con l'ultimo stato noto.

Disinstallazione

Disattivare il plugin mantiene tutti i dati. Per rimuoverlo, disattivalo ed eliminalo dalla pagina Plugins. La chiave di licenza e lo stato di licenza di questo plugin vengono sempre rimossi. Le impostazioni del gateway e i file di log vengono rimossi solo se Delete data on uninstall era attivo. Altrimenti restano disponibili per una successiva reinstallazione. Gli ordini esistenti conservano le note di pagamento, gli ID dei pagamenti Square e gli ID delle transazioni.

Square è un marchio registrato del rispettivo titolare. Questo plugin non è affiliato a Square né approvato da Square.