VibeFox Flutterwave for PrestaShop — Aide

Prérequis

PrestaShop : 8.0 à 9.x.

PHP : 8.0 ou ultérieur. Le module refuse de s'installer sur les versions antérieures de PHP.

Compte Flutterwave : vous avez besoin des clés secrètes de votre compte Flutterwave, 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. Vous configurez aussi un webhook avec un hachage secret de votre choix (voir Configuration).

Devises : le panier est toujours débité dans la devise du panier. Le module ne restreint pas lui-même les pays ni les devises ; Flutterwave affiche une erreur si votre compte ne prend pas en charge la devise. Vous pouvez limiter les devises, les pays et les groupes de clients dans Payment > Preferences.

Clé de licence VibeFox : achetée sur vibefox.net. Une clé fonctionne sur un seul domaine.

Installation

1. Dans le back office, allez dans Modules > Module Manager et cliquez sur Upload a module. Choisissez le fichier ZIP du module.

2. Une fois le téléversement terminé, cliquez sur Configure, ou retrouvez plus tard VibeFox Flutterwave Payment dans la liste des modules et cliquez sur Configure.

3. Saisissez votre clé de licence VibeFox dans License key du bloc de licence en haut de la page Configure, puis cliquez sur Activate (voir Clé de licence).

4. Saisissez vos clés secrètes, configurez le webhook dans le tableau de bord Flutterwave et saisissez le même hachage secret dans le module (voir Configuration).

5. Activez Enable/Disable et cliquez sur Save. Testez un paiement en mode test, puis activez Live mode.

À l'installation, le module crée deux statuts de commande, Awaiting Flutterwave payment et Flutterwave payment on hold. PrestaShop propose un nouveau module de paiement pour toutes les devises, tous les pays et tous les groupes de clients. Vous pouvez les limiter dans Payment > Preferences.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox Flutterwave Payment > Configure. Chaque section a son propre bouton Save, qui enregistre la page entière. Au-dessus des champs, la page affiche Live mode: real payments are accepted. ou Test mode: no real money is charged. Elle vous avertit lorsque la clé secrète du mode actuel est vide, lorsque le champ de la clé live contient une clé de test (FLWSECK_TEST-…) en mode live, ou lorsque le champ de la clé de test contient une clé live (FLWSECK-…) en mode test ; le moyen de paiement est alors masqué à l'étape de paiement tant que le problème n'est pas corrigé. Elle vous avertit aussi lorsqu'aucun hachage secret de webhook n'est défini : les webhooks sont alors rejetés et les paiements ne sont confirmés que lorsque le client revient sur votre boutique. Le titre de la première section indique le mode actuel, TEST ou LIVE.

Flutterwave

Enable/Disable : Enable Flutterwave Payment active ou désactive le moyen de paiement. Par défaut : désactivé.

Title : le titre du moyen de paiement que les clients voient à l'étape de paiement. C'est aussi le nom du moyen de paiement enregistré dans la commande. Par défaut : Flutterwave. Obligatoire.

Description : le texte que les clients voient sous le moyen de paiement à l'étape de paiement. Par défaut : Pay securely via Card, Bank Transfer, USSD, Mobile Money via Flutterwave.

Clés API

Copiez les clés secrètes depuis le tableau de bord Flutterwave, sous Settings, API keys (la section contient un lien). Le mode test et le mode production ont des clés différentes.

Live mode : accepte les paiements réels. Désactivez-le pour le mode test. 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 live. Par défaut : désactivé (mode test). Tant que le mode test est activé, les clients voient TEST MODE - no real payments will be processed. sous le moyen de paiement.

Test Secret Key : votre clé secrète de test Flutterwave (FLWSECK_TEST-...).

Live Secret Key : votre clé secrète live Flutterwave (FLWSECK-...).

Les clés enregistrées et le hachage secret ne sont plus jamais affichés. Le champ reste vide et affiche Saved — leave empty to keep it. Saisissez une nouvelle valeur uniquement pour la modifier.

Webhook

Le webhook confirme les paiements même lorsque le client ne revient pas sur votre boutique. Dans le tableau de bord Flutterwave, sous Settings, Webhooks, saisissez l'URL affichée sous Webhook URL dans cette section ainsi qu'un hachage secret de votre choix, en mode test comme en mode production. Avec des URL conviviales, l'URL ressemble à https://your-shop/module/wcp_flutterwave_payment/webhook, éventuellement avec un code de langue comme /en/. Copiez l'URL exactement telle qu'elle est affichée dans les réglages. Le module 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 paramètres de webhook de votre tableau de bord Flutterwave. Flutterwave l'envoie avec chaque webhook, et la même valeur est utilisée pour le mode test et le mode production. Les webhooks sans hachage secret valide sont rejetés. Sans webhook, un paiement n'est confirmé que lorsque le client revient sur votre boutique.

