VibeFox Mollie for WooCommerce — Guida

Requisiti

WordPress: 6.0 o successivo.

WooCommerce: 7.0 o successivo, installato e attivo. Senza WooCommerce il plugin non si attiva.

PHP: 8.0 o successivo.

Valuta del negozio: 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 il metodo di pagamento viene nascosto al checkout. Quali metodi di pagamento offre Mollie dipende dalla valuta e dal tuo account.

Accesso a internet al sito: Mollie invia i webhook al tuo negozio, quindi il sito deve essere raggiungibile da internet. Senza webhook, gli ordini vengono comunque aggiornati 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_. 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. In WordPress vai su Plugins > Add New > Upload Plugin, scegli il file ZIP del plugin e fai clic su Install Now. In alternativa puoi caricare la cartella wcp_mollie_gateway in /wp-content/plugins/ via FTP.

2. Fai clic su Activate.

3. Apri le impostazioni: WooCommerce > Settings > Payments > Mollie > Manage, oppure fai clic su Settings sotto il nome del plugin nella pagina Plugin.

4. Inserisci la tua chiave di licenza VibeFox nel blocco licenza in cima alla pagina e fai clic su Activate.

5. Inserisci le chiavi API di test e live (vedi Configurazione). Non è necessario configurare alcun webhook in Mollie.

6. Attiva Enable/Disable. Lascia attivo Test Mode finché non hai effettuato un pagamento di prova, poi deselezionalo.

Configurazione

Tutte le impostazioni si trovano in un'unica pagina: WooCommerce > Settings > Payments > Mollie. 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 del negozio. In entrambi i casi il metodo di pagamento viene nascosto al checkout. Nell'elenco dei metodi di pagamento, Mollie risulta da configurare finché la modalità corrente non ha una chiave API, e mostra Test mode finché la modalità di test è attiva.

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 il valore precedente.

Checkout

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

Title: il titolo del metodo di pagamento mostrato al cliente durante il checkout. Predefinito: Mollie.

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

Chiavi API

Trovi le tue chiavi API in Mollie Dashboard > Developers > API keys. Non serve alcuna configurazione dei webhook: il plugin invia il proprio URL webhook con ogni pagamento. L'URL è mostrato in questa sezione e ha questo aspetto: https://your-site/?wc-api=molg_mollie_webhook. Deve essere raggiungibile da internet, altrimenti gli ordini vengono aggiornati solo quando il cliente torna da Mollie.

Test Mode: Enable test mode usa la chiave API di test per i nuovi pagamenti. Non viene elaborato alcun pagamento reale. Nella pagina di pagamento di test di Mollie puoi scegliere il risultato (paid, failed, cancelled, expired). I clienti vedono Test mode: no real payment will be made. al checkout. I pagamenti effettuati nell'altra modalità continuano a usare la chiave della propria modalità per i controlli dello stato e per i rimborsi. Predefinito: attivo.

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_).

Ordini

Order Status After Payment: lo stato dell'ordine da impostare dopo un pagamento riuscito. Lo stato viene impostato in un unico passaggio, senza un secondo cambio di stato.

Avanzate

Logging: Enable debug logging scrive le chiamate API e i webhook in WooCommerce > Status > Logs, origine wcp_mollie_gateway. Gli errori vengono sempre registrati. Le chiavi API e i dati dei clienti non vengono mai registrati. Predefinito: disattivato.

Delete Data on Uninstall: Remove the plugin settings and logs when uninstalling. Se selezionato, le impostazioni del plugin e i suoi file di log vengono eliminati quando il plugin viene cancellato. Gli ID di pagamento Mollie memorizzati negli ordini vengono conservati. Predefinito: disattivato.

Checkout

Il cliente sceglie il metodo di pagamento (per impostazione predefinita Mollie) e completa l'ordine. Il plugin crea un pagamento Mollie per il totale dell'ordine nella valuta dell'ordine (JPY e ISK senza decimali), con la descrizione Order # seguita dal numero dell'ordine, e invia il cliente alla pagina di pagamento ospitata da Mollie. Lì il cliente sceglie uno dei metodi di pagamento attivati nel tuo account Mollie e paga.

I webhook di Mollie non hanno firma, contengono solo l'ID del pagamento. Per questo il plugin non si fida mai di un webhook in quanto tale: recupera il pagamento dalle API di Mollie con la tua chiave API, verifica che il pagamento appartenga all'ordine e confronta importo e valuta pagati con quelli dell'ordine. L'ordine viene segnato come pagato solo dopo che Mollie lo ha confermato in questo modo. Il plugin gestisce questi stati di pagamento Mollie:

Quando il cliente torna, il plugin verifica l'ultimo pagamento con le API di Mollie allo stesso modo. Un pagamento riuscito porta alla pagina di ricezione dell'ordine. Se il pagamento è stato annullato, non è riuscito, è scaduto o non è concluso, il cliente va alla pagina Pay for order con un messaggio, per 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.

Quando il cliente paga di nuovo, viene riutilizzato il pagamento Mollie ancora aperto dello stesso importo, invece di crearne un secondo da pagare. Se il totale dell'ordine è cambiato, il vecchio pagamento aperto viene annullato in Mollie quando Mollie lo consente. Se nel frattempo il vecchio pagamento è stato effettuato, l'ordine viene segnato come pagato senza un nuovo pagamento.

