VibeFox Nexi XPay for PrestaShop — Guida

Requisiti

PrestaShop: da 8.0 a 9.x.

PHP: 8.0 o successivo. Il modulo rifiuta di installarsi su versioni precedenti di PHP.

Valuta: la valuta del carrello 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: le credenziali 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 dopo l'attivazione dell'account commerciante. Nel back office di Nexi non c'è nulla da configurare: l'indirizzo di notifica viene inviato con ogni pagamento.

Sito pubblico: l'URL di notifica deve essere raggiungibile da internet, senza autenticazione di base né regole del firewall che blocchino Nexi. La modalità manutenzione del negozio non lo blocca. Se la notifica non riesce a raggiungere il negozio, 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. 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, più tardi, trova VibeFox Nexi XPay 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 Test Mode e inserisci l'alias e la chiave MAC di test (vedi Configurazione).

5. Attiva Enable/Disable, fai clic su Save ed effettua un ordine di prova. Quando tutto funziona, inserisci l'alias e la chiave MAC live e disattiva Test Mode.

All'installazione il modulo crea due stati dell'ordine: Awaiting Nexi XPay payment e Nexi XPay payment on hold. PrestaShop propone un nuovo modulo di pagamento per tutte le valute, i paesi e i gruppi di clienti. Puoi limitarlo in Payment > Preferences. Un paese attivato nel negozio dopo l'installazione del modulo deve essere spuntato anche lì.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox Nexi XPay Gateway > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Sopra i campi la pagina mostra Test mode is on: payments go to the Nexi XPay test environment, no real money is charged. finché la modalità test è attiva. Avvisa quando il gateway è attivo ma l'alias o la chiave MAC della modalità corrente sono vuoti, oppure quando la valuta predefinita del negozio non è EUR. In questi casi il metodo di pagamento viene nascosto al checkout. Spazi e interruzioni di riga attorno ai valori incollati vengono rimossi al salvataggio.

Nexi XPay

Enable/Disable: Enable Nexi XPay Gateway attiva o disattiva il metodo di pagamento. Predefinito: off.

Title: il titolo del metodo di pagamento mostrato al cliente al checkout. È anche il nome del metodo di pagamento salvato nell'ordine. Predefinito: Credit Card (Nexi). In modalità test il checkout e l'ordine aggiungono (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 su 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: usa l'ambiente di test di Nexi XPay e le credenziali di test. Disattivalo per accettare pagamenti reali con le credenziali live. Predefinito: on.

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

L'alias e la chiave MAC live sono mostrati nel tuo back office di Nexi XPay (ecommerce.nexi.it) dopo l'attivazione del tuo 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.

Le chiavi MAC salvate non vengono mai mostrate di nuovo. Il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo per cambiarlo.

Eliminare le chiavi salvate: spunta Test MAC Key o Live MAC Key e fai clic su Save per rimuovere una chiave salvata. Un campo vuoto mantiene il valore salvato.

Pagamento

Notification URL: mostrato a titolo informativo. Viene inviato a Nexi con ogni pagamento, quindi non c'è nulla da configurare nel back office di Nexi. Con URL parlanti ha questo aspetto: https://your-shop/module/wcp_nexi_gateway/s2s?id_cart={id_cart}, eventualmente con un codice lingua come /it/, e con il numero del carrello alla fine. Nexi invia l'esito del pagamento a questo URL server-to-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, con l'alias di quell'ambiente e con il codice transazione emesso per quel carrello. Gli esiti che non superano la verifica vengono rifiutati e non modificano nulla.

Acquisizione: quando viene addebitato il denaro.

Order Status After Payment: lo stato dell'ordine dopo un pagamento riuscito.

Avanzate

Debug Log: registra gli eventi di pagamento in logs/nexi_ip_debug.log.php nella cartella del modulo. Il file non può essere aperto dal web. Chiavi MAC, MAC, dati della carta e indirizzi e-mail non vengono registrati. Errori e avvisi, ad esempio una verifica MAC non riuscita, vengono sempre registrati, anche con l'opzione disattivata. Predefinito: off.

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

Delete Data on Uninstall: se attiva, la disinstallazione del modulo rimuove tutte le impostazioni del modulo e il registro. I dati di pagamento Nexi XPay degli ordini e gli stati dell'ordine vengono conservati. Predefinito: off.

Checkout

Al passaggio del pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita Credit Card (Nexi)) e conferma. La pagina successiva mostra Redirecting to Nexi XPay for payment... e invia automaticamente il cliente alla pagina di Nexi XPay, con un pulsante Pay Now come alternativa. Il pagamento viene inviato in EUR per il totale del carrello, con un nuovo codice transazione, l'e-mail del cliente, la descrizione Cart, il numero del carrello e il nome del tuo negozio. La pagina Nexi si apre nella lingua del carrello se è italiano, inglese, spagnolo, francese, tedesco, giapponese, cinese, arabo, russo o portoghese, altrimenti in inglese. In questo momento non esiste ancora alcun ordine.

