VibeFox MultiSafepay for PrestaShop — Guida

Requisiti

PrestaShop: da 8.0 a 9.x.

PHP: 8.0 o successivo. Il modulo rifiuta l'installazione su versioni di PHP precedenti.

Valuta: la valuta del carrello deve essere una valuta accettata da MultiSafepay, ad esempio EUR, USD, GBP, PLN, CHF, SEK, DKK o NOK. Per le altre valute il metodo di pagamento non viene mostrato al checkout.

Account MultiSafepay: ti serve la chiave API del tuo sito web in MultiSafepay Control. Gli account di prova e live hanno chiavi diverse. Non c'è altro da configurare in MultiSafepay: l'indirizzo di notifica viene inviato con ogni pagamento.

Sito pubblico: MultiSafepay deve poter raggiungere il tuo negozio per inviare le notifiche. Altrimenti gli ordini vengono comunque creati quando il cliente torna da MultiSafepay.

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

Installazione

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

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

3. Inserisci la tua chiave di licenza VibeFox nel campo License key del blocco della licenza in cima alla pagina Configure e clicca su Activate (vedi Chiave di licenza).

4. Incolla la chiave API di prova e/o live da MultiSafepay Control (vedi Configurazione).

5. Attiva Enable/Disable e clicca su Save. Prova un pagamento con Test mode attivo, poi disattivalo per accettare pagamenti reali.

All'installazione il modulo crea lo stato dell'ordine MultiSafepay payment on hold. PrestaShop offre un nuovo modulo di pagamento per tutte le valute, i paesi e i gruppi di clienti. Puoi limitarli in Payment > Preferences.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox MultiSafepay Gateway > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Sopra i campi la pagina mostra Test mode: new payments use the MultiSafepay test environment (no real payments). mentre la modalità test è attiva, avvisa quando la modalità corrente non ha una chiave API (in quel caso il metodo di pagamento non viene mostrato al checkout) e quando MultiSafepay non accetta la valuta predefinita del tuo negozio. La pagina non si salva senza un Title.

Checkout

Enable/Disable: Enable MultiSafepay attiva o disattiva il metodo di pagamento. Predefinito: disattivato.

Title: il nome del metodo di pagamento che il cliente vede al checkout. È anche il nome del metodo di pagamento salvato nell'ordine. Predefinito: MultiSafepay. Obbligatorio.

Description: il testo mostrato sotto il metodo di pagamento al checkout. Predefinito: Pay securely with iDEAL, cards, Bancontact, PayPal and more via MultiSafepay.

Chiavi API

La chiave API si trova in MultiSafepay Control > Manage settings > Website settings. La sezione rimanda all'account di prova (testmerchant.multisafepay.com) e all'account live (merchant.multisafepay.com). Hanno chiavi diverse. La modalità test usa solo la chiave di prova, la modalità live solo la chiave live.

Test mode: Use the MultiSafepay test environment (no real payments). Cambia sia l'indirizzo dell'API sia la chiave API. I pagamenti già effettuati continuano a usare l'ambiente in cui sono stati fatti per i controlli di stato e i rimborsi. Predefinito: attivo. Mentre è attivo, i clienti vedono Test mode: no real payment will be made. sotto il metodo di pagamento.

Test API key: la chiave API del tuo account di prova MultiSafepay.

Live API key: la chiave API del tuo account live MultiSafepay.

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

Clear saved keys: seleziona una chiave e clicca su Save per rimuoverla. Un campo vuoto mantiene il valore salvato.

Notifiche

Non c'è nulla da configurare. Il campo Notification URL mostra l'indirizzo che viene inviato a MultiSafepay con ogni pagamento. Con URL leggibili assume questa forma: https://your-shop/module/wcp_multisafepay_gateway/webhook, eventualmente con un codice lingua come /en/. Una notifica indica solo al modulo quale pagamento è cambiato: stato, importo e valuta vengono sempre letti dall'API di MultiSafepay con la tua chiave API prima che un ordine venga creato o modificato. Le notifiche per pagamenti non avviati nel tuo negozio vengono ignorate. La notifica funziona anche quando il negozio è in modalità manutenzione e non è bloccata dalla restrizione per paese del negozio.

Ordini

Order status after payment: lo stato di un ordine pagato. Lo stato viene impostato subito, con un solo cambio di stato e una sola e-mail al cliente.

Avanzate

Debug log: Log API calls and notifications scrive in logs/mspg_debug.log.php nella cartella del modulo. Il file non può essere aperto dal web. Errori e avvisi vengono sempre registrati. Chiavi API e dati dei clienti non vengono mai registrati. Predefinito: disattivato.

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

Delete data on uninstall: se attivo, disinstallando il modulo vengono rimosse le impostazioni e il registro. I dati di pagamento MultiSafepay degli ordini e lo stato dell'ordine restano sempre, quindi i rimborsi di ordini vecchi restano possibili. Disattivare il modulo non cancella mai nulla. Predefinito: disattivato.

Checkout

