VibeFox Barion 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 de PHP plus anciennes.
Boutique Barion : vous avez besoin de la POSKey (clé secrète) de votre boutique et de l'adresse e-mail du portefeuille Barion qui reçoit les paiements. Les deux se trouvent dans le portail Barion : secure.barion.com pour la production, secure.test.barion.com pour le test, sous My stores et votre boutique. Les identifiants de test et de production sont différents.
Devise : la devise du panier doit être HUF, EUR, USD ou CZK. Pour les autres devises, le mode de paiement est masqué à l'étape de paiement.
Boutique accessible : Barion appelle votre boutique après chaque paiement ; le site doit donc être accessible depuis Internet, sans pare-feu ni authentification de base devant lui.
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 Barion Gateway dans la liste des modules et cliquez sur Configure.
3. Saisissez votre clé de licence VibeFox dans License key, dans le bloc de licence en haut de la page Configure, puis cliquez sur Activate (voir Clé de licence).
4. Saisissez la POSKey de test et l'e-mail du portefeuille de test, laissez Test Mode activé, activez Enable/Disable et cliquez sur Save. Passez une commande de test.
5. Quand tout fonctionne, saisissez les identifiants de production et désactivez Test Mode.
L'URL de callback est envoyée automatiquement à Barion à chaque paiement. Rien n'est à configurer dans le portail Barion.
À l'installation, le module crée deux statuts de commande : Awaiting Barion payment et Barion 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 Barion Gateway > Configure. Chaque section a son propre bouton Save, qui enregistre la page entière. Au-dessus des champs, la page vous avertit lorsque le mode actuel n'a pas de POSKey ou pas d'e-mail de bénéficiaire (le mode de paiement est alors masqué à l'étape de paiement) et lorsque la devise par défaut de votre boutique n'est pas prise en charge par Barion, avec la liste des devises acceptées. Tant que le mode test est activé, elle affiche Le mode test est activé : les paiements sont envoyés au bac à sable Barion (api.test.barion.com), aucun argent réel n'est débité.
Barion
Enable/Disable : Enable Barion Payment active ou désactive le mode de paiement. Par défaut : désactivé.
Title : le nom du mode de paiement que voient les clients à l'étape de paiement. C'est aussi le nom du mode de paiement enregistré dans la commande. Par défaut : Barion. Obligatoire.
Description : le texte affiché sous le mode de paiement à l'étape de paiement. Par défaut : Pay securely with Barion — card, Barion Wallet, Apple Pay or Google Pay.
Identifiants de la boutique Barion
Récupérez votre POSKey et l'e-mail de votre portefeuille dans le portail Barion : secure.barion.com (production) ou secure.test.barion.com (test), My stores, votre boutique. Le mode test n'utilise que les identifiants de test, le mode production uniquement les identifiants de production.
Test Mode : utilise les identifiants de test indiqués ci-dessous et le bac à sable Barion (api.test.barion.com). Aucun argent réel n'est débité. Par défaut : activé. Désactivez-le pour recevoir de vrais paiements. Tant qu'il est activé, les clients voient Mode test : aucun paiement réel n'est encaissé. sous le mode de paiement.
Test POSKey : la clé secrète (POSKey) de votre boutique dans le système de test de Barion (secure.test.barion.com, My stores).
Test Payee Email : l'adresse e-mail de votre portefeuille de test Barion qui reçoit les paiements de test.
Live POSKey : la clé secrète (POSKey) de votre boutique dans le système de production de Barion (secure.barion.com, My stores).
Live Payee Email : l'adresse e-mail de votre portefeuille Barion qui reçoit les paiements.
Les POSKey enregistrées ne sont jamais réaffichées. Le champ reste vide et affiche Enregistrée — laissez vide pour la conserver. Saisissez une nouvelle valeur uniquement si vous voulez la changer.
Clear saved POSKeys : cochez une clé et cliquez sur Save pour la supprimer. Un champ vide conserve la valeur enregistrée.
Callback URL : l'adresse que Barion appelle après chaque paiement, par exemple https://your-shop/module/wcp_barion_gateway/callback avec des URL conviviales, éventuellement précédée d'un code de langue comme /en/. Elle est envoyée à Barion avec chaque paiement, il n'y a donc rien à configurer. Elle doit seulement être accessible depuis Internet.
Commandes
Order Status After Payment : le statut de commande attribué après un paiement réussi et vérifié.
Les paiements encore en cours chez Barion attendent en Awaiting Barion payment. Les écarts de montant ou de devise vont toujours en Barion payment on hold.
Avancé
Logging : écrit les requêtes et les callbacks Barion dans logs/barion_p_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les clés secrètes et les e-mails des portefeuilles ne sont pas journalisés. Par défaut : désactivé. Tant qu'il est désactivé, rien n'est écrit, erreurs comprises.
Log : affiche la taille et les dernières entrées du journal. Cliquez sur Clear log pour le vider.
Delete Data on Uninstall : lorsqu'il est activé, la désinstallation du module supprime ses réglages et le journal. Les commandes, leurs données de paiement Barion et les statuts de commande sont toujours conservés. Par défaut : désactivé.
Paiement
À l'étape de paiement, le client choisit le mode de paiement (par défaut Barion) et voit la mention Vous serez redirigé vers la page de paiement sécurisée Barion. Après confirmation, le module lance un paiement Barion pour le total du panier, dans la devise du panier, et envoie le client sur la page de paiement Barion. Les produits, la livraison, l'emballage cadeau et les taxes figurent sur le paiement, celui-ci apparaît comme Cart avec le numéro du panier, l'e-mail du client est transmis à titre indicatif, et la langue de la page suit celle du panier lorsque Barion la prend en charge. Aucune commande n'existe encore à ce stade.
Après le paiement, le client revient dans votre boutique, et Barion appelle aussi l'URL de callback. Aucune de ces deux requêtes ne marque quoi que ce soit comme payé à elle seule : le module demande à Barion l'état du paiement avec la POSKey du mode dans lequel il a été lancé. La commande n'est marquée comme payée qu'après confirmation de Barion, et seulement si le montant et la devise correspondent au panier. Le lien de retour contient la clé sécurisée du panier, et seuls les paiements lancés pour ce panier sont vérifiés.
Si le paiement a réussi, la commande est créée et le client voit la page standard de confirmation de commande avec Votre paiement avec Barion a bien été reçu. Si le paiement est encore en cours chez Barion, la commande est créée en Awaiting Barion payment et la page affiche Votre paiement est en cours de confirmation par Barion. Vous recevrez un e-mail dès qu'il sera confirmé. Si ce paiement est ensuite annulé, expire ou échoue chez Barion, la page affiche Votre paiement Barion n'a pas abouti. Veuillez nous contacter au sujet de cette commande. Si Barion est injoignable au retour du client, une page Confirmation du paiement affiche le même texte « en cours de confirmation » et un bouton Check again ; le callback crée la commande dès que Barion confirme le paiement.
Si le paiement n'a pas abouti (annulé, expiré ou échoué), aucune commande n'est créée, le panier est conservé et le client revient à l'étape de paiement avec Le paiement n'a pas abouti. Veuillez réessayer. Le client peut réessayer. Chaque tentative est mémorisée : un paiement tardif d'une tentative antérieure crée tout de même la commande, et une tentative antérieure qui expire n'annule pas la commande d'une tentative plus récente.
Si le paiement ne peut pas être lancé, le client reste à l'étape de paiement avec un court message : Le paiement Barion n'a pas pu être lancé. Veuillez réessayer ou choisir un autre mode de paiement., Barion ne prend pas en charge les paiements en devise du panier, ou Barion ne peut pas traiter une commande d'un total nul. Les détails sont écrits dans le journal lorsque Logging est activé.
Le callback fonctionne pendant que la boutique est en mode maintenance et n'est pas bloqué par la restriction géographique de votre boutique.
Le module ne prend en charge que les paiements immédiats. Il ne prend pas en charge les paiements avec réservation ou capture différée, les abonnements ou paiements récurrents, les cartes enregistrées, Barion Pixel ni les données 3-D Secure supplémentaires ; Barion gère le 3-D Secure sur sa page de paiement.
Commandes et remboursements
Statuts de commande
No order yet : le client a été redirigé vers Barion et n'a pas payé, ou Barion n'a pas encore confirmé le paiement. Seul le panier existe.
Awaiting Barion payment : Barion indique que le paiement est toujours en cours. Une note affiche le PaymentId Barion, le montant et, en mode test, (test mode). La commande passe à « Paiement accepté » lorsque Barion confirme le paiement.
Payment accepted or Delivered : Barion a confirmé le paiement. Le statut suit Order Status After Payment. Le paiement est enregistré avec l'identifiant de transaction Barion, et une note affiche le montant, le PaymentId et la transaction.
Barion payment on hold : Barion a indiqué un montant ou une devise différent du total de la commande, par exemple parce que le panier a été modifié après le lancement du paiement. La note affiche les deux montants. Vérifiez le paiement dans le portail Barion, puis traitez la commande ou remboursez le paiement dans le portail Barion.
Canceled : la dernière tentative de paiement d'une commande en attente a été annulée ou a expiré chez Barion.
Payment error : la dernière tentative de paiement d'une commande en attente a échoué.
Refunded : le paiement a été entièrement remboursé par le module.
Si un paiement de la commande réussit encore après l'annulation ou l'échec de la commande, la commande passe à payée. Une commande payée ou remboursée n'est jamais modifiée par un callback ultérieur. Si un autre paiement réussit pour une commande payée, une note vous demande de le vérifier dans le portail Barion et de le rembourser s'il s'agit d'un doublon. Les notes sont des messages privés sur la page de la commande.
Bloc de paiement Barion
La page de la commande affiche un bloc Barion payment avec le PaymentId, la transaction Barion, le statut du paiement, le montant payé et remboursé, un badge Test mode pour les paiements de test et l'historique des remboursements.
Remboursements
Dans le bloc Barion payment, saisissez le montant (le montant non encore remboursé est pré-rempli), éventuellement un motif, puis cliquez sur Refund via Barion. Confirmez la question Rembourser ce montant via Barion ? Cette action est irréversible. Les remboursements totaux et partiels sont pris en charge. Vous devez disposer du droit de modifier les commandes. Le motif est envoyé à Barion sous forme de commentaire. Les remboursements en HUF doivent être des montants entiers. Le remboursement est envoyé dans le mode (test ou production) dans lequel le paiement a été effectué, la POSKey de ce mode doit donc être renseignée. Si Barion n'accepte ou ne confirme pas 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 la transaction et le statut Barion. Un remboursement total passe la commande en Refunded. Un remboursement partiel ne modifie pas le statut.
Les remboursements sont disponibles une fois que Barion a confirmé le paiement et que la commande est payée par ce biais. Un paiement avec un écart de montant ou de devise ne peut pas être remboursé depuis PrestaShop ; remboursez-le dans le portail Barion. Le module ne crée pas d'avoirs, et les boutons de remboursement standard de PrestaShop sur la page de commande ne renvoient pas d'argent via Barion.
Clé de licence
Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Barion Gateway est le premier bloc de Modules > Module Manager > VibeFox Barion 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-barion 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 : celui 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 l'emplacement dans votre compte vibefox.net.
Sans clé active, Barion n'est pas proposé 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 boutique PrestaShop ne sait pas que vous êtes connecté au back-office ; le mode de paiement est donc masqué pour vous aussi : vous pouvez configurer le module avant d'acheter une clé, mais 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é à nouveau 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 licence.
Dépannage
Barion n'apparaît pas à l'étape de paiement : vérifiez que la licence est active, que Enable/Disable est activé, que le mode actuel dispose d'une POSKey et d'un e-mail de bénéficiaire (la page des réglages affiche un avertissement si l'un manque) et que la devise du panier est HUF, EUR, USD ou CZK. 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 : la commande est créée lorsque Barion appelle l'URL de callback ou lorsque le client revient dans votre boutique. Assurez-vous que le site est accessible depuis Internet (pas de pare-feu ni d'authentification de base devant l'URL de callback). Vérifiez que la POSKey du mode dans lequel le paiement a été effectué est correcte, car le module l'utilise pour demander l'état du paiement à Barion. Activez Logging pour voir le callback.
Le callback répond Busy, retry : la commande était en cours de traitement par le retour du client au même moment, ou la commande n'a pas pu être créée (par exemple, parce que le module est désactivé). Barion rappelle. Activez Logging pour voir la raison.
Le callback répond API error : la boutique n'a pas pu lire l'état du paiement chez Barion, ou la POSKey du mode dans lequel le paiement a été effectué n'est pas renseignée. Vérifiez cette POSKey.
Le callback répond Order not found : le PaymentId n'a pas été lancé par cette boutique. Les appels de Barion destinés à d'autres boutiques ou à des systèmes de test sont ignorés.
Le client voit Payment verification failed : le lien de retour ne correspond pas au panier, par exemple parce qu'il a été ouvert dans une autre session de navigateur ou modifié. L'état du paiement est tout de même confirmé par le callback.
Le client voit une erreur lors du choix de Barion : activez Logging et consultez le champ Log de la page du module. Une POSKey ou un e-mail de bénéficiaire incorrect provoque Le paiement Barion n'a pas pu être lancé.
La commande est en Barion payment on hold : lisez la note d'écart sur la commande, vérifiez le paiement dans le portail Barion, puis traitez la commande ou remboursez-la dans le portail Barion.
Pourquoi ne puis-je pas rembourser 10,50 HUF ? : Barion traite le HUF sans décimales. Saisissez un montant entier.
Le remboursement indique que la POSKey Barion du mode de cette commande n'est pas configurée : le paiement a été effectué en mode test ou production, et la POSKey de ce mode est vide. Renseignez-la et réessayez.
Désinstallation
Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox Barion 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 données de paiement Barion des commandes et les statuts de commande Awaiting Barion payment et Barion payment on hold sont toujours conservés, afin que les commandes payées auparavant puissent encore être remboursées après une réinstallation. Les commandes existantes conservent leurs notes de paiement et leurs identifiants de transaction.
Barion est une marque déposée de son titulaire respectif. Ce module n'est ni affilié à Barion ni approuvé par Barion.