Il cliente paga e torna al tuo negozio. L'ordine viene segnato come pagato solo dopo un esito Nexi verificato con importo e valuta esatti del carrello: dalla notifica server-to-server o dal ritorno firmato del cliente, a seconda di quale arriva per primo. Poi l'ordine viene creato e il cliente vede la pagina standard di conferma dell'ordine con Your Nexi XPay payment has been received. Se Nexi segnala il pagamento come in attesa, la pagina mostra Your payment is pending confirmation from Nexi XPay. We will update your order as soon as the payment is confirmed. Per un ordine in attesa (acquisizione differita o revisione manuale) mostra We have received your Nexi XPay payment authorization. Your order will be processed shortly. Se un pagamento in attesa fallisce in seguito, la pagina mostra The payment was not completed. Please contact us.

Se l'esito non è ancora stato elaborato quando il cliente torna, compare una pagina con We have not received the payment confirmation from Nexi XPay yet. If you completed the payment, your order will be updated shortly. e un pulsante Check again. La notifica crea l'ordine non appena arriva.

Se il pagamento viene rifiutato o il cliente annulla nella pagina Nexi, torna al checkout e vede uno di questi messaggi: The payment was not completed. Please try again or choose a different payment method., Payment was cancelled. Please try again. oppure We could not confirm the payment. If your card was charged, please contact us before paying again. Non viene creato alcun ordine e il carrello viene conservato, così il cliente può pagare di nuovo. Se il carrello ha già un ordine (ad esempio è stato pagato in un'altra scheda), il cliente va alla conferma dell'ordine invece che a un nuovo pagamento.

Se il modulo non è configurato per la modalità corrente, il cliente vede This payment method is not available right now. Please choose another payment method.

La notifica funziona mentre il negozio è in modalità manutenzione e non è bloccata dalla restrizione per paese del tuo negozio.

Il modulo accetta pagamenti solo nella pagina Nexi XPay. Non prevede rimborsi da PrestaShop, carte salvate o OneClick, abbonamenti o pagamenti ricorrenti, Pay-By-Link, campi incorporati XPay Build né metodi di pagamento selezionati in PrestaShop: la pagina Nexi mostra i metodi attivati sul tuo terminale.

Ordini e rimborsi

Stati dell'ordine

Nessun ordine ancora: il cliente è stato inviato a Nexi e non ha pagato, ha annullato o è stato rifiutato, oppure Nexi non ha ancora confermato il pagamento. Esiste solo il carrello.

Payment accepted, Delivered or Nexi XPay payment on hold: Nexi ha confermato il pagamento. Lo stato segue Order Status After Payment. Il pagamento viene registrato con il codice transazione Nexi come ID transazione, e una nota mostra il codice di autorizzazione, il codice transazione, il marchio della carta e il messaggio di Nexi.

Nexi XPay payment on hold (authorized): è selezionata l'acquisizione differita e il pagamento è solo autorizzato. Acquisiscilo con Capture Nexi XPay payment nella pagina dell'ordine.

Awaiting Nexi XPay payment: Nexi ha segnalato il pagamento in attesa di conferma. L'ordine viene aggiornato con l'esito finale.

Nexi XPay payment on hold after payment: l'importo o la valuta ricevuti da Nexi non corrispondevano al carrello (l'ordine non viene segnato come pagato), oppure è arrivato un pagamento riuscito per un ordine già annullato. La nota lo spiega. Controlla il pagamento nel back office di Nexi XPay e gestisci o rimborsa l'ordine.

Errore di pagamento: un pagamento in attesa è fallito. Lo stesso carrello non può essere pagato di nuovo, quindi il cliente deve effettuare un nuovo ordine.

Un ordine pagato non viene mai retrocesso da un successivo fallimento. Se per un ordine già pagato arriva un altro pagamento riuscito, una nota ti chiede di rimborsarlo nel back office di Nexi XPay se si tratta di un duplicato.

Blocco pagamento Nexi XPay

La pagina dell'ordine mostra un blocco Nexi XPay payment con il codice transazione (codTrans), lo stato e l'esito Nexi, la modalità di acquisizione, l'importo inviato a Nexi e quello ricevuto, il codice di autorizzazione, il marchio della carta, il messaggio di Nexi e la data, un badge Test environment per i pagamenti di test e le Nexi XPay notes dell'ordine.

Acquisizione differita