Al momento del pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita MultiSafepay, con il logo MultiSafepay) e conferma. Il modulo crea un pagamento MultiSafepay per il totale del carrello nella valuta del carrello e invia il cliente alla pagina di pagamento MultiSafepay. Lì il cliente sceglie un metodo di pagamento qualsiasi attivo nel tuo account MultiSafepay e paga. L'indirizzo di fatturazione, l'e-mail, il telefono e la lingua del cliente vengono passati a MultiSafepay, e il pagamento compare come Order #, il numero del carrello e il nome del tuo negozio. In questo momento non esiste ancora alcun ordine.

Dopo il pagamento il cliente torna al tuo negozio. L'ordine viene segnato come pagato solo dopo che MultiSafepay lo ha confermato: tramite la notifica o tramite un controllo con l'API di MultiSafepay quando il cliente torna. L'ordine viene quindi creato e il cliente vede la pagina standard di conferma dell'ordine con Your payment with MultiSafepay has been received. Per un ordine in attesa la pagina mostra We are confirming your payment with MultiSafepay. The order will be updated automatically — please do not pay again. Se il pagamento fallisce in seguito, la pagina mostra Your MultiSafepay payment was not completed. Please contact us about this order. Se MultiSafepay non ha ancora confermato il pagamento quando il cliente torna (per esempio si attende un bonifico bancario), una pagina Payment confirmation mostra lo stesso testo di conferma e un pulsante Check again; la notifica crea l'ordine non appena MultiSafepay segnala il pagamento.

Se il cliente annulla nella pagina di MultiSafepay, oppure il pagamento viene rifiutato o scade, il cliente torna al checkout con il carrello conservato e con uno di questi messaggi: The MultiSafepay payment was cancelled. You can try again or choose another payment method., The payment was declined. Please try again or choose another payment method. oppure The payment session has expired. Please try again.

Prima di creare un nuovo pagamento per lo stesso carrello, il modulo controlla quello precedente presso MultiSafepay. Se è già pagato o in elaborazione, viene creato l'ordine invece di un nuovo pagamento. Se è ancora aperto con lo stesso importo, viene riutilizzata la stessa pagina di pagamento. Se l'importo è cambiato, il vecchio pagamento viene annullato presso MultiSafepay così non può più essere pagato.

Se MultiSafepay non riesce ad avviare il pagamento, il cliente resta al checkout con un breve messaggio, per esempio Could not connect to MultiSafepay. Please try again in a moment. oppure MultiSafepay cannot accept this order amount or currency. Please choose another payment method. Il motivo tecnico viene scritto nel registro.

Il modulo offre un unico metodo di pagamento che porta alla pagina di MultiSafepay. Non ci sono metodi di pagamento PrestaShop separati per ogni metodo di pagamento MultiSafepay, né campi carta integrati, né pulsanti express Apple Pay o Google Pay, né abbonamenti, pagamenti ricorrenti o carte salvate, e non è possibile catturare o annullare da PrestaShop. Non viene inviato alcun dato del carrello, quindi per questi ordini MultiSafepay non offre i metodi di pagamento differito che lo richiedono (per esempio Klarna, in3 o Riverty).

Ordini e rimborsi

Stati dell'ordine

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

Payment accepted o Delivered: MultiSafepay ha confermato il pagamento (completato o spedito). Lo stato segue Order status after payment. Il pagamento viene registrato con l'ID dell'ordine MultiSafepay come ID della transazione, e una nota mostra il pagamento, il metodo di pagamento e l'ambiente.

MultiSafepay payment on hold before payment: il pagamento è non regolato (in esame da parte di MultiSafepay) oppure riservato (autorizzato). Per ricevere i fondi, cattura un pagamento riservato in MultiSafepay Control. L'ordine passa automaticamente allo stato pagato quando MultiSafepay lo segnala come completato.

MultiSafepay payment on hold after payment: MultiSafepay ha confermato un importo o una valuta diversi dal totale del carrello (per esempio il carrello è stato modificato dopo l'avvio del pagamento), un pagamento di prova è stato completato mentre il modulo è in modalità live (non è stato ricevuto denaro reale e nessun pagamento è stato registrato), oppure il pagamento è stato completato dopo l'annullamento dell'ordine. La nota lo spiega. Controlla la transazione in MultiSafepay Control, poi evadi o rimborsa l'ordine.

MultiSafepay payment on hold after a chargeback: MultiSafepay ha segnalato uno storno per un ordine pagato: il denaro è stato sottratto dal tuo conto.

Payment error: un pagamento non regolato o riservato è stato successivamente rifiutato, annullato, scaduto o invalidato.

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

Un ordine pagato o rimborsato non viene mai riaperto da una notifica tardiva. Se per un carrello già pagato viene completato un secondo pagamento, l'ordine non cambia. Una nota ti chiede di rimborsare il duplicato in MultiSafepay Control.

Blocco di pagamento MultiSafepay

La pagina dell'ordine mostra un blocco MultiSafepay payment con l'ID dell'ordine MultiSafepay, il metodo di pagamento, lo stato, l'importo pagato e rimborsato, un badge Test mode per i pagamenti di prova, lo storico dei rimborsi e le MultiSafepay notes dell'ordine.

Rimborsi

Nel blocco MultiSafepay payment inserisci l'importo (viene compilato l'importo non ancora rimborsato), facoltativamente un motivo, e clicca su Refund via MultiSafepay. Conferma la domanda Refund this amount through MultiSafepay? This cannot be undone. Sono supportati rimborsi totali e parziali. Ti serve il permesso di modificare gli ordini; non serve l'accesso alle pagine dei moduli. I rimborsi vengono effettuati nell'importo e nella valuta addebitati da MultiSafepay, quindi dopo una differenza di importo puoi rimborsare fino a quanto il cliente ha effettivamente pagato, non fino al totale dell'ordine. Il rimborso viene inviato all'ambiente in cui è stato effettuato il pagamento (prova o live), quindi la chiave API di quell'ambiente deve essere impostata. Se MultiSafepay non accetta il rimborso, il blocco mostra MultiSafepay refund failed: con l'errore di MultiSafepay, e nessun rimborso viene registrato. Un rimborso riuscito viene aggiunto allo storico dei rimborsi e alle note, con l'ID di rimborso MultiSafepay. Un rimborso totale imposta l'ordine su Refunded. Un rimborso parziale non cambia lo stato. I rimborsi sono disponibili dopo che MultiSafepay ha segnalato il pagamento.