Clear saved secrets : cochez Test Secret Key, Live Secret Key ou Secret Hash et cliquez sur Save pour la supprimer. Un champ vide conserve la valeur enregistrée.

Paiement

Payment Options : moyens de paiement séparés par des virgules à afficher sur la page de Flutterwave, par exemple card, banktransfer, ussd, mobilemoney. Laissez vide pour afficher tous les moyens activés sur votre compte. La liste est nettoyée à l'enregistrement (minuscules, sans doublons).

Autocomplete Orders : les commandes payées reçoivent le statut Delivered au lieu de Payment accepted, avec un seul changement de statut. Par défaut : désactivé.

Avancé

Debug log : enregistre les événements de l'API Flutterwave à des fins de débogage dans logs/flwv_debug.log.php, dans le dossier du module. Ce fichier ne peut pas être ouvert depuis le web. Les erreurs et avertissements sont toujours journalisés. Les clés, le hachage secret et les données clients ne sont jamais journalisés. Par défaut : désactivé.

Log : affiche la taille et les dernières entrées du journal. Cliquez sur Clear log pour le vider.

Delete data on uninstall : supprime les réglages et les journaux du module lors de sa désinstallation. Les données de paiement enregistrées sur les commandes sont toujours conservées. Par défaut : désactivé.

Paiement

À l'étape de paiement, le client choisit le moyen de paiement (par défaut Flutterwave) et valide. Une adresse e-mail valide est obligatoire. Le module crée un paiement Flutterwave pour le total du panier dans la devise du panier, avec l'adresse e-mail du client, le téléphone et le nom de l'adresse de facturation, le nom et le logo de votre boutique, puis envoie le client sur la page de paiement de Flutterwave. Là, le client paie avec l'un des moyens activés sur votre compte (ou listés dans Payment Options). Aucune commande n'existe encore à ce stade.

Après le paiement, le client revient sur 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 lorsque le client revient. La commande est alors créée et le client voit la page de confirmation de commande standard. Si le paiement est encore en attente, par exemple un virement bancaire, un paiement USSD ou mobile money, la commande est créée en Awaiting Flutterwave payment et la page affiche Your payment is being confirmed by Flutterwave. You will receive an e-mail as soon as it is confirmed. Si la commande a été mise en attente de vérification, par exemple parce que le montant payé ne correspond pas au panier, la page affiche Your payment was received and your order is being reviewed. We will contact you if anything is needed. Si un paiement en attente échoue plus tard et que le client rouvre la page de confirmation, elle affiche Your Flutterwave payment was not completed. Please contact us about this order.

Si Flutterwave est injoignable lorsque le client revient, une page Payment confirmation indique Your payment is being confirmed by Flutterwave. Your order will be created as soon as it is confirmed — please do not pay again. avec les boutons Check again et Back to checkout. Le webhook crée la commande dès son arrivée.

Si le paiement est refusé, le client revient à l'étape de paiement avec le message Your payment was declined. You can try again or choose another payment method. Si le client annule sur la page de Flutterwave, le message est Payment was cancelled. You can try again or choose another payment method. Si le paiement n'a pas été finalisé, le message est The payment was not completed. You can try again or choose another payment method. Le panier est conservé et le client peut payer à nouveau. Chaque tentative a sa propre référence, et un ancien lien de paiement réglé plus tard reste accepté.

Si Flutterwave ne peut pas démarrer le paiement, le client reste à l'étape de paiement avec un bref message, par exemple Flutterwave is temporarily unavailable. Please try again in a moment or choose another payment method. La raison technique est écrite dans le journal.

Si le panier change entre le paiement et sa confirmation, par exemple dans un autre onglet du navigateur, les montants ne correspondent plus et la commande passe en Flutterwave payment on hold avec une note.

Le webhook fonctionne lorsque la boutique est en mode maintenance et n'est pas bloqué par la restriction de pays de votre boutique.

Le module n'accepte que les paiements ponctuels. Il 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 d'un panier peut donc encore être payé.

Commandes et remboursements

Statuts de commande

Pas encore de commande : le client a été envoyé à Flutterwave et n'a pas encore payé, ou Flutterwave n'a pas encore confirmé le paiement. Seul le panier existe.

