VibeFox Nets Nexi for PrestaShop — Guida

Requisiti

PrestaShop: da 8.0 a 9.x.

PHP: 8.0 o successivo con l'estensione cURL. Il modulo non si installa su versioni precedenti di PHP o senza cURL.

Account Nets: ti servono le chiavi segrete del tuo account Nets Easy (test e produzione). Vengono usate solo le chiavi segrete. Le chiavi di checkout non servono, perché i clienti pagano sulla pagina di pagamento ospitata da Nets.

Valute e metodi di pagamento: il modulo non limita da sé valute e paesi. Usa le valute abilitate nel tuo account Nets; una valuta non supportata viene segnalata da Nets alla creazione del pagamento. I metodi di pagamento visibili al cliente dipendono dal tuo contratto Nets, dal paese e dalla valuta.

HTTPS per i webhook: Nets chiama solo indirizzi HTTPS pubblici di massimo 256 caratteri e senza "&", quindi il tuo negozio ha bisogno di HTTPS e di URL semplici per ricevere i webhook. Senza webhook il pagamento viene comunque confermato quando il cliente torna nel negozio o con la verifica dello stato nella pagina dell'ordine.

Chiave di licenza VibeFox: acquistata 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 Nets Nexi 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 alto nella pagina Configure, e fai clic su Activate (vedi Chiave di licenza).

4. Copia la chiave segreta di test dal portale di test di Nets Easy e incollala in Test Secret Key (vedi Configurazione).

5. Attiva Enable/Disable, lascia attivo Test Mode, fai clic su Save ed effettua un ordine di prova. Poi inserisci la chiave segreta di produzione e disattiva Test Mode.

All'installazione il modulo crea lo stato dell'ordine Nets payment on hold. PrestaShop collega un nuovo modulo di pagamento solo ai paesi attivi al momento dell'installazione. Controlla valute, paesi e gruppi di clienti del modulo in Payment > Preferences.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox Nets Nexi Gateway > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Sopra i campi la pagina ti avvisa se manca la chiave segreta della modalità selezionata, per esempio con Nets Nexi: enter the Test Secret Key — the payment method is hidden at checkout until the key of the selected mode is set., e mostra Nets Nexi is in test mode: payments go to the Nets test environment and no real money is charged. finché la modalità test è attiva.

Nets Nexi (paesi nordici)

Il titolo della sezione mostra TEST o LIVE per la modalità selezionata.

Enable/Disable: Enable Nets Nexi Gateway attiva o disattiva il metodo di pagamento. Predefinito: disattivato.

Title: il titolo del metodo di pagamento mostrato ai clienti durante il checkout. È anche il nome del metodo di pagamento salvato nell'ordine. Predefinito: Nets Easy. Obbligatorio: un titolo vuoto genera l'errore Enter a title for the payment method. e non viene salvato nulla.

Description: la descrizione del metodo di pagamento mostrata ai clienti durante il checkout. Predefinito: Pay securely with Nets Easy.

Chiavi API

Copia le chiavi segrete dal portale Nets Easy in Company > Integration: il portale di test (test.portal.dibspayment.eu) per la chiave di test e il portale di produzione (portal.dibspayment.eu) per la chiave di produzione. Le chiavi di checkout non servono.

Test Mode: la modalità test usa test.api.dibspayment.eu con la chiave segreta di test; la modalità di produzione usa api.dibspayment.eu con la chiave segreta di produzione. Rimborsi e acquisizioni di un ordine usano sempre l'ambiente in cui è stato pagato. Predefinito: attivo. Finché è attiva, i clienti vedono Test mode: no real money will be charged. sotto il metodo di pagamento.

Test Secret Key: la chiave segreta API del tuo ambiente di test Nets.

Live Secret Key: la chiave segreta API del tuo ambiente di produzione Nets.

Le chiavi salvate non vengono più mostrate. Il campo resta vuoto e mostra Saved — leave empty to keep it. Inserisci un nuovo valore solo se vuoi cambiarlo.

Clear saved secrets: seleziona una chiave e fai clic su Save per rimuoverla. Un campo vuoto mantiene il valore salvato.

Pagamento

Webhooks: le notifiche Nets (webhook) vengono registrate automaticamente con ogni pagamento. Non c'è nulla da configurare nel portale Nets. La sezione mostra l'indirizzo a cui vengono inviate. Con URL semplici appare così: https://your-shop/module/wcp_nets_nexi_gateway/webhook, eventualmente con un codice lingua come /en/. Se l'indirizzo non è un indirizzo HTTPS pubblico, la sezione ti avvisa che il negozio non riceve webhook; in tal caso i pagamenti vengono confermati quando il cliente torna nel negozio o con Nets: check payment status and capture nella pagina dell'ordine. Vengono registrati questi eventi:

Ogni webhook deve contenere il segreto casuale che il modulo ha creato per quel pagamento. I webhook senza il segreto corretto vengono rifiutati. Il webhook indica solo al modulo quale pagamento è cambiato: il pagamento stesso viene sempre riletto dalle API di Nets con la chiave segreta dell'ambiente in cui è stato effettuato. Il webhook funziona anche quando il negozio è in modalità manutenzione e non è bloccato dalla restrizione per paese del negozio.

