VibeFox Nexi XPay for WooCommerce — Guida
Requisiti
WordPress: 6.0 o successivo.
WooCommerce: 7.0 o successivo, installato e attivo.
PHP: 8.0 o successivo.
Valuta: la valuta del negozio o dell'ordine deve essere EUR. Per le altre valute il metodo di pagamento viene nascosto al checkout.
Account Nexi XPay: ti serve un account commerciante Nexi XPay (integrazione a reindirizzamento "Pagamento Semplice") con l'alias (ID terminale) e la chiave MAC del tuo terminale. Le credenziali di test e quelle live sono separate: quelle di test si ottengono nell'area test di Nexi XPay o nel portale sviluppatori (developer.nexi.it), quelle live nel back office di Nexi XPay una volta attivato l'account commerciante. Nel back office Nexi non va configurato nulla: l'indirizzo di notifica viene inviato con ogni pagamento.
Sito pubblico: l'URL di notifica deve essere raggiungibile da internet, senza modalità manutenzione, autenticazione di base o regole del firewall che bloccano Nexi. Altrimenti il pagamento viene comunque confermato dal ritorno firmato del cliente.
Chiave di licenza VibeFox: si acquista su vibefox.net. Una chiave funziona su un solo 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_nexi_gateway in /wp-content/plugins/ via FTP.
2. Clicca su Activate.
3. Apri le impostazioni: WooCommerce > Settings > Payments > Nexi XPay > 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 Test Mode e inserisci alias e chiave MAC di test (vedi Configurazione).
6. Attiva Enable/Disable ed effettua un ordine di prova. Quando tutto funziona, inserisci alias e chiave MAC live e deseleziona Test Mode.
Configurazione
Tutte le impostazioni sono in un'unica pagina: WooCommerce > Settings > Payments > Nexi XPay. Sopra i campi la pagina mostra La modalità test è attiva: i pagamenti vanno all'ambiente di test di Nexi XPay e non viene addebitato denaro reale. finché la modalità test è attiva, e avvisa quando il gateway è abilitato ma alias o chiave MAC della modalità corrente sono vuoti, oppure quando la valuta del negozio non è EUR. In entrambi i casi il metodo di pagamento viene nascosto al checkout. Gli spazi e le interruzioni di riga attorno alle chiavi incollate vengono rimossi al salvataggio.
Generali
Enable/Disable: Enable Nexi XPay Gateway attiva o disattiva il metodo di pagamento. Predefinito: disattivato.
Title: il titolo del metodo di pagamento mostrato al cliente al checkout. Predefinito: Credit Card (Nexi). In modalità test il checkout aggiunge (TEST MODE) al titolo.
Description: la descrizione del metodo di pagamento mostrata al cliente al checkout. Predefinito: Pay securely with your credit card via Nexi XPay.
Ambiente di test
I pagamenti di test vanno a int-ecommerce.nexi.it e non addebitano mai carte reali. Ottieni alias e chiave MAC di test nell'area test di Nexi XPay o nel portale sviluppatori (developer.nexi.it).
Test Mode: Enable test mode usa l'ambiente di test di Nexi XPay e le credenziali di test. Deselezionalo per accettare pagamenti reali con le credenziali live. Predefinito: attivo.
Test Alias: l'alias (ID terminale) del tuo terminale di test Nexi XPay.
Test MAC Key: la chiave di calcolo MAC del tuo terminale di test Nexi XPay.
Ambiente live
Alias e chiave MAC live sono mostrati nel tuo back office di Nexi XPay (ecommerce.nexi.it) dopo l'attivazione dell'account commerciante.
Live Alias: l'alias (ID terminale) del tuo terminale live Nexi XPay.
Live MAC Key: la chiave di calcolo MAC del tuo terminale live Nexi XPay.
Pagamento
L'URL di notifica viene inviato a Nexi con ogni pagamento, quindi nel back office non va configurato nulla. La sezione lo mostra; ha questo aspetto https://your-site/wp-json/wc-nexi-gateway/v1/s2s/{order_id}, con l'ID dell'ordine alla fine. Nexi invia l'esito del pagamento a questo URL da server a server e lo passa anche con il ritorno del cliente. Entrambi sono firmati allo stesso modo e vengono verificati con la chiave MAC dell'ambiente in cui è stato effettuato il pagamento, l'alias di quell'ambiente e il codice transazione emesso per quell'ordine. Gli esiti che non superano la verifica vengono rifiutati e non modificano nulla.
Capture: quando il denaro viene addebitato.
Order Status After Payment: lo stato dell'ordine dopo un pagamento riuscito. Lo stato viene impostato subito, con un solo cambio di stato e una sola e-mail.
Avanzate
Debug Log: Enable logging registra gli eventi di pagamento in WooCommerce > Status > Logs, origine wcp_nexi_gateway. Chiavi MAC, dati della carta e indirizzi e-mail non vengono registrati. Errori e avvisi, per esempio una verifica MAC fallita, vengono sempre registrati, anche con l'opzione disattivata. Predefinito: disattivato.
Delete Data on Uninstall: Remove all plugin settings and logs when uninstalled. Predefinito: disattivato.
Checkout
Il cliente sceglie il metodo di pagamento (per impostazione predefinita Credit Card (Nexi)) e conferma l'ordine. La pagina successiva mostra Reindirizzamento a Nexi XPay per il pagamento... e invia automaticamente il cliente alla pagina di Nexi XPay, con un pulsante Pay Now di riserva. Il pagamento viene inviato in EUR con un nuovo codice transazione, l'e-mail del cliente e la descrizione Order, il numero dell'ordine e il nome del tuo sito. La pagina di Nexi si apre nella lingua del negozio se è italiano, inglese, spagnolo, francese, tedesco, giapponese, cinese, arabo, russo o portoghese, altrimenti in inglese.
Il cliente paga e torna alla pagina di conferma ordine del tuo negozio. L'ordine viene segnato come pagato solo dopo un esito Nexi verificato, con importo e valuta esatti dell'ordine: dalla notifica da server a server oppure dal ritorno firmato del cliente, a seconda di quale arriva per primo.
Se il pagamento viene rifiutato o il cliente annulla nella pagina di Nexi, torna al checkout (o alla pagina Pay for order se il carrello è vuoto) e vede uno di questi messaggi: Il pagamento non è stato completato. Riprova o scegli un altro metodo di pagamento., Il pagamento è stato annullato. Riprova. oppure Non siamo riusciti a confermare il pagamento. Se la carta è stata addebitata, contattaci prima di pagare di nuovo. Annullare nella pagina di Nexi lascia l'ordine invariato, quindi il cliente può pagare di nuovo.
Se il plugin non è configurato per la modalità corrente, il cliente vede Questo metodo di pagamento non è disponibile al momento. Scegli un altro metodo di pagamento.
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 pagamenti solo nella pagina di Nexi XPay. Non prevede rimborsi da WooCommerce, carte salvate o OneClick, abbonamenti o pagamenti ricorrenti, Pay-By-Link, campi incorporati XPay Build né metodi di pagamento selezionati in WooCommerce: la pagina di Nexi mostra i metodi attivati sul tuo terminale.
Ordini e rimborsi
Stati dell'ordine
Pagamento in attesa: il cliente è stato inviato a Nexi e non ha ancora pagato, oppure ha annullato nella pagina di Nexi.
In lavorazione, Completato o In attesa: Nexi ha confermato il pagamento. Lo stato segue Order Status After Payment. La nota dell'ordine mostra il codice di autorizzazione, il codice transazione, il marchio della carta e il messaggio di Nexi. L'ID transazione è il codice transazione di Nexi.
In attesa (autorizzato): è selezionata l'acquisizione differita e il pagamento è solo autorizzato. Acquisiscilo con l'azione Capture Nexi XPay payment.
In attesa (in sospeso): Nexi ha segnalato il pagamento in attesa di conferma. L'ordine viene aggiornato con l'esito finale.
In attesa dopo il pagamento: importo o valuta ricevuti da Nexi non corrispondevano all'ordine (l'ordine non viene segnato come pagato), oppure è arrivato un pagamento riuscito per un ordine già annullato. La nota dell'ordine lo spiega. Controlla il pagamento nel back office di Nexi XPay e gestisci o rimborsa l'ordine.
Non riuscito: l'ultimo tentativo di pagamento è stato rifiutato, annullato o si è concluso con un errore. Il cliente può pagare di nuovo.
Un ordine pagato non viene mai retrocesso da un successivo fallimento. Se arriva un altro pagamento riuscito per un ordine già pagato, una nota ti chiede di rimborsarlo nel back office di Nexi XPay se si tratta di un duplicato.
Acquisizione differita
Per un ordine autorizzato in attesa, apri l'ordine, scegli Capture Nexi XPay payment tra le azioni dell'ordine e clicca sulla freccia. Il plugin acquisisce l'importo autorizzato nell'ambiente del pagamento e segna l'ordine come pagato con lo stato di Order Status After Payment. Se l'acquisizione fallisce, l'errore viene mostrato nella schermata dell'ordine e aggiunto alle note, e l'ordine resta in attesa.
Rimborsi
I rimborsi non vengono effettuati da WooCommerce, quindi non c'è il pulsante Refund via. Effettua il rimborso nel back office di Nexi XPay, poi registralo manualmente in WooCommerce.
Chiave di licenza
Il plugin funziona con una chiave di licenza VibeFox acquistata su vibefox.net. Il blocco licenza si trova in cima a WooCommerce > Settings > Payments > Nexi XPay. 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 controllare di nuovo 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 solo 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, Nexi XPay 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. Gli amministratori del negozio connessi vedono ancora il metodo di pagamento, contrassegnato come (unlicensed — visible to admins only), così puoi configurare e testare il plugin prima di acquistare una chiave. Un promemoria compare nella pagina Plugins e nelle pagine di WooCommerce. Gli ordini esistenti non sono coinvolti: i pagamenti già avviati vengono ancora confermati e quelli differiti possono ancora essere acquisiti.
Quando una licenza scade, il plugin continua a funzionare, ma aggiornamenti e supporto richiedono il rinnovo. Lo stato viene controllato di nuovo automaticamente in background.
Risoluzione dei problemi
Nexi XPay non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo, che la modalità corrente abbia entrambe le credenziali (Test Alias e Test MAC Key in modalità test, Live Alias e Live MAC Key in modalità live) e che la valuta del negozio o dell'ordine sia EUR. La pagina delle impostazioni mostra un avviso in questi casi.
Il pagamento è andato a buon fine, ma l'ordine resta In attesa di pagamento: né la notifica né il ritorno del cliente sono stati accettati. Verifica che il negozio sia raggiungibile da internet, che chiave MAC e alias corrispondano all'ambiente (test o live) del pagamento, e attiva Debug Log per vedere cosa ha inviato Nexi in WooCommerce > Status > Logs, origine wcp_nexi_gateway.
La notifica risponde invalid_mac o invalid_alias: la chiave MAC o l'alias nelle impostazioni non corrispondono al terminale che ha inviato l'esito. Copiali di nuovo dall'area test o dal back office di Nexi.
La notifica risponde unknown_transaction: il codice transazione non è stato emesso da questo negozio per quell'ordine. L'esito viene ignorato.
La notifica risponde not_configured o busy: alias o chiave MAC dell'ambiente del pagamento sono vuoti, oppure un'altra richiesta stava aggiornando l'ordine nello stesso momento. Nexi ripete la notifica.
L'ordine è In attesa dopo il pagamento: leggi la nota dell'ordine. È selezionata l'acquisizione differita (acquisisci il pagamento con l'azione dell'ordine), importo o valuta non corrispondevano, è arrivato un pagamento per un ordine annullato, il pagamento è in sospeso presso Nexi, oppure In attesa è selezionato come stato dopo il pagamento.
Capture Nexi XPay payment manca o fallisce: l'azione viene mostrata solo per gli ordini Nexi in attesa come autorizzati con acquisizione differita. Se fallisce, leggi l'errore nelle note dell'ordine; l'acquisizione usa le chiavi dell'ambiente in cui è stato effettuato il pagamento.
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 sul nuovo dominio. Se il server delle licenze non è raggiungibile, il plugin continua a funzionare con l'ultimo stato noto.
Disinstallazione
Disattivare il plugin conserva tutti i dati. Per rimuoverlo, disattivalo ed eliminalo nella pagina Plugins. La chiave di licenza e lo stato della licenza di questo plugin vengono sempre rimossi. Le impostazioni del gateway e i log vengono rimossi solo se Delete Data on Uninstall era attivo. Altrimenti restano per una successiva reinstallazione. Gli ordini esistenti conservano le note di pagamento e gli ID transazione.
Nexi e XPay sono marchi dei rispettivi proprietari. Questo plugin non è affiliato a Nexi né approvato da Nexi.