VibeFox Flutterwave for PrestaShop — Guida

Requisiti

PrestaShop: dalla 8.0 alla 9.x.

PHP: 8.0 o successivo. Il modulo non si installa su versioni precedenti di PHP.

Account Flutterwave: ti servono le chiavi segrete del tuo account Flutterwave, dalla dashboard di Flutterwave in 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. Inoltre configuri un webhook con un hash segreto a tua scelta (vedi Configurazione).

Valute: il carrello viene sempre addebitato nella valuta del carrello. Il modulo non limita di suo paesi o valute; Flutterwave mostra un errore se il tuo account non supporta la valuta. Puoi limitare valute, paesi e gruppi di clienti in Payment > Preferences.

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 in seguito VibeFox Flutterwave Payment nell'elenco dei moduli e fai clic su Configure.

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

4. Inserisci le tue chiavi segrete, configura il webhook nella dashboard di Flutterwave e inserisci nel modulo lo stesso hash segreto (vedi Configurazione).

5. Attiva Enable/Disable e fai clic su Save. Prova un pagamento in modalità test, poi attiva Live mode.

All'installazione il modulo crea due stati dell'ordine, Awaiting Flutterwave payment e Flutterwave payment on hold. PrestaShop propone un nuovo modulo di pagamento per tutte le valute, tutti i paesi e tutti i gruppi di clienti. Puoi limitarlo in Payment > Preferences.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox Flutterwave Payment > Configure. Ogni sezione ha il proprio pulsante Save, che salva l'intera pagina. Sopra i campi la pagina mostra Live mode: real payments are accepted. oppure Test mode: no real money is charged. Ti avvisa quando la chiave segreta della modalità attuale è vuota, quando il campo della chiave live contiene una chiave di test (FLWSECK_TEST-…) in modalità live, o quando il campo della chiave di test contiene una chiave live (FLWSECK-…) in modalità test; in tali casi il metodo di pagamento viene nascosto al checkout finché il problema non viene risolto. Ti avvisa anche quando non è impostato alcun hash segreto del webhook: i webhook vengono rifiutati e i pagamenti vengono confermati solo quando il cliente torna al tuo negozio. Il titolo della prima sezione mostra la modalità attuale, TEST o LIVE.

Flutterwave

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

Title: il titolo del metodo di pagamento che i clienti vedono al checkout. È anche il nome del metodo di pagamento salvato nell'ordine. Predefinito: Flutterwave. Obbligatorio.

Description: il testo che i clienti vedono sotto il metodo di pagamento al checkout. Predefinito: Pay securely via Card, Bank Transfer, USSD, Mobile Money via Flutterwave.

Chiavi API

Copia le chiavi segrete dalla dashboard di Flutterwave in Settings, API keys (la sezione contiene un link). La modalità test e la modalità live hanno chiavi diverse.

Live mode: accetta pagamenti reali. Disattivalo per la modalità test. La modalità test usa la chiave segreta di test e non viene addebitato denaro reale. La modalità live usa la chiave segreta live. Predefinito: disattivato (modalità test). Finché la modalità test è attiva, i clienti vedono TEST MODE - no real payments will be processed. sotto il metodo di pagamento.

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

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

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

Webhook

Il webhook conferma i pagamenti anche quando il cliente non torna al tuo negozio. Nella dashboard di Flutterwave, in Settings, Webhooks, inserisci l'URL mostrato in Webhook URL in questa sezione e un hash segreto a tua scelta, sia in modalità test sia in modalità live. Con URL semplificati l'URL ha questa forma: https://your-shop/module/wcp_flutterwave_payment/webhook, eventualmente con un codice lingua come /en/. Copia l'URL esattamente come lo mostrano le impostazioni. Il modulo reagisce a questo evento:

Gli altri eventi vengono ignorati.

Secret Hash: l'hash segreto del webhook. Deve corrispondere al valore nelle impostazioni del webhook della tua dashboard di Flutterwave. Flutterwave lo invia con ogni webhook, e lo stesso valore viene usato per la modalità test e per quella live. I webhook senza un hash segreto valido vengono rifiutati. Senza il webhook, un pagamento viene confermato solo quando il cliente torna al tuo negozio.

Clear saved secrets: spunta Test Secret Key, Live Secret Key o Secret Hash e fai clic su Save per rimuoverlo. Un campo vuoto mantiene il valore salvato.

Pagamento

Payment Options: metodi di pagamento separati da virgole da mostrare nella pagina di Flutterwave, ad esempio card, banktransfer, ussd, mobilemoney. Lascia vuoto per mostrare tutti i metodi attivati nel tuo account. L'elenco viene ripulito al salvataggio (minuscole, senza duplicati).

Autocomplete Orders: gli ordini pagati ricevono lo stato Delivered invece di Payment accepted, con un unico cambio di stato. Predefinito: disattivato.

Avanzate