Order Status After Payment: lo stato dell'ordine dopo che Nets ha confermato e addebitato il pagamento.

Avanzate

Debug log: registra le chiamate API e le variazioni di stato dei pagamenti in logs/nng_debug.log.php nella cartella del modulo. Il file non può essere aperto dal web. Gli errori vengono sempre registrati. Chiavi e dati dei clienti non vengono registrati. Predefinito: disattivato.

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

Delete Data on Uninstall: elimina le impostazioni del modulo e i registri alla disinstallazione. I dati di pagamento salvati sugli ordini vengono sempre conservati. Predefinito: disattivato.

Checkout

Nel passaggio del pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita Nets Easy) e conferma. Il modulo crea un pagamento Nets per il totale del carrello nella valuta del carrello, con i prodotti, la spedizione, la confezione regalo e gli sconti come righe dell'ordine, e invia il cliente alla pagina di pagamento ospitata da Nets. Il riferimento del pagamento presso Nets è il numero del carrello. E-mail, nome, indirizzo e telefono del cliente vengono passati a Nets quando Nets accetta il loro formato. Il link alla pagina dei termini e condizioni del tuo checkout compare sulla pagina Nets (se non ne è impostata una, la home page del negozio). A questo punto non esiste ancora alcun ordine.

Dopo il pagamento il cliente torna nel tuo negozio. L'ordine viene segnato come pagato solo dopo la conferma di Nets: il modulo legge il pagamento dalle API di Nets, confronta importo prenotato e valuta con il carrello, addebita la prenotazione e solo allora crea l'ordine. Questo avviene con il webhook o al ritorno del cliente, a seconda di quale arriva per primo. Il cliente vede quindi la pagina standard di conferma dell'ordine. Se il pagamento non può ancora essere confermato (Nets non era raggiungibile, oppure un'altra richiesta lo stava confermando in quel momento), una pagina Payment confirmation mostra Your Nets payment is being confirmed. Your order will be created as soon as it is confirmed — please do not pay again. con i pulsanti Check again e Back to checkout.

Se il cliente annulla nella pagina Nets, torna al checkout con The Nets payment was cancelled. You can try again or choose another payment method. Se non è stato pagato nulla, il messaggio è The payment was not completed. You can try again or choose another payment method. Il carrello viene conservato. Al nuovo tentativo il modulo verifica prima il pagamento precedente; se è già pagato, viene creato l'ordine invece di un nuovo pagamento. Altrimenti la sessione Nets precedente viene chiusa prima di avviarne una nuova.

Se Nets non riesce ad avviare il pagamento, il cliente resta al checkout con un breve messaggio, ad esempio Nets could not start the payment with the details of this order. Please check your address and phone number, or choose another payment method., This payment method is temporarily unavailable. Please choose another payment method. o The payment service could not be reached. Please try again in a moment. Un totale del carrello pari a zero mostra The order total must be greater than zero to pay with Nets. I dettagli vengono scritti nel registro.

Il modulo usa solo la pagina di pagamento ospitata. Non prevede un checkout Nets integrato nella pagina, abbonamenti o pagamenti ricorrenti, carte salvate, commissioni sulle fatture, modalità solo autorizzazione né acquisizioni parziali per spedizione.

Ordini e rimborsi

Stati dell'ordine

No order yet: il cliente è stato inviato a Nets e non ha pagato, oppure il pagamento non è ancora confermato. Esiste solo il carrello.

Payment accepted or Delivered: Nets ha confermato e addebitato il pagamento. Lo stato segue Order Status After Payment. Il pagamento viene registrato con l'ID pagamento Nets come ID transazione, e una nota mostra l'ID pagamento, l'ID addebito e il metodo di pagamento.

Nets payment on hold: importo o valuta presso Nets differiscono dal carrello (non acquisito), l'acquisizione è stata rifiutata, oppure il cliente ha pagato dopo che l'ordine era stato annullato (prenotato, non acquisito). La nota lo spiega. Non viene acquisito nulla automaticamente. Dopo aver verificato l'ordine, acquisisci con Nets: check payment status and capture, oppure annulla la prenotazione nel portale Nets.

Canceled: la prenotazione di un ordine in attesa è stata annullata, ad esempio nel portale Nets.

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

Webhook ripetuti e ricaricamenti non addebitano mai due volte né aggiungono note duplicate, e un ordine pagato non viene mai modificato di nuovo dagli eventi Nets. Se un vecchio link di pagamento viene completato per un ordine già pagato, la seconda prenotazione viene rilasciata automaticamente; se era già addebitata, una nota ti chiede di rimborsarla nel portale Nets.

Blocco pagamento Nets Easy