Se Mollie non riesce ad avviare il pagamento, il cliente vede un breve messaggio, per 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 aggiunto alle note dell'ordine e al log.

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 cliente sceglie il metodo Mollie nella pagina di Mollie, non nel tuo checkout. Il plugin non prevede abbonamenti o pagamenti ricorrenti, carte salvate o mandati, Mollie Components (campi carta sul tuo sito), pulsanti express di Apple Pay o PayPal, né Orders API, quindi Mollie non offre per questi pagamenti i metodi che richiedono righe d'ordine (per esempio alcune varianti di Klarna, Billie o in3). I pagamenti autorizzati si acquisiscono o si annullano nella Mollie Dashboard, non da WooCommerce.

Ordini e rimborsi

Stati dell'ordine

Pending payment: il cliente è stato inviato a Mollie e non ha ancora pagato.

Processing or Completed: il pagamento è confermato. Lo stato segue Order Status After Payment. La nota dell'ordine mostra il pagamento Mollie, il metodo e la modalità. L'ID della transazione è l'ID del pagamento Mollie (tr_...) che ha pagato l'ordine.

On hold: un bonifico attende il denaro, un pagamento autorizzato attende la cattura, oppure Mollie ha segnalato uno storno. Lo stato In attesa viene impostato anche quando l'importo o la valuta pagati differiscono dall'ordine, quando un pagamento di prova è stato effettuato con il negozio in modalità live (non è arrivato denaro), o quando il pagamento arriva dopo l'annullamento dell'ordine. La nota dell'ordine lo spiega. Controlla il pagamento nella Mollie Dashboard, poi elabora l'ordine o rimborsa il pagamento.

Failed: l'ultimo tentativo di pagamento non è riuscito, è scaduto o è stato annullato. Un ordine pagato non viene mai modificato. Il cliente può pagare di nuovo.

Se un secondo pagamento dello stesso ordine viene effettuato, l'ordine non cambia di nuovo. Una nota ti chiede di rimborsare il pagamento duplicato nella tua Mollie Dashboard.

Rimborsi

Apri l'ordine, fai clic su Refund, inserisci l'importo e fai clic su Refund via Mollie (il pulsante mostra il tuo Title). Sono supportati rimborsi totali e parziali. Il rimborso viene inviato per il pagamento che ha effettivamente pagato l'ordine, con la chiave API della modalità in cui è stato effettuato, quindi quella chiave deve essere impostata. Il pulsante è disponibile solo per gli ordini con un pagamento Mollie effettuato. Se Mollie rifiuta il rimborso, WooCommerce mostra il messaggio di errore di Mollie e nessun rimborso viene registrato. Un rimborso riuscito viene aggiunto alle note dell'ordine con l'ID del rimborso Mollie.

I rimborsi e gli storni creati nella Mollie Dashboard non vengono trasformati in rimborsi WooCommerce. Uno storno aggiunge una nota.

Chiave di licenza

Il plugin funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza si trova in cima a WooCommerce > Settings > Payments > Mollie. Incolla la chiave in License key e fai clic 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 dominio. Rimuovere la chiave da un sito non libera lo slot del dominio. Libera lo slot nel tuo account vibefox.net.

Senza una chiave attiva, Mollie 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. 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. Nella pagina Plugin e nelle pagine di WooCommerce compare un promemoria. Gli ordini esistenti non sono interessati: i pagamenti già avviati vengono comunque confermati e i rimborsi funzionano.

Quando una licenza scade, il plugin continua a funzionare, ma aggiornamenti e supporto richiedono il rinnovo. Lo stato viene verificato di nuovo automaticamente in background.

Risoluzione dei problemi

Mollie non compare al 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à di test, Live API Key in modalità live. Verifica che la valuta del negozio (o la valuta dell'ordine nella pagina Pay for order) sia supportata da Mollie. La pagina delle impostazioni mostra un avviso per ciascuno di questi problemi.

Il pagamento è andato a buon fine, ma l'ordine resta Pending payment: il webhook non riesce a raggiungere il tuo sito. L'URL del webhook mostrato nelle impostazioni deve essere raggiungibile da internet (niente modalità manutenzione, autenticazione di base o firewall che lo bloccano). L'ordine viene aggiornato anche quando il cliente torna nel negozio dopo aver pagato.

Webhook answers Unknown payment.: l'ID del pagamento non è noto a Mollie per la tua chiave API di test o live, per esempio un pagamento di un altro account Mollie.

Webhook answers Payment ID mismatch.: il pagamento, secondo i suoi dati, non appartiene all'ordine. L'ordine non viene modificato.

Webhook answers Failed to fetch payment.: le API di Mollie non sono raggiungibili. Mollie riproverà il webhook più tardi.

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

Il pagamento non viene creato: la nota dell'ordine e il log mostrano il codice HTTP e il messaggio di Mollie. 401 significa chiave API errata; 422 indica un campo della richiesta, per esempio un importo o una valuta che Mollie non accetta. Attiva Logging e controlla WooCommerce > Status > Logs, origine wcp_mollie_gateway.

L'ordine è On hold: leggi la nota dell'ordine. Il motivo è una differenza di importo o valuta, un pagamento di prova in modalità live, un pagamento dopo l'annullamento, un bonifico, un'autorizzazione senza cattura o uno storno.

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

Altre valute: gli sviluppatori possono modificare l'elenco delle valute con il filtro molg_supported_currencies.

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 fai clic su Check now. Se l'indirizzo del sito è cambiato, fai clic su Check now per attivare la chiave per il nuovo dominio. Se il server delle licenze non è raggiungibile, il plugin continua a funzionare con l'ultimo stato noto.

Disinstallazione

Disattivare il plugin mantiene 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 file di 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, gli ID dei pagamenti Mollie e gli ID delle transazioni.

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