Per un ordine autorizzato in attesa, fai clic su Capture Nexi XPay payment nel blocco (il pulsante mostra l'importo) e conferma la domanda Capture the authorized amount through Nexi XPay? Ti serve il permesso di modificare gli ordini. Il modulo acquisisce l'importo autorizzato nell'ambiente del pagamento, con le chiavi di quell'ambiente, registra il pagamento e imposta lo stato secondo Order Status After Payment. Se l'acquisizione fallisce, il blocco mostra l'errore, viene aggiunta una nota e l'ordine resta in attesa. Una seconda acquisizione dello stesso pagamento viene rifiutata.

Rimborsi

I rimborsi non si effettuano da PrestaShop, quindi non esiste un pulsante di rimborso per Nexi XPay. Esegui il rimborso nel back office di Nexi XPay, poi registralo manualmente in PrestaShop. I pulsanti di rimborso standard di PrestaShop nella pagina dell'ordine non restituiscono denaro tramite Nexi.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox Nexi XPay Gateway è il primo blocco di Modules > Module Manager > VibeFox Nexi XPay Gateway > Configure, sopra le impostazioni. Inserisci la chiave in License key e fai clic su Activate. Poi il blocco mostra la chiave mascherata, lo stato (per esempio la data fino alla quale la licenza è attiva e il tuo dominio) e i pulsanti Check now per verificare di nuovo lo stato, Change key per inserire un'altra chiave e Remove key per rimuovere la chiave da questo negozio. Sotto compaiono la riga Product: presta-payment-nexi e il link Manage licenses and domains in your account, che apre il tuo account vibefox.net. Solo i collaboratori con il permesso Configure per il modulo possono modificare 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 o License expired on seguito da una data. Dopo aver cambiato l'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: quello 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, Nexi XPay non viene mostrato ai clienti al checkout. Se un pagamento viene avviato comunque, il cliente vede This payment method is not available. Please choose another one. Il front office di PrestaShop non sa che hai effettuato l'accesso al back office, quindi il metodo di pagamento viene nascosto anche a te: puoi configurare il modulo prima di acquistare una chiave, ma non testarlo al checkout. Un promemoria compare in Modules > Module Manager, nella scheda Alerts. Gli ordini esistenti non sono interessati: i pagamenti già avviati vengono comunque confermati e i pagamenti autorizzati possono ancora essere acquisiti.

Quando una licenza scade, il modulo continua a funzionare, ma aggiornamenti e supporto richiedono un rinnovo. Lo stato viene verificato di nuovo automaticamente mentre lavori nel back office: una volta al giorno nei primi 14 giorni dopo l'inserimento della chiave, poi una volta a 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

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 carrello sia EUR. La pagina delle impostazioni mostra un avviso in questi casi. In Payment > Preferences verifica che il modulo sia consentito per EUR, per il paese del cliente e per il gruppo del cliente.

Il pagamento è andato a buon fine, ma non è stato creato alcun ordine: 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 nel campo Log della pagina del modulo.

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 quel carrello. L'esito viene ignorato.

La notifica risponde not_configured o busy: l'alias o la chiave MAC dell'ambiente del pagamento sono vuoti, oppure l'ordine era in aggiornamento da un'altra richiesta nello stesso momento, oppure l'ordine non è stato creato (ad esempio il modulo è disattivato). Nexi ripete la notifica.

L'URL di notifica mostra method_not_allowed nel browser: è normale. L'URL accetta solo richieste da Nexi.

L'ordine è in Nexi XPay payment on hold after payment: leggi le Nexi XPay notes nel blocco dell'ordine. È selezionata l'acquisizione differita (acquisisci il pagamento con il pulsante), l'importo o la valuta non corrispondevano, è arrivato un pagamento per un ordine annullato, oppure Nexi XPay payment on hold è selezionato come stato dopo il pagamento.

Capture Nexi XPay payment è assente o non funziona: il pulsante viene mostrato solo per gli ordini Nexi XPay in attesa come autorizzati con acquisizione differita, e solo ai collaboratori che possono modificare gli ordini. Se l'alias o la chiave MAC dell'ambiente del pagamento sono vuoti, il blocco lo indica. Se l'acquisizione fallisce, leggi l'errore nel blocco e nelle note, ad esempio Nexi XPay refused the capture con il codice e il messaggio di Nexi.

I pagamenti di test non confermano un pagamento live: ogni pagamento viene verificato con le chiavi dell'ambiente in cui è stato avviato. Imposta Test Mode sulla modalità che desideri e usa alias e chiave MAC di quella modalità.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox Nexi XPay Gateway e scegli Uninstall. La chiave di licenza e lo stato della licenza di questo modulo vengono sempre rimossi. Se Delete Data on Uninstall è attivo, le impostazioni del modulo e il registro vengono rimossi. Se è disattivo, tutte le impostazioni vengono conservate per una reinstallazione successiva. I dati di pagamento Nexi XPay degli ordini e gli stati dell'ordine Awaiting Nexi XPay payment e Nexi XPay payment on hold vengono sempre conservati, così i pagamenti autorizzati possono essere ancora acquisiti dopo una reinstallazione. Gli ordini esistenti conservano le note di pagamento e gli ID transazione.

Nexi e XPay sono marchi dei rispettivi titolari. Questo modulo non è affiliato a Nexi né approvato da Nexi.