VibeFox Mollie 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 del negozio: la valuta del carrello deve essere una delle valute supportate da Mollie: AED, AUD, BGN, BRL, CAD, CHF, CZK, DKK, EUR, GBP, HKD, HUF, ILS, ISK, JPY, MXN, MYR, NOK, NZD, PHP, PLN, RON, SEK, SGD, THB, TWD, USD, ZAR. Per le altre valute l'opzione di pagamento non viene mostrata nel checkout. I metodi di pagamento offerti da Mollie dipendono dalla valuta e dal tuo account.

Accesso a internet al tuo negozio: Mollie invia webhook al tuo negozio, quindi il sito deve essere raggiungibile da internet. Senza webhook, gli ordini vengono comunque creati quando il cliente torna da Mollie.

Account Mollie: ti servono le chiavi API da Mollie Dashboard > Developers > API keys. Le chiavi di test iniziano con test_, quelle live con live_. Non servono altre chiavi o segreti. I metodi di pagamento si attivano nel tuo account Mollie.

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 clicca su Upload a module. Scegli il file ZIP del modulo.

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

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

4. Inserisci le tue chiavi API di test e live (vedi Configurazione). Non occorre configurare alcun webhook in Mollie.

5. Attiva Enable/Disable e clicca su Save. Lascia attivo Test Mode finché non hai effettuato un pagamento di prova, poi disattivalo.

Durante l'installazione il modulo crea due stati dell'ordine, Awaiting Mollie payment e Mollie payment on hold. PrestaShop propone 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 Mollie Gateway > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Sopra i campi la pagina ti avvisa quando Mollie è attivo ma la chiave API della modalità corrente è vuota, e quando Mollie non supporta la valuta predefinita del negozio. In entrambi i casi l'opzione di pagamento viene nascosta nel checkout.

Al salvataggio, una chiave API che non inizia con test_ o live_ seguito da almeno 30 lettere e cifre non viene salvata: appare un errore e resta la chiave salvata in precedenza.

Checkout

Enable/Disable: Enable Mollie Gateway attiva o disattiva l'opzione di pagamento. Predefinito: off.

Title: il titolo del metodo di pagamento mostrato al cliente nel checkout. È anche il nome del metodo di pagamento salvato nell'ordine. Predefinito: Mollie. Obbligatorio.

Description: la descrizione del metodo di pagamento mostrata al cliente nel checkout. Predefinito: Pay securely via Mollie.

Chiavi API

Trovi le tue chiavi API nel Mollie Dashboard, sotto Developers > API keys; la sezione rimanda a quella pagina. Le chiavi di test e quelle live sono separate.

Test Mode: usa la chiave API di test per i nuovi pagamenti. Non viene elaborato alcun pagamento reale. Nella pagina di checkout di prova di Mollie puoi scegliere l'esito del pagamento. I clienti vedono Test mode: no real payment will be made. sotto l'opzione di pagamento. I pagamenti effettuati nell'altra modalità continuano a usare la chiave della propria modalità per i controlli dello stato e i rimborsi. Predefinito: on.

Test API Key: la tua chiave API di test di Mollie (inizia con test_).

Live API Key: la tua chiave API live di Mollie (inizia con live_).

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

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

Webhook: mostra l'URL del webhook. Non serve alcuna configurazione: il modulo invia questo URL a Mollie con ogni pagamento. Con gli URL parlanti ha questo aspetto: https://your-shop/module/wcp_mollie_gateway/webhook, eventualmente con un codice lingua. Deve essere raggiungibile da internet, altrimenti gli ordini vengono creati solo quando il cliente torna da Mollie.

Ordini

Order Status After Payment: lo stato dell'ordine impostato dopo un pagamento riuscito. Lo stato viene impostato in un solo passaggio.

I bonifici restano in Awaiting Mollie payment. I pagamenti autorizzati e le differenze di importo o valuta vanno in Mollie payment on hold.

Avanzate

Logging: scrive chiamate API e webhook in logs/molg_debug.log.php, nella cartella del modulo. Il file non può essere aperto dal web. Errori e avvisi vengono sempre registrati, anche con questa opzione disattivata. Le chiavi API e i dati dei clienti non vengono mai registrati. Predefinito: off.

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

Delete Data on Uninstall: se attivo, le impostazioni del modulo e il suo registro vengono eliminati alla disinstallazione del modulo. Gli ID di pagamento Mollie salvati con gli ordini, i registri dei rimborsi e gli stati dell'ordine del modulo restano sempre. Predefinito: off.

Checkout

Nella fase di pagamento il cliente sceglie l'opzione di pagamento (per impostazione predefinita Mollie) e conferma. Il modulo crea un pagamento Mollie per il totale del carrello nella valuta del carrello (JPY e ISK senza decimali), con la descrizione Order # e il numero del carrello, e invia il cliente alla pagina di pagamento ospitata da Mollie. Lì il cliente sceglie uno dei metodi attivati nel tuo account Mollie e paga. In questo momento non esiste ancora alcun ordine.