Payment accepted or Delivered : le paiement a été confirmé. Delivered est utilisé lorsque Autocomplete Orders est activé. Le paiement est enregistré avec la référence Flutterwave (flw_ref) comme ID de transaction, et une note indique le montant, le moyen de paiement, la référence, la transaction et le mode.

Awaiting Flutterwave payment : le client est revenu alors que le paiement était encore en attente chez Flutterwave. La commande passe au statut payé lorsque Flutterwave confirme le paiement.

Flutterwave payment on hold : le montant ou la devise vérifié ne correspondait pas au panier, ou le paiement est arrivé après l'annulation de la commande. Le paiement est enregistré avec le montant réellement payé (et non avec le montant débité par Flutterwave dans une autre devise). La note l'explique. Traitez la commande ou remboursez le paiement. Une commande remboursée ou annulée n'est jamais rouverte par un webhook répété.

Payment error : Flutterwave a signalé que la dernière tentative de paiement d'une commande en attente a échoué ou a été annulée. La note indique la raison.

Canceled : défini par vous. Si Flutterwave signale ensuite un paiement pour une commande annulée, la commande passe en Flutterwave payment on hold (voir ci-dessus).

Refunded : le paiement a été intégralement remboursé via le module.

Si un second paiement est reçu pour une commande déjà payée, la commande n'est pas modifiée. Une note vous demande de rembourser le doublon dans le tableau de bord Flutterwave.

Bloc de paiement Flutterwave

La page de commande affiche un bloc Flutterwave payment avec la référence (tx_ref), l'ID de transaction et la référence Flutterwave, le mode, le statut et le moyen de paiement, le montant payé et remboursé, un badge Test mode pour les paiements de test, l'historique des remboursements et les Flutterwave notes de la commande.

Remboursements

Dans le bloc Flutterwave payment, saisissez le montant (le montant non encore remboursé est pré-rempli), éventuellement un motif, puis cliquez sur Refund via Flutterwave. Confirmez la question Refund this amount through Flutterwave? This cannot be undone. Les remboursements totaux et partiels sont pris en charge. Vous devez avoir le droit de modifier les commandes ; l'accès aux pages Modules n'est pas nécessaire. Les remboursements sont effectués au montant et dans la devise débités par Flutterwave ; après un écart de montant ou de devise, vous pouvez donc rembourser jusqu'à ce que le client ait réellement payé, et non le total de la commande. 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 renseignée. Si Flutterwave refuse le remboursement, le bloc affiche l'erreur et aucun remboursement n'est enregistré. Un remboursement réussi est ajouté à l'historique des remboursements et aux notes, avec l'ID du remboursement et son statut (completed, ou initiated avec le statut indiqué par Flutterwave). Un remboursement total place la commande en Refunded. Un remboursement partiel ne modifie pas le statut. Les remboursements ne sont disponibles qu'une fois le paiement confirmé par Flutterwave.

Le module ne crée pas d'avoirs. Les boutons de remboursement standard de PrestaShop sur la page de commande ne renvoient pas d'argent via Flutterwave.

