VibeFox Square for PrestaShop — Guida

Requisiti

PrestaShop: da 8.0 a 9.x.

PHP: 8.0 o successivo. Il modulo non si installa su versioni precedenti di PHP.

Valuta: la valuta del carrello deve essere la valuta della tua sede Square: USD, CAD, AUD, JPY, GBP o EUR. Per le altre valute il metodo di pagamento non viene mostrato nel 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 nessun webhook: il modulo ottiene il risultato del pagamento direttamente dalla risposta di Square.

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

Installazione

1. Nel back office vai su Modules > Module Manager e fai clic su Upload a module. Scegli il file ZIP del modulo.

2. Al termine del caricamento, fai clic su Configure, oppure trova più tardi VibeFox Square Gateway nell'elenco dei moduli e fai clic su Configure.

3. Inserisci la tua chiave di licenza VibeFox in License key, nel blocco licenza in cima alla pagina Configure, e fai clic su Activate (vedi Chiave di licenza).

4. Lascia attivo Sandbox Mode e inserisci Application ID, Access Token e Location ID del sandbox (vedi Configurazione). Fai clic su Save: il modulo verifica le credenziali con Square.

5. Attiva Enable/Disable, salva e prova un pagamento con le carte di test della guida di test del sandbox di Square. Poi disattiva Sandbox Mode, inserisci le credenziali di produzione e salva di nuovo.

All'installazione il modulo crea lo stato dell'ordine Square payment on hold. PrestaShop consente a un nuovo modulo di pagamento di operare sulle valute, sui paesi attivi al momento dell'installazione e sui gruppi di clienti. Controllali, e seleziona i paesi aggiunti in seguito in Payment > Preferences.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox Square Gateway > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. 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 è attivo ma manca l'Application ID, l'Access Token o il Location ID della modalità selezionata (il metodo di pagamento viene allora nascosto nel checkout), quando Square non può elaborare la valuta predefinita del negozio e quando la valuta della tua sede Square è diversa da quella.

Al salvataggio il modulo verifica con Square le credenziali della modalità selezionata. Le impostazioni vengono salvate comunque. Vedi un avviso se Square rifiuta l'Access Token, se il Location ID non viene trovato per questo token, se non è stato possibile verificare le credenziali o se la valuta della sede è diversa da quella del negozio. Square può addebitare solo nella valuta della sede: il modulo ricorda la valuta della sede verificata e nasconde il metodo di pagamento per i carrelli in qualsiasi altra valuta. Ti avvisa anche se un Application ID sandbox viene usato in modalità live, o viceversa.

Square

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 nel checkout. È anche il nome del metodo di pagamento salvato nell'ordine. Predefinito: Credit / debit card. Obbligatorio.

Description: la descrizione del metodo di pagamento che il cliente vede nel checkout. Predefinito: Pay securely with your credit or debit card via Square. In modalità sandbox viene aggiunto (SANDBOX MODE).

Account Square

Apri il Square Developer Dashboard (la sezione contiene un link), 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 finché Sandbox Mode è attivo, quelli live quando è disattivo. Entrambi i set restano salvati.

Sandbox Mode: i pagamenti vanno al 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 per il sandbox (inizia con sandbox-sq0idb-).

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

Sandbox Location ID: il tuo Location ID Square per il 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.

Gli access token salvati non vengono mai mostrati di nuovo. Il campo resta vuoto e mostra Salvato — lascia vuoto per mantenerlo. Inserisci un nuovo valore solo se vuoi modificarlo.

Clear saved secrets: seleziona un access token e fai clic su Save per rimuoverlo. Un campo vuoto mantiene il valore salvato.

Avanzate

Debug log: errori e avvisi vengono sempre registrati. Attivalo per registrare anche ogni richiesta e risposta, senza dati di carta né chiavi, in logs/wc_sqg_debug.log.php nella cartella del modulo. Il file non può essere aperto dal web. Predefinito: off.

Log: mostra la dimensione e le ultime voci del log. Fai clic su Clear log per svuotarlo.