La pagina dell'ordine mostra un blocco Nets Easy payment con ID pagamento, ID addebito, ambiente (con un badge Test environment per i pagamenti di test), stato, importi prenotati e addebitati presso Nets, totale dell'ordine e importo rimborsato, cronologia dei rimborsi e le Nets notes dell'ordine. I pulsanti del blocco funzionano per ogni dipendente che può modificare gli ordini; non serve l'accesso alle pagine dei Moduli.

Nets: check payment status and capture: mostrato per gli ordini non ancora pagati. Legge il pagamento da Nets e acquisisce una prenotazione che corrisponde all'ordine, anche dopo un'acquisizione non riuscita o dopo che hai verificato un ordine in attesa. Se non cambia nulla, una nota spiega perché, ad esempio che il cliente non ha ancora completato il pagamento.

Rimborsi

Nel blocco Nets Easy payment inserisci l'importo (viene compilato l'importo non ancora rimborsato), facoltativamente un motivo, e fai clic su Refund via Nets. Conferma la domanda Refund this amount through Nets? This cannot be undone. Rimborsi totali e parziali sono supportati una volta addebitato il pagamento; un pagamento solo prenotato può essere annullato nel portale Nets. Il rimborso va sull'addebito dell'ordine nell'ambiente in cui è stato pagato. Se Nets non accetta il rimborso, il blocco mostra l'errore e non viene registrato alcun rimborso. Un rimborso riuscito viene aggiunto alla cronologia dei rimborsi e alle note con l'ID rimborso Nets. Un rimborso totale imposta l'ordine su Refunded; un rimborso parziale non cambia lo stato.

Il modulo non crea note di credito. I pulsanti standard di rimborso di PrestaShop nella pagina dell'ordine non restituiscono denaro tramite Nets. I rimborsi effettuati nel portale Nets non vengono sincronizzati; aggiorna l'ordine manualmente se necessario.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox di vibefox.net. Il blocco licenza License — VibeFox Nets Nexi Gateway è il primo blocco di Modules > Module Manager > VibeFox Nets Nexi 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-nets-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, Nets 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 rimborsi funzionano.

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

Nets Nexi non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo e che la modalità selezionata abbia una chiave segreta: Test Secret Key in modalità test, Live Secret Key in modalità di produzione. La pagina delle impostazioni mostra un avviso quando la chiave manca. In Payment > Preferences verifica che il modulo sia consentito per la valuta del carrello, il paese del cliente e il gruppo del cliente.

Il pagamento è andato a buon fine, ma nessun ordine è stato creato: il webhook non ha raggiunto il tuo negozio. Verifica che il negozio usi HTTPS e URL semplici, così che l'indirizzo in Webhooks sia un indirizzo HTTPS pubblico senza "&", e che la chiave segreta dell'ambiente del pagamento sia impostata. L'ordine viene creato anche quando il cliente torna nel negozio dopo il pagamento.

Il webhook risponde Unauthorized: il webhook non conteneva il segreto di quel pagamento. I webhook vengono accettati solo con il segreto registrato con il pagamento.

Il webhook risponde Busy, retry later, Payment lookup failed o Payment not reserved yet: un'altra richiesta stava confermando lo stesso carrello, le API di Nets non erano raggiungibili, o la prenotazione non era ancora visibile. Nets ritenta automaticamente il webhook.

Il webhook risponde Order could not be created, retry later: l'ordine non è stato creato, ad esempio perché il modulo è disattivato. Attiva Debug log per vedere il motivo.

L'URL del webhook mostra Method not allowed nel browser: è normale. L'indirizzo accetta solo richieste da Nets.

Il cliente vede un errore scegliendo Nets: attiva Debug log e controlla il campo Log nella pagina del modulo. This payment method is temporarily unavailable. Please choose another payment method. di solito indica una chiave segreta errata o mancante. Una valuta rifiutata viene segnalata da Nets nel registro.

L'ordine è in Nets payment on hold dopo il pagamento: leggi le Nets notes nel blocco. Se l'acquisizione è stata rifiutata, riprova con Nets: check payment status and capture oppure addebita nel portale Nets. Se importo o valuta non coincidono, controlla il pagamento nel portale Nets. Se il cliente ha pagato dopo l'annullamento, verifica l'ordine e acquisisci o annulla la prenotazione.

Refund via Nets manca o non funziona: i rimborsi sono possibili solo dopo l'addebito del pagamento; il blocco mostra allora un ID addebito. Un rimborso usa la chiave segreta dell'ambiente in cui l'ordine è stato pagato, quindi tale chiave deve essere impostata; altrimenti il blocco indica quale chiave di ambiente manca.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox Nets Nexi 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 eliminati. Se è disattivo, tutte le impostazioni vengono conservate per una successiva reinstallazione. I dati di pagamento Nets degli ordini (pagamenti, addebiti e rimborsi) e lo stato ordine Nets payment on hold vengono sempre conservati, così gli ordini pagati in precedenza possono essere rimborsati anche dopo una reinstallazione. Gli ordini esistenti mantengono le proprie note di pagamento e gli ID transazione.

Nets, Nets Easy e Nexi sono marchi dei rispettivi proprietari. Questo modulo non è affiliato né approvato da Nets o Nexi.