I webhook di Mollie non hanno firma, contengono solo l'ID del pagamento. Per questo il modulo non si fida mai di un webhook in quanto tale: accetta solo gli ID di pagamento che ha creato lui stesso, legge il pagamento dalle API di Mollie con la chiave della modalità in cui è stato effettuato, verifica che il pagamento appartenga al carrello e confronta importo e valuta pagati con il totale del carrello. L'ordine viene segnato come pagato solo dopo che Mollie lo conferma in questo modo. Il modulo gestisce questi stati di pagamento Mollie:

Quando il cliente torna, il modulo controlla allo stesso modo l'ultimo pagamento del carrello tramite le API di Mollie. Un pagamento effettuato porta alla pagina standard di conferma dell'ordine con Your payment with Mollie has been received. Per un bonifico la pagina mostra Your order will be processed as soon as Mollie receives your bank transfer. Se l'ordine è in attesa, la pagina mostra We are confirming your payment with Mollie. The order will be updated automatically — please do not pay again. Se il pagamento di un ordine esistente non è riuscito o l'ordine è stato annullato, la pagina mostra Your Mollie payment was not completed. Please contact us about this order.

Se il pagamento è stato annullato, non è riuscito, è scaduto o non è stato completato, il cliente torna al checkout con un messaggio, ad esempio You cancelled the Mollie payment. You can try again or choose another payment method. oppure The Mollie payment has expired. Please try again or choose another payment method. Il carrello viene conservato. Se Mollie non è raggiungibile o non ha ancora deciso, compare una pagina Payment confirmation che chiede al cliente di non pagare di nuovo e offre un pulsante Check again; il webhook crea l'ordine appena arriva.

Quando il cliente paga di nuovo, viene riutilizzato il pagamento Mollie ancora aperto dello stesso importo, invece di crearne un secondo pagabile. Se il totale del carrello è cambiato, il vecchio pagamento aperto viene annullato presso Mollie quando Mollie lo consente. Se nel frattempo il vecchio pagamento è stato effettuato, l'ordine viene creato senza un nuovo pagamento.

Se Mollie non riesce ad avviare il pagamento, il cliente resta nel checkout con un breve messaggio, ad esempio The payment provider could not be reached. Please try again in a moment., This payment method is temporarily unavailable. Please choose another payment method. (chiave API errata) oppure Mollie cannot accept a payment of this amount or currency. Please choose another payment method. Il motivo tecnico viene scritto nel registro.

Il webhook funziona anche quando il negozio è in modalità manutenzione e non viene bloccato dalla restrizione per paese del tuo negozio.

Il cliente sceglie il metodo Mollie nella pagina di Mollie, non nel checkout del tuo negozio. Il modulo non prevede abbonamenti o pagamenti ricorrenti, carte salvate o mandati, campi carta sul tuo sito, pulsanti express di Apple Pay o PayPal e non usa le Orders API: per questi pagamenti Mollie non offre quindi i metodi che richiedono righe d'ordine (per esempio alcune varianti di Klarna, Billie o in3). I pagamenti autorizzati si catturano o si annullano nel Mollie Dashboard, non da PrestaShop.

Ordini e rimborsi

Stati dell'ordine

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

Payment accepted o Delivered: il pagamento è stato confermato. Lo stato segue Order Status After Payment. Il pagamento viene registrato con l'ID del pagamento Mollie (tr_...) come ID della transazione, e una nota mostra il pagamento Mollie, il metodo e la modalità.

Awaiting Mollie payment: il cliente ha scelto il bonifico bancario nella pagina di Mollie. L'ordine passa allo stato pagato quando Mollie riceve il denaro.

Mollie payment on hold: un pagamento autorizzato attende la cattura, Mollie ha segnalato una contestazione, l'importo o la valuta pagati erano diversi dal carrello (per esempio il carrello è stato modificato dopo l'avvio del pagamento), un pagamento di prova è stato effettuato mentre il negozio era in modalità live (non è arrivato denaro), oppure il pagamento è arrivato dopo che l'ordine era stato annullato. La nota lo spiega. Verifica il pagamento nel Mollie Dashboard, poi elabora l'ordine o rimborsa il pagamento.

Payment error: un bonifico o un'autorizzazione di un ordine esistente non è riuscito, è scaduto o è stato annullato. Un ordine pagato non viene mai modificato.

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

Se viene pagato un secondo pagamento dello stesso carrello, l'ordine non cambia. Una nota ti chiede di rimborsare il pagamento duplicato nel tuo Mollie Dashboard.

Blocco Mollie payment

La pagina dell'ordine mostra un blocco Mollie payment con l'ID del pagamento Mollie, il metodo, lo stato del pagamento, l'importo pagato e rimborsato, un badge Test mode per i pagamenti di prova, lo storico dei rimborsi e le Mollie notes dell'ordine. Le note sono visibili solo nel back office.

Rimborsi