Delete data on uninstall: se attivo, disinstallando il modulo vengono rimosse le impostazioni del gateway e i file di log. I pagamenti e i rimborsi Square degli ordini e lo stato dell'ordine Square payment on hold vengono sempre conservati. Predefinito: off.

Checkout

Nella fase di pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita Credit / debit card) e inserisce la carta nel modulo Square mostrato sotto la descrizione. Quando il cliente conferma l'ordine, la carta viene tokenizzata nel browser con verifica dell'acquirente (3-D Secure / SCA): il totale del carrello, la valuta e l'indirizzo di fatturazione vengono inviati a Square, e la banca del cliente può chiedere una conferma. Il tuo negozio riceve solo un token monouso.

Il modulo addebita poi il token tramite la Square Payments API per il totale del carrello nella valuta del carrello, con l'ID del carrello come riferimento, una nota Cart # con il numero del carrello e il nome del negozio, e l'e-mail del cliente. Il pagamento viene acquisito subito. L'ordine viene segnato come pagato solo dopo la conferma di Square: la risposta di Square deve mostrare un pagamento COMPLETED dell'importo esatto del totale del carrello, con la stessa valuta, lo stesso ID carrello e la stessa sede. L'ordine viene quindi creato con Payment accepted e il cliente vede la pagina standard di conferma dell'ordine con Abbiamo ricevuto il pagamento con la tua carta. e un link alla ricevuta Square. Se il pagamento non è COMPLETED o un valore non corrisponde, l'ordine viene creato in Square payment on hold e la pagina mostra Abbiamo ricevuto il pagamento con la tua carta e lo stiamo verificando. Aggiorneremo il tuo ordine non appena la verifica sarà completata.

Viene eseguito un solo tentativo di pagamento per carrello alla volta. Se il cliente fa clic due volte o paga in due schede, il secondo tentativo vede 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 carrello, lo stesso token di carta e lo stesso importo non creano mai un secondo pagamento, e un carrello che ha già un ordine non viene mai addebitato di nuovo.

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 c'è ancora risposta, il modulo cerca subito il pagamento di questo carrello presso Square. Se lo trova, crea l'ordine con esso. Se non trova alcun pagamento, il cliente resta nel checkout con Non siamo riusciti a ottenere una conferma dal provider di pagamento. Attendi un minuto e riprova: se la tua carta era già stata addebitata, il pagamento verrà riconosciuto e non verrai addebitato due volte. Il tentativo successivo cerca prima di nuovo il pagamento precedente. Se anche per questa ricerca Square non è raggiungibile, l'ordine viene creato in Square payment on hold senza pagamento, con una nota che indica che la carta potrebbe essere stata addebitata, e la pagina di conferma mostra Non siamo riusciti a ottenere una conferma del pagamento con carta da Square. Controlla la tua e-mail e l'estratto conto della carta prima di pagare di nuovo, oppure contattaci.

Quando la banca rifiuta la carta, non viene creato alcun ordine e il cliente resta nel checkout con un breve messaggio in base al codice di errore di Square, ad esempio La tua carta è stata rifiutata. Usa un'altra carta o un altro metodo di pagamento., Il codice di sicurezza (CVV) della carta 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 carrello viene conservato e il cliente può riprovare con un'altra carta. Il motivo tecnico finisce nel log.

Il modulo accetta solo pagamenti con carta, acquisiti immediatamente. Non prevede carte salvate né profili cliente, abbonamenti, Apple Pay, Google Pay, Cash App Pay, Afterpay, ACH o gift card Square, non prevede pagamenti solo autorizzati, webhook Square né sincronizzazione di prodotti o giacenze con Square. Le contestazioni si gestiscono nella Square Dashboard.

Ordini e rimborsi

Stati dell'ordine

No order yet: la carta è stata rifiutata, oppure la risposta di Square è andata persa e non è stato trovato alcun pagamento. Esiste solo il carrello.