Les remboursements effectués dans le tableau de bord Flutterwave ne sont pas synchronisés avec PrestaShop. Mettez à jour le statut de la commande manuellement si nécessaire.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Flutterwave Payment est le premier bloc de Modules > Module Manager > VibeFox Flutterwave Payment > Configure, au-dessus des réglages. Saisissez la clé dans License key et cliquez sur Activate. Ensuite, le bloc affiche la clé masquée, le statut (par exemple la date jusqu'à laquelle la licence est active et votre domaine) ainsi que les boutons Check now pour vérifier à nouveau le statut, Change key pour saisir une autre clé et Remove key pour retirer la clé de cette boutique. En dessous figurent la ligne Product: presta-payment-flutterwave et le lien Manage licenses and domains in your account, qui ouvre votre compte vibefox.net. Seuls les employés disposant de l'autorisation Configure pour le module peuvent modifier la clé. Les textes du bloc suivent la langue du back office (l'anglais et le russe sont inclus).

Si la clé n'est pas acceptée, le bloc indique la raison, par exemple Key not found, This key belongs to another product, Domain limit reached ou License expired on suivi d'une date. Après un changement d'adresse de la boutique, ou après avoir libéré un emplacement de domaine dans votre compte, cliquez sur Check now. Si le serveur de licences est injoignable, le module continue de fonctionner avec le dernier statut connu.

Une clé fonctionne sur un seul domaine : le domaine de la boutique principale, y compris dans une configuration multiboutique. Retirer la clé de la boutique ne libère pas son emplacement de domaine. Libérez-le dans votre compte vibefox.net.

Sans clé active, Flutterwave n'est pas affiché aux clients à l'étape de paiement. Si un paiement est tout de même lancé, le client voit This payment method is not available. Please choose another one. La vitrine PrestaShop ne sait pas que vous êtes connecté au back office, donc le moyen de paiement est aussi masqué pour vous : vous pouvez configurer le module avant d'acheter une clé, mais ne pas le tester à l'étape de paiement. Un rappel apparaît dans Modules > Module Manager, sous l'onglet Alerts. Les commandes existantes ne sont pas affectées : les paiements déjà lancés sont toujours confirmés, et les remboursements fonctionnent.

Lorsqu'une licence expire, le module continue de fonctionner, mais les mises à jour et l'assistance nécessitent un renouvellement. Le statut est vérifié automatiquement pendant votre travail dans le back office : une fois par jour pendant les 14 premiers jours après la saisie de la clé, puis une fois par semaine. Aucune tâche cron n'est nécessaire. La désinstallation ou la réinitialisation du module supprime toujours la clé de licence et le statut de la licence.

Dépannage

Flutterwave n'apparaît pas à l'étape de 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 au mode : une clé de test (FLWSECK_TEST-…) en mode test, une clé live (FLWSECK-…) en mode production. La page des réglages affiche un avertissement dans le cas contraire. Dans Payment > Preferences, vérifiez que le module est autorisé pour la devise du panier, le pays du client et le groupe du client.

Le paiement a abouti, mais aucune commande n'a été créée : le webhook ne fonctionne pas. Dans le tableau de bord Flutterwave, vérifiez que l'URL du webhook est exactement celle affichée sous Webhook URL, dans le mode que vous utilisez (test ou production), et que son hachage secret est identique à Secret Hash dans le module. Les virements bancaires, paiements USSD et mobile money en attente restent en attente tant que Flutterwave ne les a pas confirmés. La commande est aussi créée lorsque le client revient sur la boutique après avoir payé. Activez Debug log et consultez le champ Log sur la page du module.

Le webhook répond Invalid hash ou Secret hash not configured : le hachage secret du tableau de bord Flutterwave diffère de celui du module, ou le module n'en a pas. Saisissez la même valeur aux deux endroits.

Le webhook répond Verification failed, Busy, retry later ou Order could not be created, retry later : Flutterwave n'a pas pu être contacté pour vérifier le paiement, la transaction n'est pas encore visible, le panier était en cours de traitement par une autre requête, ou la commande n'a pas pu être créée (par exemple parce que le module est désactivé). Flutterwave renouvelle le webhook. Le journal indique la raison.

L'URL du webhook affiche Empty body dans le navigateur : c'est normal. L'URL n'accepte que les webhooks de Flutterwave.

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 qui n'appartient pas au panier du client. Si le client a été débité, retrouvez le paiement dans le tableau de bord Flutterwave.

Flutterwave affiche une erreur sur sa page, ou le client voit Flutterwave could not start the payment : votre compte Flutterwave ne prend peut-être pas en charge la devise du panier ou les options de paiement sélectionnées.

La commande est en Flutterwave payment on hold après le paiement : lisez les notes du bloc Flutterwave payment (voir Statuts de commande), puis traitez 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 remboursement répond Another operation on this payment is running : un autre remboursement de la même commande était en cours d'envoi à ce moment-là. Patientez un instant, vérifiez l'historique des remboursements et réessayez si nécessaire.

Pour les développeurs, le README du module répertorie les hooks actionWcpFlutterwavePaymentRequest (données envoyées à Flutterwave) et actionWcpFlutterwaveCurrencyDecimals (précision de la devise).

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox Flutterwave Payment et choisissez Uninstall. La clé de licence et le statut de licence de ce module sont toujours supprimés. Si Delete data on uninstall est activé, les réglages et le journal du module sont supprimés. S'il est désactivé, tous les réglages sont conservés pour une réinstallation ultérieure. Les données de paiement Flutterwave et les remboursements des commandes, ainsi que les statuts de commande Awaiting Flutterwave payment et Flutterwave payment on hold, sont toujours conservés : les commandes payées auparavant peuvent donc être remboursées après une réinstallation. Les commandes existantes conservent leurs notes de paiement et leurs ID de transaction.

Flutterwave est une marque déposée de son propriétaire. Ce module n'est ni affilié à Flutterwave ni approuvé par Flutterwave.