Debug log: registra gli eventi dell'API di Flutterwave a scopo di debug in logs/flwv_debug.log.php, nella cartella del modulo. Il file non può essere aperto dal web. Errori e avvisi vengono sempre registrati. Chiavi, hash segreto e dati dei clienti non vengono mai registrati. Predefinito: disattivato.

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

Delete data on uninstall: rimuove le impostazioni e i registri del modulo quando il modulo viene disinstallato. I dati di pagamento salvati sugli ordini vengono sempre conservati. Predefinito: disattivato.

Checkout

Nella fase di pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita Flutterwave) e conferma. È richiesto un indirizzo e-mail valido. Il modulo crea un pagamento Flutterwave per il totale del carrello nella valuta del carrello, con l'e-mail del cliente, il telefono e il nome dell'indirizzo di fatturazione, il nome e il logo del tuo negozio, e invia il cliente alla pagina di pagamento di Flutterwave. Lì il cliente paga con uno dei metodi attivati nel tuo account (o elencati in Payment Options). A questo punto non esiste ancora alcun ordine.

Dopo il pagamento, il cliente torna al tuo negozio. L'ordine viene segnato come pagato solo dopo che Flutterwave lo ha confermato: tramite il webhook o tramite un controllo lato server quando il cliente torna. Solo allora l'ordine viene creato e il cliente vede la pagina standard di conferma dell'ordine. Se il pagamento è ancora in sospeso, ad esempio un bonifico bancario, un pagamento USSD o mobile money, l'ordine viene creato in Awaiting Flutterwave payment e la pagina mostra Your payment is being confirmed by Flutterwave. You will receive an e-mail as soon as it is confirmed. Se l'ordine è stato messo in attesa di verifica, ad esempio perché l'importo pagato non corrisponde al carrello, la pagina mostra Your payment was received and your order is being reviewed. We will contact you if anything is needed. Se un pagamento in sospeso fallisce in seguito e il cliente riapre la pagina di conferma, questa mostra Your Flutterwave payment was not completed. Please contact us about this order.

Se Flutterwave non risponde quando il cliente torna, una pagina Payment confirmation dice Your payment is being confirmed by Flutterwave. 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. Il webhook crea l'ordine non appena arriva.

Se il pagamento viene rifiutato, il cliente torna al checkout con Your payment was declined. You can try again or choose another payment method. Se il cliente annulla nella pagina di Flutterwave, 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. Il carrello viene conservato e il cliente può pagare di nuovo. Ogni tentativo ha il proprio riferimento, e un vecchio link di pagamento pagato in seguito viene comunque accettato.

Se Flutterwave non riesce ad avviare il pagamento, il cliente resta al checkout con un breve messaggio, ad esempio Flutterwave is temporarily unavailable. Please try again in a moment or choose another payment method. Il motivo tecnico viene scritto nel registro.

Se il carrello cambia tra il pagamento e la sua conferma, ad esempio in un'altra scheda del browser, gli importi non corrispondono più e l'ordine passa in Flutterwave payment on hold con una nota.

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

Il modulo 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 di Flutterwave, quindi un vecchio link di un carrello può ancora essere pagato.

Ordini e rimborsi

Stati dell'ordine

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

Payment accepted or Delivered: il pagamento è stato confermato. Delivered viene usato quando Autocomplete Orders è attivo. Il pagamento viene registrato con il riferimento Flutterwave (flw_ref) come ID transazione, e una nota mostra l'importo, il metodo di pagamento, il riferimento, la transazione e la modalità.

Awaiting Flutterwave payment: il cliente è tornato mentre il pagamento era ancora in sospeso presso Flutterwave. L'ordine passa allo stato pagato quando Flutterwave conferma il pagamento.

Flutterwave payment on hold: l'importo o la valuta verificati non corrispondevano al carrello, oppure il pagamento è arrivato dopo che l'ordine era stato annullato. Il pagamento viene registrato con l'importo effettivamente pagato (non con quello che Flutterwave ha addebitato in un'altra valuta). La nota lo spiega. Evadi l'ordine o rimborsa il pagamento. Un ordine rimborsato o annullato non viene mai riaperto da un webhook ripetuto.

Payment error: Flutterwave ha segnalato che l'ultimo tentativo di pagamento di un ordine in attesa è fallito o è stato annullato. La nota mostra il motivo.

Canceled: impostato da te. Se Flutterwave segnala in seguito un pagamento per un ordine annullato, l'ordine passa in Flutterwave payment on hold (vedi sopra).

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

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

Blocco pagamento Flutterwave

La pagina dell'ordine mostra un blocco Flutterwave payment con il riferimento (tx_ref), l'ID transazione e il riferimento Flutterwave, la modalità, lo stato e il metodo di pagamento, l'importo pagato e rimborsato, un badge Test mode per i pagamenti di test, la cronologia dei rimborsi e le Flutterwave notes dell'ordine.

Rimborsi