Payment accepted: Square ha confermato un pagamento COMPLETED del totale del carrello. Il pagamento viene registrato con l'ID del pagamento Square come ID transazione, e una nota mostra l'ID del pagamento, il marchio della carta con le ultime 4 cifre e la modalità (sandbox o live).

Square payment on hold: Square ha risposto con un pagamento non COMPLETED (ad esempio APPROVED), oppure con un importo, una valuta, un riferimento o una sede diversi. La nota Il pagamento Square deve essere verificato mostra l'ID del pagamento, lo stato e gli importi. Un pagamento COMPLETED viene registrato sull'ordine con l'importo addebitato da Square. Questo stato viene usato anche quando il carrello è cambiato durante il pagamento, e quando la risposta di Square è andata persa e non è stato possibile verificarla (in quel caso non viene registrato alcun pagamento). Verifica il pagamento nella Square Dashboard prima di evadere l'ordine.

Refunded: il pagamento è stato rimborsato integralmente tramite il modulo.

Se per un carrello che ha già un ordine arriva un secondo pagamento, l'ordine non viene modificato. Una nota ti chiede di verificarlo e di rimborsare il duplicato nella Square Dashboard.

Blocco Square

La pagina dell'ordine mostra un blocco Square con l'ID del pagamento Square (collegato al pagamento nella Square Dashboard), lo stato Square, il marchio della carta e le ultime 4 cifre, gli importi Paid / order / refunded, l'ambiente e la sede, un link alla ricevuta Square, un badge Sandbox per i pagamenti sandbox, lo storico dei rimborsi e le Square notes dell'ordine. I numeri di carta non vengono mai memorizzati.

Rimborsi

Nel blocco Square inserisci l'importo (viene precompilato l'importo non ancora rimborsato), facoltativamente un motivo, e fai clic su Refund via Square. Conferma la domanda Rimborsare questo importo tramite Square? Non è possibile annullare l'operazione. Sono supportati rimborsi totali e parziali. Ti serve il permesso di modificare gli ordini. I rimborsi vengono eseguiti nell'importo e nella valuta addebitati da Square, quindi in caso di importo diverso puoi rimborsare fino a quanto il cliente ha effettivamente pagato, non fino al totale dell'ordine. Il rimborso viene inviato all'ambiente (sandbox o produzione) e alla sede in cui è stato effettuato il pagamento, quindi l'Access Token di quella modalità deve essere impostato. 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 allo storico dei rimborsi e alle note con l'ID del rimborso Square. Se Square lo rifiuta, il blocco mostra l'errore e non viene registrato alcun rimborso. Un rimborso totale imposta l'ordine su Refunded. Un rimborso parziale non cambia lo stato.

Il modulo non crea note di credito. I pulsanti di rimborso standard di PrestaShop nella pagina dell'ordine non restituiscono denaro tramite Square. Square completa i rimborsi dal proprio lato: un rimborso che Square rifiuta in seguito non viene comunicato, e i rimborsi effettuati nella Square Dashboard non compaiono in PrestaShop.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox Square Gateway è il primo blocco di Modules > Module Manager > VibeFox Square Gateway > Configure, sopra le impostazioni. Incolla la chiave in License key e fai clic su Activate. Dopo di che il blocco mostra la chiave mascherata, lo stato (ad esempio la data fino alla quale la licenza è attiva e il tuo dominio) e i pulsanti Check now per controllare di nuovo lo stato, Change key per inserire un'altra chiave e Remove key per rimuovere la chiave da questo negozio. Sotto si trovano la riga Product: presta-payment-square e il link Manage licenses and domains in your account, che apre il tuo account vibefox.net. Solo i dipendenti con il permesso Configure per il modulo possono cambiare la chiave. I testi del blocco seguono la lingua del back office (sono inclusi inglese e russo).