Nel blocco Mollie payment inserisci l'importo (viene compilato l'importo non ancora rimborsato), facoltativamente un motivo, e clicca su Refund via Mollie. Conferma la domanda Refund this amount through Mollie? This cannot be undone. Sono supportati rimborsi totali e parziali. Ti serve il permesso di modificare gli ordini; l'accesso alle pagine dei moduli non è necessario. I rimborsi vengono effettuati nell'importo e nella valuta addebitati da Mollie, 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 per il pagamento che ha effettivamente saldato l'ordine, con la chiave API della modalità in cui è stato effettuato, quindi quella chiave deve essere impostata. Se Mollie rifiuta il rimborso, il blocco mostra il messaggio di errore di Mollie e nessun rimborso viene registrato. Un rimborso riuscito viene aggiunto allo storico dei rimborsi e alle note con l'ID del rimborso Mollie. Un rimborso totale imposta l'ordine su Refunded. Un rimborso parziale non cambia lo stato. I rimborsi sono disponibili appena Mollie ha segnalato il pagamento come pagato.

Il modulo non crea note di credito. I pulsanti di rimborso standard di PrestaShop nella pagina dell'ordine non restituiscono denaro tramite Mollie. I rimborsi creati nel Mollie Dashboard non vengono mostrati sull'ordine; una contestazione aggiunge una nota.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox Mollie Gateway è il primo blocco nella pagina Modules > Module Manager > VibeFox Mollie Gateway > Configure, sopra le impostazioni. Inserisci la chiave in License key e clicca su Activate. Dopodiché 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 si trovano la riga Product: presta-payment-mollie 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 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: quello del negozio principale, anche in una configurazione multistore. Rimuovere la chiave dal negozio non libera il suo slot di dominio. Liberalo nel tuo account vibefox.net.

Senza una chiave attiva, Mollie non viene mostrato ai clienti nel checkout. Se comunque viene avviato un pagamento, 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 nel 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 a settimana. Non serve alcun cron job. La disinstallazione o il reset del modulo rimuovono sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

Mollie non compare nel checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo e che la modalità corrente abbia una chiave API: Test API Key in modalità test, Live API Key in modalità live. Verifica che la valuta del carrello sia supportata da Mollie. La pagina delle impostazioni mostra un avviso per una chiave mancante e per una valuta del negozio non supportata. 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: il webhook non riesce a raggiungere il tuo negozio. L'URL mostrato in Webhook deve essere raggiungibile da internet (senza autenticazione di base o firewall che lo blocchi). L'ordine viene creato anche quando il cliente torna nel negozio dopo aver pagato, o quando clicca su Check again.

Il webhook risponde Unknown payment.: il pagamento non è stato creato da questo negozio, oppure Mollie non lo conosce con la chiave API della sua modalità, per esempio un pagamento di un altro account Mollie.

Il webhook risponde Payment ID mismatch.: il pagamento non appartiene al carrello per cui è stato creato. Non viene modificato nulla.

Il webhook risponde Failed to fetch payment.: le API di Mollie non sono raggiungibili, oppure la chiave API della modalità del pagamento non è impostata. Mollie riproverà il webhook più tardi.

Il webhook risponde Temporarily unavailable.: il carrello era in elaborazione da un'altra richiesta nello stesso momento, oppure non è stato possibile creare l'ordine (per esempio perché il modulo è disattivato). Mollie riproverà il webhook. Attiva Logging per vedere il motivo.

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

Una chiave API non viene salvata: la chiave deve iniziare con test_ o live_ seguito da almeno 30 lettere e cifre. Copiala di nuovo dal Mollie Dashboard.

Il cliente vede un errore quando sceglie Mollie: controlla il campo Log nella pagina del modulo. Mostra il codice HTTP e il messaggio di Mollie. 401 significa una chiave API errata; 422 indica un campo della richiesta, per esempio un importo o una valuta che Mollie non accetta.

L'ordine è in Mollie payment on hold: leggi le note dell'ordine (vedi Stati dell'ordine), poi elabora l'ordine o rimborsa il pagamento.

Il rimborso non riesce con un messaggio sulla modalità: il pagamento è stato effettuato in modalità test o live, e la chiave API di quella modalità non è impostata. Inseriscila e riprova.

Altre valute o dati di pagamento: gli sviluppatori possono modificare l'elenco delle valute con l'hook actionWcpMollieSupportedCurrencies e la richiesta di pagamento con l'hook actionWcpMolliePaymentData.

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox Mollie 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. Gli ID di pagamento e i registri dei rimborsi Mollie e gli stati dell'ordine Awaiting Mollie payment e Mollie payment on hold restano sempre, quindi gli ordini pagati in precedenza possono essere rimborsati anche dopo una reinstallazione. Gli ordini esistenti conservano le proprie note di pagamento e gli ID delle transazioni.

Mollie è un marchio del suo rispettivo titolare. Questo modulo non è affiliato a Mollie né approvato da Mollie.