VibeFox Flutterwave for WooCommerce — Guida

Requisiti

WordPress: 5.8 o successivo.

WooCommerce: 7.0 o successivo, installato e attivo. Il plugin non si attiva senza WooCommerce.

PHP: 8.0 o successivo. Il plugin non si attiva su versioni precedenti di PHP.

Account Flutterwave: ti servono le chiavi segrete del tuo account Flutterwave, disponibili nella dashboard Flutterwave sotto Settings, API keys: FLWSECK_TEST-… per la modalità test e FLWSECK-… per la modalità live. Vengono usate solo le chiavi segrete. Le chiavi pubbliche e di crittografia non sono necessarie. Configura anche un webhook con un hash segreto a tua scelta (vedi Configurazione).

Valute: l'importo dell'ordine viene sempre addebitato nella valuta dell'ordine. Il plugin non limita paesi o valute; Flutterwave mostra un errore se il tuo account non supporta la valuta.

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

Installazione

1. In WordPress vai a Plugins > Add New > Upload Plugin, scegli il file ZIP del plugin e fai clic su Install Now. Puoi anche caricare la cartella wcp_flutterwave_payment in /wp-content/plugins/ tramite FTP.

2. Fai clic su Activate.

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

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

5. Inserisci le chiavi segrete, configura il webhook nella dashboard Flutterwave e inserisci lo stesso hash segreto nel plugin (vedi Configurazione).

6. Attiva Enable/Disable, prova un pagamento in modalità test, quindi seleziona Live mode.

Configurazione

Tutte le impostazioni sono su una sola pagina: WooCommerce > Settings > Payments > Flutterwave. Sopra i campi, la pagina mostra Live mode: real payments are accepted. oppure Test mode: no real money is charged. Ti avvisa se la chiave segreta della modalità corrente è vuota, se il campo della chiave live contiene una chiave di test (FLWSECK_TEST-…) in modalità live o se il campo della chiave di test contiene una chiave live (FLWSECK-…) in modalità test; il metodo di pagamento viene quindi nascosto al checkout finché non correggi il problema. Ti avvisa anche se non è impostato un hash segreto del webhook: i webhook vengono rifiutati e i pagamenti confermati solo quando il cliente torna al tuo negozio. Nell'elenco dei metodi di pagamento, Flutterwave risulta da configurare finché non è presente una chiave segreta per la modalità corrente e mostra un badge di modalità test in tale modalità.

Generale

Enable/Disable: Enable Flutterwave Payment attiva o disattiva il metodo di pagamento. Valore predefinito: off.

Title: il titolo del metodo di pagamento che i clienti vedono al checkout. Valore predefinito: Flutterwave.

Description: il testo che i clienti vedono al checkout. Valore predefinito: Pay securely via Card, Bank Transfer, USSD, Mobile Money via Flutterwave.

Chiavi API

Copia le chiavi segrete dalla dashboard Flutterwave sotto Settings, API keys. Le modalità test e live hanno chiavi diverse.

Live mode: Accept real payments (uncheck for test mode). La modalità test usa la chiave segreta di test e non addebita denaro reale. La modalità live usa la chiave segreta live. Valore predefinito: off (modalità test).

Test Secret Key: la tua chiave segreta di test Flutterwave (FLWSECK_TEST-...).

Live Secret Key: la tua chiave segreta live Flutterwave (FLWSECK-...).

Webhook

Il webhook conferma i pagamenti anche quando il cliente non torna al tuo negozio. Nella dashboard Flutterwave sotto Settings, Webhooks, inserisci la Webhook URL mostrata in questa sezione e un hash segreto a tua scelta, in modalità test e live. L'URL ha la forma https://your-site/wc-api/flw_p_webhook/. Il plugin reagisce a questo evento:

Gli altri eventi vengono ignorati.

Secret Hash: l'hash segreto del webhook. Deve corrispondere al valore nelle impostazioni del webhook nella tua dashboard Flutterwave. Flutterwave lo invia con ogni webhook. I webhook senza un hash segreto valido vengono rifiutati. Senza webhook, un pagamento viene confermato solo quando il cliente torna al tuo negozio.

Pagamento

Payment Options: metodi di pagamento separati da virgole da mostrare sulla pagina Flutterwave, per esempio card, banktransfer, ussd, mobilemoney. Lascia vuoto per tutti i metodi attivati sul tuo account. L'elenco viene ripulito al salvataggio.

Autocomplete Orders: Automatically mark orders as completed after successful payment. Se attivato, dopo il pagamento gli ordini passano a Completato invece di In lavorazione, con un solo cambio di stato. Valore predefinito: off.

Avanzate