Se la chiave non viene accettata, il blocco indica il motivo, ad esempio Key not found, This key belongs to another product, Domain limit reached oppure License expired on seguito da una data. Dopo una modifica dell'indirizzo del negozio, o dopo aver liberato uno slot di dominio nel tuo account, fai clic su Check now. Se il server delle licenze non è raggiungibile, il modulo continua a funzionare con l'ultimo stato noto.

Una chiave funziona su un solo dominio: il dominio del negozio principale, anche in una configurazione multistore. Rimuovere la chiave dal negozio 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 nel checkout. Se un pagamento viene avviato comunque, il cliente vede This payment method is not available. Please choose another one. Lo storefront di PrestaShop non sa che hai effettuato l'accesso al back office, quindi il metodo di pagamento viene nascosto anche per te: puoi configurare il modulo prima di acquistare una chiave, ma non puoi provarlo nel checkout. Un promemoria compare in Modules > Module Manager nella scheda Alerts. Gli ordini esistenti non sono interessati: gli ordini pagati restano pagati e i rimborsi funzionano.

Quando una licenza scade, il modulo continua a funzionare, ma aggiornamenti e supporto richiedono il rinnovo. Lo stato viene ricontrollato automaticamente mentre lavori nel back office: una volta al giorno per i primi 14 giorni dopo l'inserimento della chiave, poi una volta alla settimana. Non serve alcun cron job. Disinstallare o ripristinare il modulo rimuove sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

Square non compare nel checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo e che l'Application ID, l'Access Token e il Location ID della modalità corrente siano compilati. Verifica che la valuta del carrello sia USD, CAD, AUD, JPY, GBP o EUR e che corrisponda alla valuta della tua sede Square. La pagina delle impostazioni mostra un avviso per ciascuno di questi problemi. In Payment > Preferences verifica che il modulo sia consentito per la valuta del carrello, il paese del cliente e il gruppo del cliente.

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 l'Application ID e il Location ID appartengano alla modalità selezionata (gli ID sandbox iniziano con sandbox-). Se il cliente fa clic troppo presto, viene mostrato Il modulo della carta è ancora in caricamento. Attendi un momento e riprova.

Il metodo di pagamento è scomparso dopo il salvataggio: la valuta della sede Square è diversa dalla valuta del carrello. Inserisci il Location ID di una sede Square nella valuta del tuo negozio e salva di nuovo: il metodo torna visibile dopo una verifica riuscita.

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 verifica 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 siamo riusciti a ottenere una conferma dal provider di pagamento: Square non ha risposto e non è ancora stato trovato alcun pagamento. Controlla i pagamenti di questa sede nella Square Dashboard (riferimento = ID del carrello). Se il cliente riprova, il modulo cerca prima il pagamento precedente e crea l'ordine con quello, invece di addebitare di nuovo.

Il cliente ha visto Il pagamento è stato ricevuto, ma non è stato possibile completare l'ordine automaticamente: la carta è stata addebitata, ma PrestaShop non è riuscito a creare l'ordine (ad esempio perché il modulo era disattivato in quel momento). Leggi il log, poi crea l'ordine manualmente oppure rimborsa il pagamento nella Square Dashboard.

L'ordine è in Square payment on hold: leggi le note nel blocco Square (vedi Stati dell'ordine). Verifica il pagamento nella Square Dashboard, poi evadi l'ordine oppure 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 il campo Log nella pagina del modulo.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox Square Gateway e scegli Uninstall. La chiave di licenza e lo stato di licenza di questo modulo vengono sempre rimossi. Se Delete data on uninstall è attivo, vengono rimosse le impostazioni del gateway e i file di log. Se è disattivo, tutte le impostazioni vengono conservate per una reinstallazione successiva. I pagamenti e i rimborsi Square degli ordini e lo stato dell'ordine Square payment on hold vengono sempre conservati, quindi gli ordini pagati in precedenza possono ancora essere rimborsati dopo una reinstallazione. Gli ordini esistenti conservano le proprie note di pagamento, gli ID dei pagamenti Square e gli ID transazione.

Square è un marchio del rispettivo proprietario. Questo modulo non è affiliato a Square né approvato da Square.