VibeFox Flow for PrestaShop — Aide
Prérequis
PrestaShop : 8.0 à 9.x.
PHP : 8.0 ou ultérieur. Le module refuse de s'installer sur les anciennes versions de PHP.
Devise : peso chilien (CLP) ou dollar américain (USD). Pour les paniers dans d'autres devises, le moyen de paiement est masqué à l'étape de commande. Pour le CLP, réglez la précision de la devise CLP sur 0 dans International > Localization > Currencies, car Flow facture des pesos entiers.
Compte Flow : vous avez besoin de l'API Key et de la Secret Key de votre compte Flow, dans Flow sous Mis datos, Datos técnicos. Pour les tests, créez un compte sandbox distinct sur sandbox.flow.cl et utilisez ses clés. Les clés sandbox et production sont différentes. Rien n'est à configurer dans le compte Flow.
Site public : les URL de confirmation, de retour et de remboursement de votre boutique doivent être accessibles depuis Internet, sans protection par mot de passe ni pare-feu bloquant Flow. Le mode maintenance de la boutique ne les bloque pas.
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 Flow Gateway 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 l'API Key et la Secret Key sandbox, activez Enable / Disable, cliquez sur Save et passez une commande test.
5. Pour accepter de vrais paiements, renseignez les clés de production et désactivez Sandbox mode.
À l'installation, le module crée deux statuts de commande, Awaiting Flow payment et Flow 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 Flow Gateway > Configure. Chaque section comportant des champs a son propre bouton Save, qui enregistre toute la page. Au-dessus des champs, la page vous avertit lorsque les clés du mode actuel sont vides (Flow est alors masqué à l'étape de commande), lorsque la devise par défaut de la boutique n'est ni CLP ni USD, et lorsque la devise CLP a des décimales (réglez sa précision sur 0 pour que les prix, les totaux et les remboursements correspondent exactement). En mode sandbox, elle affiche Sandbox mode — payments go to sandbox.flow.cl, no real money is charged.
Flow.cl
Enable / Disable : Enable Flow.cl payments active ou désactive le moyen de paiement. Par défaut : off.
Title : le nom du moyen de paiement affiché au client à l'étape de commande. Il est aussi le nom enregistré dans la commande. Par défaut : Flow. Obligatoire.
Description : le texte affiché sous le moyen de paiement à l'étape de commande. Par défaut : Pay with Webpay, credit or debit card, bank transfer and other methods. You will be redirected to Flow to complete the payment.
Identifiants API Flow
Copiez l'API Key et la Secret Key depuis votre compte Flow (Mis datos, Datos técnicos) : clés de production sur www.flow.cl, clés sandbox sur sandbox.flow.cl (un compte sandbox distinct).
Sandbox mode : utilise le sandbox Flow (sandbox.flow.cl) et les clés sandbox. Aucun paiement réel n'est débité en mode sandbox. Par défaut : on. Désactivez-le et renseignez les clés de production pour accepter de vrais paiements. Les remboursements utilisent toujours l'environnement dans lequel la commande a été payée.
Sandbox API Key : l'API Key de votre compte sandbox.flow.cl.
Sandbox Secret Key : la Secret Key de votre compte sandbox.flow.cl. Elle sert à signer chaque requête.
Live API Key : l'API Key de votre compte www.flow.cl.
Live Secret Key : la Secret Key de votre compte www.flow.cl. Gardez-la confidentielle.
Les clés enregistrées ne sont jamais réaffichées. Le champ reste vide et affiche Saved — leave empty to keep it. Saisissez une nouvelle valeur uniquement pour la modifier.
Clear saved keys : cochez une clé et cliquez sur Save pour la supprimer. Un champ vide conserve la valeur enregistrée.
Notifications
Le module envoie trois URL à Flow avec chaque paiement et remboursement ; rien n'est donc à configurer dans le compte Flow. Le champ Flow URLs de cette section les liste. Avec des URL conviviales, elles ressemblent à ceci :
La confirmation ne contient qu'un jeton de paiement. Le module recherche ce jeton parmi les paiements qu'il a créés, demande à Flow le statut du paiement par une requête signée dans l'environnement où le paiement a été créé, et n'applique que la réponse de Flow. Un paiement que cette boutique n'a pas créé est rejeté sans interroger Flow. Sans la confirmation, la commande est créée lorsque le client revient de Flow.
Avancé
Debug log : écrit les appels à l'API et les notifications dans logs/flw_p_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les clés et les données clients ne sont jamais journalisées. Les erreurs sont toujours journalisées, même lorsque l'option est désactivée. Par défaut : off.
Log : affiche la taille et les dernières entrées du journal. Cliquez sur Clear log pour le vider.
Delete data on uninstall : si activée, la désinstallation du module supprime ses réglages et son journal. Les données Flow enregistrées sur les commandes sont conservées. Par défaut : off.
Tunnel de commande
À l'étape de paiement, le client choisit le moyen de paiement (par défaut Flow) et voit la description. En mode sandbox, il affiche SANDBOX MODE — les paiements vont vers le sandbox Flow. Aucun débit réel. Après confirmation, le module crée un paiement Flow pour le total du panier dans la devise du panier, avec pour objet Cart # suivi du numéro de panier et du nom de la boutique, puis envoie le client sur la page de paiement Flow. L'adresse e-mail du client est transmise à Flow. Là, le client choisit un moyen de paiement activé dans votre compte Flow. Aucune commande n'existe encore à ce stade.
Après le paiement, le client revient dans votre boutique. La commande n'est marquée comme payée qu'après la confirmation de Flow : par la confirmation ou par une requête de statut signée lorsque le client revient. La commande est alors créée et le client voit la page standard de confirmation de commande avec Your payment with Flow has been received. Si le client a généré un bon Servipag ou Multicaja, la commande est créée en Awaiting Flow payment et la page affiche Your Flow payment coupon was generated. The order will be processed as soon as Flow confirms the payment. Si le paiement d'une commande avec bon échoue ou est annulé par la suite, la page affiche Your Flow payment was not completed. Please contact us about this order. Si le montant ne correspondait pas, la page affiche Your Flow payment was received and is being reviewed by the shop.
Si Flow est injoignable au retour du client, ou si une autre requête est en train de créer la commande à ce moment-là, une page Payment confirmation demande au client de ne pas payer à nouveau et propose Check again et Back to checkout.
Si le paiement a été refusé, le client revient au tunnel de commande avec Your Flow payment was rejected. Please try again or choose another payment method. Si le client a quitté la page Flow sans payer, le message est The Flow payment was not completed. You can try again or choose another payment method. Si le résultat n'a pas pu être vérifié, le message est We could not confirm your Flow payment yet. If you completed it, you will receive a confirmation e-mail shortly; otherwise please try again. Le panier est conservé, et chaque nouvelle tentative crée un nouveau paiement Flow lié au panier.
Si Flow ne peut pas démarrer le paiement, le client reste à l'étape de commande avec un court message, par exemple Could not connect to Flow. Please try again in a moment. Les détails figurent dans le journal.
Si un bon de réduction du panier cesse d'être valide entre le paiement et sa confirmation, PrestaShop le retire de la commande. La commande passe alors en Flow payment on hold avec une note, car le client a payé le prix avec la réduction.
Le module n'accepte que les paiements ponctuels. Il ne gère ni cartes enregistrées, ni abonnements, ni débits récurrents, ni liens de paiement, et ne présélectionne aucun moyen de paiement Flow. Flow ne peut pas annuler un lien de paiement déjà créé : si un client paie un ancien lien alors que le panier a déjà été payé, la commande reçoit une note vous demandant de rembourser le doublon dans Flow.
Commandes et remboursements
Statuts de commande
No order yet : le client a été envoyé vers Flow et n'a pas payé, ou Flow n'a pas encore confirmé le paiement. Seul le panier existe.
Payment accepted : Flow a signalé le paiement comme effectué, et le montant et la devise correspondent. Le paiement est enregistré avec le numéro de commande Flow comme ID de transaction, et une note indique le montant, le numéro de commande Flow et le moyen de paiement.
Awaiting Flow payment : le client a généré un bon de paiement Servipag ou Multicaja. La commande passe en Payment accepted lorsque Flow confirme le paiement.
Flow payment on hold : Flow a signalé un montant ou une devise différent du total de la commande (par exemple, le panier a été modifié après le début du paiement), un bon de réduction a été retiré, ou un paiement est arrivé pour une commande annulée. Le paiement encaissé par Flow est enregistré et la note l'explique. Vérifiez la commande, puis expédiez-la ou remboursez le paiement.
Payment error : Flow a refusé le paiement par bon d'une commande en attente.
Canceled : le paiement par bon d'une commande en attente a été annulé dans Flow.
Refunded : le paiement a été entièrement remboursé via le module.
Si un autre paiement arrive pour une commande déjà payée, la commande n'est pas modifiée. Une note vous demande de rembourser le doublon dans votre compte Flow. Une commande remboursée n'est jamais rouverte.
Bloc de paiement Flow
La page de commande affiche un bloc Flow payment avec le numéro de commande Flow et le moyen de paiement, la référence commerceOrder, le statut du paiement, le montant payé et remboursé, un badge Sandbox pour les paiements sandbox, l'historique des remboursements et les Flow notes de la commande.
Remboursements
Dans le bloc Flow payment, saisissez le montant (le montant non encore remboursé est prérempli), facultativement un motif, puis cliquez sur Refund via Flow. Confirmez la question Refund this amount via Flow? Flow e-mails the customer to complete the refund. Les remboursements totaux et partiels sont pris en charge. Vous devez disposer du droit de modifier les commandes. Les remboursements sont limités au montant que Flow a effectivement encaissé : après un écart de montant, vous pouvez donc rembourser jusqu'au montant payé par le client, et non le total de la commande. Les remboursements en CLP doivent être des montants entiers. Le remboursement est envoyé à l'environnement dans lequel le paiement a été effectué (sandbox ou production), donc les clés de cet environnement doivent être renseignées, et le client doit avoir une adresse e-mail valide. Si Flow refuse le remboursement, le bloc affiche l'erreur et aucun remboursement n'est enregistré. Une demande réussie est ajoutée à l'historique des remboursements et aux notes, avec le numéro et le statut du remboursement Flow. Un remboursement total place la commande en Refunded. Un remboursement partiel ne modifie pas le statut. Les remboursements sont disponibles une fois que Flow a confirmé le paiement.
Les changements de statut ultérieurs du remboursement signalés par Flow sont ajoutés aux notes. Si Flow rejette ou annule ensuite un remboursement, la note indique que l'argent n'a pas été restitué au client, et le montant peut être remboursé à nouveau. 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 Flow. Les remboursements créés dans le tableau de bord Flow ne sont pas importés dans PrestaShop.
Clé de licence
Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Flow Gateway est le premier bloc de Modules > Module Manager > VibeFox Flow Gateway > 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-flow 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, Flow n'est pas affiché aux clients à l'étape de commande. 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 commande. Un rappel apparaît dans Modules > Module Manager, sous l'onglet Alerts. Les commandes existantes ne sont pas affectées : les paiements déjà initié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
Flow n'apparaît pas à l'étape de commande : vérifiez que la licence est active, que Enable / Disable est activé, que les clés du mode actuel sont renseignées (clés sandbox en mode sandbox, clés de production en mode production) et que la devise du panier est CLP ou USD. 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 été effectué, mais aucune commande n'a été créée : la confirmation Flow n'atteint pas votre boutique et le client n'est pas revenu. Vérifiez que l'URL de confirmation indiquée dans Flow URLs s'ouvre depuis Internet et n'est pas bloquée par une protection par mot de passe ou un pare-feu. Activez Debug log et consultez le champ Log sur la page du module.
La confirmation répond Payment does not belong to the order : le jeton ne correspond pas à un paiement créé par cette boutique, ou Flow a signalé une autre référence pour celui-ci. Rien n'est modifié.
La confirmation répond Gateway not configured : les clés de l'environnement du paiement sont vides. Saisissez-les à nouveau. Flow renouvelle la confirmation.
La confirmation répond Flow API unavailable or Busy, retry : la requête de statut vers Flow a échoué, ou la commande était en cours de création par une autre requête au même moment. Flow renouvelle la confirmation.
Le client voit Flow payments are not available at the moment : les clés sont absentes ou Flow les a refusées. Vérifiez l'API Key et la Secret Key du mode actuel.
Le client voit A valid billing email is required for Flow payments : Flow a besoin de l'adresse e-mail du client.
Le client voit The order total is too small to be paid with Flow : le total du panier s'arrondit à zéro dans la devise du panier.
Le client a payé, mais la commande est en Awaiting Flow payment ou Flow payment on hold : lisez les notes du bloc Flow payment. Le client a généré un bon de paiement en espèces qui n'est pas encore payé, ou le montant ou la devise signalé par Flow ne correspond pas à la commande. Les totaux CLP avec décimales sont arrondis à des pesos entiers ; réglez donc la précision du CLP sur 0.
Le remboursement échoue avec un message concernant les clés sandbox ou de production : la commande a été payée dans cet environnement, et ses clés sont vides. Saisissez-les et réessayez.
Le remboursement échoue avec Flow accepts CLP refunds in whole units only : saisissez un montant entier.
Pour les développeurs, le README répertorie les hooks actionWcpFlowSupportedCurrencies (devises pour lesquelles le moyen de paiement est proposé) et actionWcpFlowPaymentSubject (l'objet du paiement envoyé à Flow).
Désinstallation
Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox Flow Gateway 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 du module et le journal sont supprimés. S'il est désactivé, tous les réglages sont conservés pour une réinstallation ultérieure. Les enregistrements de paiements et de remboursements Flow ainsi que les statuts de commande Awaiting Flow payment et Flow payment on hold sont toujours conservés, de sorte que les commandes payées auparavant peuvent encore être remboursées après une réinstallation. Les commandes existantes conservent leurs notes de paiement et leurs ID de transaction.
Flow est une marque déposée de son titulaire. Ce module n'est ni affilié à Flow ni approuvé par Flow.