Debug log: Log Flutterwave API events for debugging in WooCommerce > Status > Logs, origine wcp_flutterwave_payment. Gli errori vengono sempre registrati. Chiavi e dati dei clienti non vengono mai registrati. Valore predefinito: off.

Delete data on uninstall: Remove the gateway settings and logs when the plugin is deleted. Disattivare il plugin non elimina mai nulla. I dati di pagamento salvati negli ordini vengono sempre conservati. Valore predefinito: off.

Checkout

Il cliente sceglie il metodo di pagamento (per impostazione predefinita Flutterwave) ed effettua l'ordine. In modalità test il checkout mostra TEST MODE - no real payments will be processed. È richiesta un'e-mail di fatturazione valida. Il plugin crea un pagamento Flutterwave per il totale dell'ordine nella sua valuta, con e-mail, telefono e nome del cliente, nome e logo del tuo sito, e invia il cliente alla pagina di checkout Flutterwave. Qui il cliente paga con uno dei metodi attivati sul tuo account (o elencati in Payment Options).

Dopo il pagamento il cliente torna al tuo negozio. L'ordine viene segnato come pagato solo dopo la conferma di Flutterwave: tramite webhook o controllo lato server al ritorno del cliente. Se il pagamento non è ancora confermato, per esempio un bonifico bancario o un pagamento USSD o mobile money in sospeso, la pagina di ordine ricevuto mostra Your payment is being confirmed by Flutterwave. You will receive an e-mail as soon as it is confirmed. Se il denaro è arrivato ma il plugin ha messo l'ordine In sospeso per una verifica, per esempio perché l'importo pagato non corrisponde all'ordine, la pagina mostra Your payment was received and your order is being reviewed. We will contact you if anything is needed.

Se il pagamento viene rifiutato, il cliente torna al checkout (o alla pagina Pay for order) con Your payment was declined. You can try again or choose another payment method. Se annulla sulla pagina Flutterwave, un ordine effettuato al checkout viene annullato, un ordine creato manualmente resta non pagato e il messaggio è Payment was cancelled. You can try again or choose another payment method. Se il pagamento non è stato completato, il messaggio è The payment was not completed. You can try again or choose another payment method.

Un cliente può riprovare a pagare un ordine non pagato. Ogni tentativo ha il proprio riferimento e un vecchio link pagato in seguito viene comunque accettato. Se Flutterwave non può avviare il pagamento, il cliente vede un breve messaggio, per esempio Flutterwave is temporarily unavailable. Please try again in a moment or choose another payment method.

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). I testi rivolti ai clienti sono tradotti in francese.

Il plugin accetta solo pagamenti una tantum. Non prevede checkout incorporato o modale sul tuo sito, carte salvate, abbonamenti, pagamenti suddivisi o piani di pagamento. I link di pagamento ospitati non possono essere annullati tramite l'API Flutterwave, quindi un vecchio link di un ordine può ancora essere pagato.

Ordini e rimborsi

Stati degli ordini

Pending payment: il cliente è stato inviato a Flutterwave e non ha ancora pagato, oppure il pagamento è ancora in sospeso presso Flutterwave.

Processing or Completed: il pagamento è stato confermato. Completato viene usato quando Autocomplete Orders è attivo (anche gli ordini con soli prodotti virtuali scaricabili diventano Completato, secondo il comportamento predefinito di WooCommerce). La nota dell'ordine mostra importo, metodo di pagamento, riferimento Flutterwave, transazione e modalità. L'ID transazione dell'ordine è il riferimento Flutterwave.

On hold after payment: l'importo o la valuta verificati non corrispondevano all'ordine, oppure il pagamento è arrivato dopo l'annullamento dell'ordine. La nota lo spiega. Evadi l'ordine o rimborsa il pagamento. Un webhook ripetuto non riapre mai un ordine rimborsato o annullato.

Failed: Flutterwave ha segnalato l'ultimo tentativo di pagamento di un ordine in sospeso come non riuscito o annullato. La nota mostra il motivo.

Cancelled: il cliente ha annullato sulla pagina Flutterwave dopo aver effettuato l'ordine al checkout, oppure l'ordine è stato annullato da te o alla scadenza della riserva delle scorte di WooCommerce.

Se viene ricevuto un secondo pagamento per un ordine già pagato, l'ordine non viene modificato. Una nota ti chiede di rimborsare il duplicato nella dashboard Flutterwave.

Rimborsi

Apri l'ordine, fai clic su Refund, inserisci l'importo e fai clic su Refund via Flutterwave. Sono supportati rimborsi totali e parziali. Il rimborso viene inviato con la chiave segreta della modalità in cui è stato effettuato il pagamento (test o live), quindi tale chiave deve essere impostata. Se Flutterwave rifiuta il rimborso, WooCommerce mostra l'errore e non viene registrato alcun rimborso. Un rimborso riuscito viene aggiunto alle note dell'ordine con ID e stato del rimborso (completato, oppure avviato con lo stato riportato da Flutterwave).

