VibeFox Flutterwave for WooCommerce — Aide
Prérequis
WordPress: 5.8 ou ultérieur.
WooCommerce: 7.0 ou ultérieur, installé et actif. L'extension refuse de s'activer sans WooCommerce.
PHP: 8.0 ou ultérieur. L'extension refuse de s'activer sur une version antérieure de PHP.
Compte Flutterwave : vous avez besoin des clés secrètes de votre compte Flutterwave, disponibles dans le tableau de bord Flutterwave sous Settings, API keys : FLWSECK_TEST-… pour le mode test et FLWSECK-… pour le mode production. Seules les clés secrètes sont utilisées. Les clés publiques et de chiffrement ne sont pas nécessaires. Configurez également un webhook avec un hachage secret de votre choix (voir Configuration).
Devises : la commande est toujours débitée dans sa devise. L'extension ne restreint ni les pays ni les devises ; Flutterwave affiche une erreur si votre compte ne prend pas en charge la devise.
Clé de licence VibeFox : achetée sur vibefox.net. Une clé fonctionne sur un domaine.
Installation
1. Dans WordPress, accédez à Plugins > Add New > Upload Plugin, choisissez le fichier ZIP de l'extension et cliquez sur Install Now. Vous pouvez aussi transférer le dossier wcp_flutterwave_payment dans /wp-content/plugins/ par FTP.
2. Cliquez sur Activate.
3. Ouvrez les réglages : WooCommerce > Settings > Payments > Flutterwave > Manage, ou cliquez sur Settings sous le nom de l'extension sur la page des extensions.
4. Saisissez votre clé de licence VibeFox dans le bloc de licence en haut de la page et cliquez sur Activate.
5. Saisissez vos clés secrètes, configurez le webhook dans le tableau de bord Flutterwave et saisissez le même hachage secret dans l'extension (voir Configuration).
6. Activez Enable/Disable, testez un paiement en mode test, puis cochez Live mode.
Configuration
Tous les réglages sont sur une seule page : WooCommerce > Settings > Payments > Flutterwave. Au-dessus des champs, la page affiche Live mode: real payments are accepted. ou Test mode: no real money is charged. Elle vous avertit si la clé secrète du mode actuel est vide, si le champ de clé de production contient une clé de test (FLWSECK_TEST-…) en mode production, ou si le champ de clé de test contient une clé de production (FLWSECK-…) en mode test ; la méthode de paiement est alors masquée au paiement jusqu'à correction. Elle vous avertit aussi si aucun hachage secret de webhook n'est défini : les webhooks sont alors rejetés et les paiements confirmés uniquement lorsque le client revient dans votre boutique. Dans la liste des méthodes de paiement, Flutterwave est indiqué comme nécessitant une configuration tant que le mode actuel ne dispose pas d'une clé secrète, et affiche un badge de mode test dans ce mode.
Général
Enable/Disable: Enable Flutterwave Payment active ou désactive la méthode de paiement. Valeur par défaut : off.
Title: le titre de la méthode de paiement affiché aux clients au paiement. Valeur par défaut : Flutterwave.
Description: le texte affiché aux clients au paiement. Valeur par défaut : Pay securely via Card, Bank Transfer, USSD, Mobile Money via Flutterwave.
Clés API
Copiez les clés secrètes du tableau de bord Flutterwave sous Settings, API keys. Les modes test et production utilisent des clés différentes.
Live mode: Accept real payments (uncheck for test mode). Le mode test utilise la clé secrète de test et aucun argent réel n'est débité. Le mode production utilise la clé secrète de production. Valeur par défaut : off (mode test).
Test Secret Key: votre clé secrète de test Flutterwave (FLWSECK_TEST-...).
Live Secret Key: votre clé secrète de production Flutterwave (FLWSECK-...).
Webhook
Le webhook confirme les paiements même si le client ne revient pas dans votre boutique. Dans le tableau de bord Flutterwave sous Settings, Webhooks, saisissez la Webhook URL affichée dans cette section et un hachage secret de votre choix, en mode test et en mode production. L'URL ressemble à https://your-site/wc-api/flw_p_webhook/. L'extension réagit à cet événement :
Les autres événements sont ignorés.
Secret Hash: le hachage secret du webhook. Il doit correspondre à la valeur des réglages du webhook dans votre tableau de bord Flutterwave. Flutterwave l'envoie avec chaque webhook. Les webhooks sans hachage secret valide sont rejetés. Sans webhook, un paiement est confirmé uniquement lorsque le client revient dans votre boutique.
Paiement
Payment Options: méthodes de paiement séparées par des virgules à afficher sur la page Flutterwave, par exemple card, banktransfer, ussd, mobilemoney. Laissez vide pour toutes les méthodes activées sur votre compte. La liste est nettoyée à l'enregistrement.
Autocomplete Orders: Automatically mark orders as completed after successful payment. Si l'option est activée, les commandes passent à Terminée au lieu de En cours après paiement, avec un seul changement de statut. Valeur par défaut : off.
Avancé
Debug log: Log Flutterwave API events for debugging dans WooCommerce > Status > Logs, source wcp_flutterwave_payment. Les erreurs sont toujours journalisées. Les clés et les données clients ne le sont jamais. Valeur par défaut : off.
Delete data on uninstall: Remove the gateway settings and logs when the plugin is deleted. Désactiver l'extension ne supprime jamais rien. Les données de paiement enregistrées dans les commandes sont toujours conservées. Valeur par défaut : off.
Paiement
Le client choisit la méthode de paiement (par défaut Flutterwave) et passe commande. En mode test, la page de paiement affiche TEST MODE - no real payments will be processed. Une adresse e-mail de facturation valide est requise. L'extension crée un paiement Flutterwave pour le total de la commande dans sa devise, avec l'e-mail, le téléphone et le nom du client ainsi que le nom et le logo de votre site, puis dirige le client vers la page de paiement Flutterwave. Il y paie avec une des méthodes activées sur votre compte (ou indiquées dans Payment Options).
Après avoir payé, le client revient dans votre boutique. La commande n'est marquée payée qu'après confirmation de Flutterwave : par le webhook ou par une vérification côté serveur au retour du client. Si le paiement n'est pas encore confirmé, par exemple un virement bancaire, un paiement USSD ou mobile money en attente, la page de commande reçue affiche Your payment is being confirmed by Flutterwave. You will receive an e-mail as soon as it is confirmed. Si l'argent est arrivé mais que l'extension a mis la commande En attente pour vérification, par exemple parce que le montant payé ne correspond pas à la commande, la page affiche Your payment was received and your order is being reviewed. We will contact you if anything is needed.
Si le paiement est refusé, le client revient au paiement (ou à la page Pay for order) avec Your payment was declined. You can try again or choose another payment method. S'il annule sur la page Flutterwave, une commande passée au paiement est annulée, une commande créée manuellement reste impayée, et le message est Payment was cancelled. You can try again or choose another payment method. Si le paiement n'a pas été effectué jusqu'au bout, le message est The payment was not completed. You can try again or choose another payment method.
Un client peut tenter à nouveau de payer une commande impayée. Chaque tentative possède sa propre référence, et un ancien lien payé plus tard reste accepté. Si Flutterwave ne peut pas lancer le paiement, le client voit un court message, par exemple Flutterwave is temporarily unavailable. Please try again in a moment or choose another payment method.
La méthode de paiement fonctionne sur le paiement classique, sur le bloc Paiement et sur la page Pay for order. Elle est compatible avec WooCommerce High-Performance Order Storage (HPOS). Les textes destinés aux clients sont traduits en français.
L'extension accepte uniquement les paiements ponctuels. Elle ne propose ni paiement intégré ou dans une fenêtre modale sur votre site, ni cartes enregistrées, abonnements, paiements fractionnés ou plans de paiement. Les liens de paiement hébergés ne peuvent pas être annulés via l'API Flutterwave ; un ancien lien de commande peut donc toujours être payé.
Commandes et remboursements
Statuts de commande
Pending payment: le client a été dirigé vers Flutterwave et n'a pas encore payé, ou le paiement est toujours en attente chez Flutterwave.
Processing or Completed: le paiement a été confirmé. Le statut Terminée est utilisé lorsque Autocomplete Orders est activé (les commandes contenant uniquement des produits virtuels téléchargeables passent également à Terminée, selon le comportement par défaut de WooCommerce). La note de commande indique le montant, la méthode de paiement, la référence Flutterwave, la transaction et le mode. L'identifiant de transaction de la commande est la référence Flutterwave.
On hold after payment: le montant ou la devise vérifiés ne correspondaient pas à la commande, ou le paiement est arrivé après son annulation. La note l'explique. Exécutez la commande ou remboursez le paiement. Un webhook rejoué ne rouvre jamais une commande remboursée ou annulée.
Failed: Flutterwave a signalé la dernière tentative de paiement d'une commande en attente comme échouée ou annulée. La note indique la raison.
Cancelled: le client a annulé sur la page Flutterwave après avoir passé commande au paiement, ou la commande a été annulée par vous ou à l'expiration du délai de réservation du stock de WooCommerce.
Si un second paiement est reçu pour une commande déjà payée, celle-ci n'est pas modifiée. Une note vous demande de rembourser le doublon dans le tableau de bord Flutterwave.
Remboursements
Ouvrez la commande, cliquez sur Refund, saisissez le montant et cliquez sur Refund via Flutterwave. Les remboursements totaux et partiels sont pris en charge. Le remboursement est envoyé avec la clé secrète du mode dans lequel le paiement a été effectué (test ou production) ; cette clé doit donc être définie. Si Flutterwave refuse le remboursement, WooCommerce affiche l'erreur et aucun remboursement n'est enregistré. Un remboursement réussi est ajouté aux notes de commande avec son identifiant et son statut (effectué, ou initié avec le statut signalé par Flutterwave).
Les remboursements effectués dans le tableau de bord Flutterwave ne sont pas synchronisés avec WooCommerce. Si nécessaire, créez un remboursement manuel dans WooCommerce sans Refund via Flutterwave.
Clé de licence
L'extension fonctionne avec une clé de licence VibeFox de vibefox.net. Le bloc de licence se trouve en haut de WooCommerce > Settings > Payments > Flutterwave. Collez la clé dans License key et cliquez sur Activate. Le bloc affiche le statut, par exemple la date de validité de la licence et votre domaine. Utilisez Check now pour vérifier à nouveau le statut, Change key pour saisir une autre clé et Remove key pour la retirer de ce site. Le lien Manage licenses and domains in your account ouvre votre compte vibefox.net.
Une clé fonctionne sur un domaine. Retirer la clé d'un site ne libère pas son emplacement de domaine. Libérez cet emplacement dans votre compte vibefox.net.
Sans clé active, Flutterwave n'est pas affiché aux clients au paiement. Si un paiement est malgré tout lancé, le client voit This payment method is not available. Please choose another one. Les gestionnaires de boutique connectés voient toujours la méthode de paiement, marquée (unlicensed — visible to admins only), pour vous permettre de configurer et tester l'extension avant d'acheter une clé. Un rappel apparaît sur la page des extensions et les pages WooCommerce. Les commandes existantes ne sont pas affectées : les paiements déjà lancés sont toujours confirmés et les remboursements fonctionnent.
À l'expiration d'une licence, l'extension continue de fonctionner, mais les mises à jour et l'assistance nécessitent un renouvellement. Le statut est vérifié à nouveau automatiquement en arrière-plan.
Dépannage
Flutterwave n'apparaît pas au paiement : vérifiez que la licence est active, que Enable/Disable est activé et que la clé secrète du mode actuel est renseignée et correspond à ce mode : une clé de test (FLWSECK_TEST-…) en mode test, une clé de production (FLWSECK-…) en mode production. Sinon, la page de réglages affiche un avertissement.
Le paiement a été effectué, mais la commande reste Pending payment : le webhook ne fonctionne pas. Dans le tableau de bord Flutterwave, vérifiez que son URL est exactement celle affichée dans les réglages, dans le mode utilisé (test ou production), et que son hachage secret est identique à Secret Hash dans l'extension. Les virements bancaires et paiements USSD ou mobile money en attente le restent jusqu'à confirmation de Flutterwave. Activez Debug log et consultez WooCommerce > Status > Logs, source wcp_flutterwave_payment.
Le webhook répond Invalid hash ou Secret hash not configured : le hachage secret du tableau de bord Flutterwave diffère de celui de l'extension, ou celle-ci n'en a pas. Saisissez la même valeur aux deux endroits.
Le webhook répond Verification failed ou Busy, retry later : Flutterwave n'a pas pu être joint pour vérifier le paiement, la transaction n'est pas encore visible ou une autre requête mettait à jour la commande. Flutterwave réessaie le webhook.
Le client voit Payment gateway is not properly configured : la clé secrète du mode actuel est absente ou appartient à l'autre mode.
Le client voit We could not match this payment to an order : le lien de retour contient une référence que cette boutique n'a pas créée. Si le client a été débité, recherchez le paiement dans le tableau de bord Flutterwave.
Flutterwave affiche une erreur sur sa page : votre compte Flutterwave ne prend peut-être pas en charge la devise de la commande ou les options de paiement choisies.
La commande est On hold après paiement : lisez la note de commande. Le montant ou la devise vérifiés ne correspondaient pas à la commande, ou le paiement est arrivé après son annulation. Exécutez la commande ou remboursez le paiement.
Le remboursement échoue avec un message concernant le mode : le paiement a été effectué en mode test ou production, et la clé secrète de ce mode n'est pas configurée. Saisissez-la et réessayez.
Le bloc de licence affiche une erreur : suivez le message du bloc. Par exemple, si la clé est déjà utilisée sur un autre domaine, libérez un emplacement dans votre compte vibefox.net et cliquez sur Check now. Si l'adresse du site a changé, cliquez sur Check now pour activer la clé sur le nouveau domaine. Si le serveur de licences est injoignable, l'extension continue de fonctionner avec le dernier statut connu.
Pour les développeurs, la documentation de l'extension répertorie les filtres flw_p_payment_request (données envoyées à Flutterwave), flw_p_currency_decimals (précision des devises) et flw_p_icon (icône au paiement).
Désinstallation
Lorsque vous désactivez l'extension, toutes les données sont conservées. Pour la supprimer, désactivez-la et supprimez-la sur la page Plugins. La clé et le statut de licence de cette extension sont toujours supprimés. Les réglages de la passerelle et les journaux sont supprimés uniquement si Delete data on uninstall était activé. Sinon, ils sont conservés pour une réinstallation ultérieure. Les données Flutterwave enregistrées dans les commandes sont toujours conservées. Les commandes existantes gardent leurs notes de paiement et identifiants de transaction.
Flutterwave est une marque de son propriétaire respectif. Cette extension n'est ni affiliée à Flutterwave ni approuvée par Flutterwave.