Il modulo non crea note di credito. I pulsanti di rimborso standard di PrestaShop nella pagina dell'ordine non restituiscono denaro tramite MultiSafepay.

I rimborsi effettuati in MultiSafepay Control vengono aggiunti alle note quando MultiSafepay li segnala. Lo stato dell'ordine e le note di credito non vengono modificati automaticamente. Aggiornali manualmente se necessario.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox di vibefox.net. Il blocco della licenza License — VibeFox MultiSafepay Gateway è il primo blocco nella pagina Modules > Module Manager > VibeFox MultiSafepay Gateway > Configure, sopra le impostazioni. Inserisci la chiave nel campo License key e clicca su Activate. Dopo, 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 controllare di nuovo lo stato, Change key per inserire un'altra chiave e Remove key per rimuovere la chiave da questo negozio. Sotto di essi ci sono la riga Product: presta-payment-multisafepay 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 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, per 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, clicca 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, MultiSafepay 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. Lo storefront di PrestaShop non sa che sei connesso al back office, quindi il metodo di pagamento è nascosto anche per 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 il rinnovo. Lo stato viene controllato di nuovo automaticamente mentre lavori nel back office: una volta al giorno nei 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

MultiSafepay non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo, che la modalità corrente abbia una chiave API (Test API key in modalità test, Live API key in modalità live) e che la valuta del carrello sia accettata da MultiSafepay. La pagina delle impostazioni mostra un avviso quando la chiave manca o quando la valuta del negozio non è accettata. 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 non è stato creato alcun ordine: la notifica non ha raggiunto il tuo negozio. Verifica che il negozio sia raggiungibile da internet e che la chiave API dell'ambiente del pagamento sia impostata, perché il modulo legge lo stato dall'API di MultiSafepay. Se l'API non è raggiungibile o la chiave manca, la notifica risponde ERROR e MultiSafepay la ripete. L'ordine viene creato anche quando il cliente torna al negozio e quando tenta di pagare di nuovo lo stesso carrello.

La notifica risponde Invalid request: la richiesta non aveva un ID di transazione valido. Le notifiche di MultiSafepay ne contengono sempre uno.

Il cliente vede un errore quando sceglie MultiSafepay: 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 API errata o mancante. MultiSafepay cannot accept this order amount or currency. Please choose another payment method. significa che MultiSafepay ha rifiutato l'importo o la valuta.

L'ordine è in MultiSafepay payment on hold: leggi le note nel blocco MultiSafepay payment. Il pagamento potrebbe essere non regolato o riservato, l'importo o la valuta pagati potrebbero differire dal carrello, potrebbe essere arrivato un pagamento di prova in modalità live, il pagamento potrebbe essere arrivato dopo l'annullamento dell'ordine, oppure ci potrebbe essere stato uno storno. Controlla la transazione in MultiSafepay Control.

I pagamenti di prova non confermano un ordine live: un pagamento di prova non paga mai un ordine mentre il modulo è in modalità live; l'ordine viene messo in attesa. I pagamenti di prova precedenti vengono comunque controllati e rimborsati con la chiave di prova dopo il passaggio al live.

Il rimborso non riesce con un messaggio sull'ambiente: il pagamento è stato effettuato nell'ambiente di prova o live, e la chiave API di quell'ambiente non è impostata. Inseriscila e riprova.

Disinstallazione

Vai in Modules > Module Manager, apri il menu accanto a VibeFox MultiSafepay 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, vengono rimosse le impostazioni e il registro. Se è disattivo, tutte le impostazioni vengono conservate per una successiva reinstallazione. I dati di pagamento MultiSafepay degli ordini e lo stato dell'ordine MultiSafepay payment on hold restano sempre, quindi gli ordini pagati in precedenza possono essere rimborsati anche dopo una reinstallazione. Gli ordini esistenti conservano le loro note di pagamento e gli ID di transazione.

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