I rimborsi effettuati nella dashboard Flutterwave non vengono sincronizzati con WooCommerce. Se necessario, crea un rimborso manuale in WooCommerce senza Refund via Flutterwave.

Chiave di licenza

Il plugin funziona con una chiave di licenza VibeFox di vibefox.net. Il blocco della licenza si trova in cima a WooCommerce > Settings > Payments > Flutterwave. 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 ricontrollare 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 il relativo posto per il dominio. Libera il posto nel tuo account vibefox.net.

Senza una chiave attiva, Flutterwave non viene mostrato ai clienti al checkout. Se viene comunque avviato un pagamento, il cliente vede This payment method is not available. Please choose another one. I gestori del negozio che hanno effettuato l'accesso vedono ancora il metodo di pagamento, contrassegnato con (unlicensed — visible to admins only), così puoi configurare e provare il plugin prima di acquistare una chiave. Un promemoria appare nella pagina dei plugin e nelle pagine WooCommerce. Gli ordini esistenti non sono interessati: i pagamenti già avviati continuano a essere confermati e i rimborsi funzionano.

Quando una licenza scade, il plugin continua a funzionare, ma aggiornamenti e assistenza richiedono il rinnovo. Lo stato viene ricontrollato automaticamente in background.

Risoluzione dei problemi

Flutterwave non appare al checkout: controlla che la licenza sia attiva, che Enable/Disable sia attivato e che la chiave segreta della modalità corrente sia compilata e corrisponda alla modalità: una chiave di test (FLWSECK_TEST-…) in modalità test, una chiave live (FLWSECK-…) in modalità live. Altrimenti la pagina delle impostazioni mostra un avviso.

Il pagamento è riuscito, ma l'ordine resta Pending payment: il webhook non funziona. Nella dashboard Flutterwave controlla che l'URL del webhook corrisponda esattamente a quello mostrato nelle impostazioni, nella modalità usata (test o live), e che il suo hash segreto sia identico a Secret Hash nel plugin. Bonifici bancari, USSD e mobile money in sospeso restano tali finché Flutterwave non li conferma. Attiva Debug log e consulta WooCommerce > Status > Logs, origine wcp_flutterwave_payment.

Il webhook risponde Invalid hash o Secret hash not configured: l'hash segreto nella dashboard Flutterwave è diverso da quello nel plugin, oppure manca nel plugin. Inserisci lo stesso valore in entrambi i punti.

Il webhook risponde Verification failed o Busy, retry later: non è stato possibile raggiungere Flutterwave per verificare il pagamento, la transazione non è ancora visibile oppure un'altra richiesta stava aggiornando l'ordine. Flutterwave ritenta il webhook.

Il cliente vede Payment gateway is not properly configured: la chiave segreta della modalità corrente manca o appartiene all'altra modalità.

Il cliente vede We could not match this payment to an order: il link di ritorno contiene un riferimento non creato da questo negozio. Se al cliente è stato addebitato l'importo, cerca il pagamento nella dashboard Flutterwave.

Flutterwave mostra un errore sulla sua pagina: il tuo account Flutterwave potrebbe non supportare la valuta dell'ordine o le opzioni di pagamento selezionate.

L'ordine è On hold dopo il pagamento: leggi la nota dell'ordine. L'importo o la valuta verificati non corrispondevano all'ordine, oppure il pagamento è arrivato dopo l'annullamento dell'ordine. Evadi 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 segreta di tale modalità non è configurata. Inseriscila e riprova.

Il blocco della licenza mostra un errore: segui il messaggio nel blocco. Per esempio, se la chiave è già usata su un altro dominio, libera un posto 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.

Per gli sviluppatori, la documentazione del plugin elenca i filtri flw_p_payment_request (dati inviati a Flutterwave), flw_p_currency_decimals (precisione della valuta) e flw_p_icon (icona al checkout).

Disinstallazione

Disattivando il plugin, tutti i dati vengono conservati. Per rimuoverlo, disattivalo ed eliminalo nella pagina Plugins. La chiave e lo stato di licenza di questo plugin vengono sempre rimossi. Le impostazioni del gateway e i registri vengono rimossi solo se Delete data on uninstall era attivato. Altrimenti restano per una successiva reinstallazione. I dati Flutterwave salvati negli ordini vengono sempre conservati. Gli ordini esistenti mantengono note di pagamento e ID transazione.

Flutterwave è un marchio del rispettivo proprietario. Questo plugin non è affiliato a Flutterwave né approvato da Flutterwave.