Nel blocco Flutterwave payment inserisci l'importo (viene compilato l'importo non ancora rimborsato), facoltativamente un motivo, e fai clic su Refund via Flutterwave. Conferma la domanda Refund this amount through Flutterwave? This cannot be undone. Sono supportati rimborsi totali e parziali. Ti serve il permesso di modificare gli ordini; non è necessario l'accesso alle pagine dei Moduli. I rimborsi vengono effettuati nell'importo e nella valuta addebitati da Flutterwave, quindi dopo una discrepanza di importo o valuta puoi rimborsare fino a quanto il cliente ha effettivamente pagato, non fino al totale dell'ordine. Il rimborso viene inviato con la chiave segreta della modalità in cui è stato effettuato il pagamento (test o live), quindi quella chiave deve essere impostata. Se Flutterwave rifiuta 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 e lo stato del rimborso (completed, oppure initiated con lo stato comunicato da Flutterwave). Un rimborso totale imposta l'ordine su Refunded. Un rimborso parziale non cambia lo stato. I rimborsi sono disponibili dopo che Flutterwave ha confermato il pagamento.

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

I rimborsi effettuati nella dashboard di Flutterwave non vengono sincronizzati con PrestaShop. Aggiorna manualmente lo stato dell'ordine se necessario.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox Flutterwave Payment è il primo blocco di Modules > Module Manager > VibeFox Flutterwave Payment > 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 controllare di nuovo lo stato, Change key per inserire un'altra chiave e Remove key per rimuovere la chiave da questo negozio. Sotto ci sono la riga Product: presta-payment-flutterwave 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, 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: 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, Flutterwave 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. La vetrina 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 puoi provarlo 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 ricontrollato automaticamente mentre lavori nel back office: una volta al giorno per i 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

Flutterwave non compare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo e che la chiave segreta della modalità attuale sia compilata e corrisponda alla modalità: una chiave di test (FLWSECK_TEST-…) in modalità test, una chiave live (FLWSECK-…) in modalità live. La pagina delle impostazioni mostra un avviso in caso contrario. 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 funziona. Nella dashboard di Flutterwave verifica che l'URL del webhook sia esattamente quello mostrato in Webhook URL, nella modalità che usi (test o live), e che il suo hash segreto sia uguale a Secret Hash nel modulo. I bonifici bancari, USSD e mobile money in sospeso restano tali finché Flutterwave non li conferma. L'ordine viene creato anche quando il cliente torna al negozio dopo aver pagato. Attiva Debug log e controlla il campo Log nella pagina del modulo.

Il webhook risponde Invalid hash o Secret hash not configured: l'hash segreto nella dashboard di Flutterwave è diverso da quello nel modulo, oppure il modulo non ne ha uno. Inserisci lo stesso valore in entrambi i punti.

Il webhook risponde Verification failed, Busy, retry later o Order could not be created, retry later: Flutterwave non è stato raggiunto per verificare il pagamento, la transazione non è ancora visibile, il carrello era in elaborazione da un'altra richiesta, oppure l'ordine non è stato creato (ad esempio perché il modulo è disattivato). Flutterwave ritenta il webhook. Il registro mostra il motivo.

L'URL del webhook mostra Empty body nel browser: è normale. L'URL accetta solo webhook da Flutterwave.

Il cliente vede Payment gateway is not properly configured: la chiave segreta della modalità attuale 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 che non appartiene al carrello del cliente. Se il cliente è stato addebitato, cerca il pagamento nella dashboard di Flutterwave.

Flutterwave mostra un errore sulla sua pagina, oppure il cliente vede Flutterwave could not start the payment: il tuo account Flutterwave potrebbe non supportare la valuta del carrello o le opzioni di pagamento selezionate.

L'ordine è in Flutterwave payment on hold dopo il pagamento: leggi le note nel blocco Flutterwave payment (vedi Stati dell'ordine), poi evadi l'ordine o rimborsa il pagamento.

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

Il rimborso risponde Another operation on this payment is running: in quel momento era in corso l'invio di un altro rimborso dello stesso ordine. Attendi un momento, controlla la cronologia dei rimborsi e riprova se necessario.

Per gli sviluppatori, il README del modulo elenca gli hook actionWcpFlutterwavePaymentRequest (dati inviati a Flutterwave) e actionWcpFlutterwaveCurrencyDecimals (precisione della valuta).

Disinstallazione

Vai su Modules > Module Manager, apri il menu accanto a VibeFox Flutterwave Payment 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 successiva reinstallazione. I dati di pagamento Flutterwave e i rimborsi degli ordini, insieme agli stati dell'ordine Awaiting Flutterwave payment e Flutterwave payment on hold, vengono sempre conservati, quindi gli ordini pagati in precedenza possono ancora essere rimborsati dopo una reinstallazione. Gli ordini esistenti conservano le proprie note di pagamento e gli ID transazione.

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