VibeFox Vindi 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.
Devise de la boutique : réal brésilien (BRL). Vindi n'encaisse qu'en BRL ; le moyen de paiement est donc masqué pour les paniers dans toute autre devise.
Compte Vindi : vous avez besoin de la clé API de votre compte Vindi. Le sandbox Vindi est un compte de test Vindi distinct, avec sa propre clé. Le boleto, le PIX et le BolePix doivent aussi être activés dans votre compte Vindi si vous voulez les proposer.
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échargement terminé, cliquez sur Configure, ou retrouvez plus tard VibeFox Vindi Gateway dans la liste des modules et cliquez sur Configure.
3. Saisissez votre clé de licence VibeFox dans le champ License key du bloc de licence en haut de la page Configure, puis cliquez sur Activate (voir Clé de licence).
4. Collez la Sandbox API key et, lorsque vous êtes prêt, la Live API key. Choisissez les Offered methods.
5. Copiez l'URL du webhook depuis les réglages dans Vindi (voir Configuration).
6. Activez Enable / Disable et cliquez sur Save. Testez un paiement en mode sandbox, puis désactivez Sandbox mode pour accepter de vrais paiements.
À l'installation, le module crée deux statuts de commande : Awaiting Vindi payment et Vindi 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 ; le module doit y être autorisé pour BRL.
Configuration
Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox Vindi Gateway > Configure. Chaque section a son propre bouton Save, qui enregistre toute la page. Au-dessus des champs, la page vous avertit lorsque la devise de la boutique n'est pas BRL ou lorsque la clé API du mode actuel est vide. Dans les deux cas, le moyen de paiement n'est pas affiché au paiement. À l'enregistrement, les clés sont nettoyées (les espaces superflus sont supprimés). Si aucun moyen de paiement n'est sélectionné, la carte de crédit est sélectionnée et la page affiche Choose at least one payment method — credit card was selected. Un Title vide n'est pas enregistré : la page affiche Enter a title for the payment method.
Vindi
Enable / Disable : Enable Vindi payments active ou désactive le moyen de paiement. Par défaut : désactivé.
Title : le nom du moyen de paiement affiché au paiement. C'est aussi le nom du moyen de paiement enregistré dans la commande. Par défaut : Vindi. Obligatoire.
Description : le texte affiché sous le moyen de paiement au paiement. Par défaut : Pay by credit card on the secure Vindi page, or by boleto / PIX.
Clés API
Créez les clés dans le tableau de bord Vindi, sous Settings > API keys : sur app.vindi.com.br pour la production et sur sandbox-app.vindi.com.br pour le sandbox. La production et le sandbox ont des hôtes et des clés distincts. Chaque paiement mémorise l'endroit où sa facture a été créée, de sorte que les vérifications, annulations et remboursements utilisent toujours cet environnement.
Sandbox mode : crée de nouveaux paiements dans le sandbox Vindi, via sandbox-app.vindi.com.br avec la clé API sandbox. Les clients voient une mention TEST MODE au paiement : Vindi sandbox: no real charges. Par défaut : activé. Désactivez-le pour accepter de vrais paiements.
Live API key : la clé privée du compte Vindi de production. Elle n'est envoyée qu'à l'API Vindi.
Sandbox API key : la clé privée du compte sandbox Vindi.
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.
Moyens de paiement
Offered methods : les moyens que les clients peuvent choisir. Par défaut : carte de crédit. Les moyens doivent aussi être activés dans votre compte Vindi.
Le boleto, le PIX et le BolePix exigent le CPF ou le CNPJ du client, demandé au paiement.
Notifications de paiement (webhook)
Le webhook informe votre boutique qu'une facture a été payée, annulée, rejetée ou remboursée. Le champ Webhook URL de cette section affiche l'URL. Avec des URL conviviales, elle ressemble à https://your-shop/module/wcp_vindi_gateway/webhook?token=... et contient un jeton secret créé par le module. Copiez-la exactement comme les réglages l'affichent. Dans Vindi, allez dans Settings > Webhooks, dans le compte de production comme dans le compte sandbox, ajoutez cette URL et sélectionnez ces événements :
Vindi ne signe pas ses notifications : les requêtes avec un jeton absent ou incorrect sont donc rejetées, et chaque notification oblige seulement le module à relire la facture via l'API Vindi avant qu'une commande ne change. Sans le webhook, un paiement par carte n'est pris en compte que lorsque le client repasse commande avec le même panier (la facture payée est alors retrouvée et la commande créée), et un paiement par boleto ou PIX lorsque le client rouvre la page de confirmation de commande.
Avancé
Debug log : enregistre les appels API et les notifications dans logs/wc_vdi_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les erreurs et avertissements sont toujours enregistrés, même lorsque l'option est désactivée. Les clés, le jeton du webhook 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 : lorsqu'elle est activée, la désinstallation du module supprime les réglages, le jeton du webhook et les journaux. Les commandes et les références de factures Vindi des commandes sont conservées. Par défaut : désactivé.
Paiement
Le client choisit le moyen de paiement (par défaut Vindi). Lorsque plusieurs moyens sont proposés, le bloc de paiement affiche Pay with et un choix entre carte de crédit, boleto, PIX ou BolePix. Lorsque le boleto, le PIX ou le BolePix est proposé, le bloc comporte aussi un champ CPF or CNPJ. Il est obligatoire lorsque la carte de crédit n'est pas proposée ; sinon il affiche Required for boleto and PIX. Le champ est rempli à partir du Identification number ou du numéro de TVA de l'adresse de facturation lorsqu'ils contiennent un CPF ou un CNPJ valide. Le numéro est vérifié grâce à ses chiffres de contrôle. Si un élément manque, le client voit Please choose how you want to pay with Vindi., Please enter a valid CPF or CNPJ. ou Please enter your CPF or CNPJ — it is required for boleto and PIX.
Lorsque le client confirme la commande, le module crée pour ce panier un client Vindi à partir de l'adresse de facturation, puis une facture Vindi pour le total du panier, en une seule échéance. Dans Vindi, la facture s'intitule Order # suivi du numéro du panier.
Carte de crédit : le client est redirigé vers la page de facturation Vindi et y paie. Aucune commande n'existe encore à ce stade. Vindi ne prévoit pas d'URL de retour pour les factures : le client n'est donc pas renvoyé automatiquement vers la boutique. La commande est créée lorsque Vindi confirme le paiement par le webhook. Si le client repasse commande avec le même panier, la facture en attente lui est à nouveau proposée ou, si elle est déjà payée, la commande est créée immédiatement.
Boleto, PIX et BolePix : la facture est émise immédiatement, la commande est créée avec le statut Awaiting Vindi payment et le client arrive sur la page de confirmation de commande. Là, et dans le détail de la commande de son compte client, une section Payment affiche le QR code PIX, le code PIX à copier-coller avec un bouton Copy code et sa date d'expiration, ainsi qu'un bouton Open boleto. L'e-mail de confirmation de commande contient le code PIX et le lien du boleto. Si Vindi ne renvoie pas les données du boleto ou du PIX, la facture est annulée et le client voit une erreur.
La commande n'est marquée payée qu'après confirmation de Vindi : le module relit la facture depuis l'API Vindi et vérifie la devise, que la facture appartient au panier (code du panier et client Vindi) et que le montant payé est égal au total de la commande. La page de confirmation de commande revérifie via l'API une commande en attente, au plus toutes les 15 secondes. Lorsque le paiement a été reçu, elle affiche Your payment with Vindi has been received. Pendant que la facture est en cours d'examen chez Vindi, elle affiche We are confirming your payment with Vindi. The order will be updated automatically — please do not pay again. Pour une commande annulée, elle affiche This order was cancelled and its Vindi bill can no longer be paid. Please contact us if you have already paid.
Une nouvelle tentative de paiement pour le même panier réutilise la facture Vindi en attente si le moyen, le montant et l'environnement sont identiques. Sinon, la facture précédente est annulée chez Vindi avant qu'une nouvelle ne soit créée, afin que le client ne puisse pas payer deux fois le même panier. Si la facture précédente a été payée entre-temps, la commande est créée et aucune nouvelle facture n'est émise.
Si Vindi ne peut pas démarrer le paiement, le client reste au paiement avec un bref message, par exemple pour vérifier le CPF / CNPJ, l'adresse de facturation (la rue, le code postal, la ville et l'état sont obligatoires pour le boleto), l'e-mail ou le numéro de téléphone, ou pour indiquer que Vindi est temporairement indisponible. La raison technique est écrite dans le journal.
Le webhook 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 que des paiements uniques en une seule échéance. Il ne gère ni abonnements ni facturation récurrente, ni cartes enregistrées, ni paiements en plusieurs fois, ni formulaire de carte sur votre site : la carte est toujours saisie sur la page Vindi.
Commandes et remboursements
Statuts de commande
No order yet : un paiement par carte a été lancé et Vindi ne l'a pas encore confirmé. Seul le panier existe.
Awaiting Vindi payment : un paiement par boleto, PIX ou BolePix est en attente (note Awaiting ... payment at Vindi.). La commande passe en Payment accepted lorsque Vindi signale la facture payée.
Payment accepted : le paiement a été confirmé. Il est enregistré avec l'ID de la facture Vindi comme ID de transaction, et une note affiche la facture Vindi, le montant et l'environnement.
Vindi payment on hold : la facture Vindi est en cours d'examen, la facture payée ne correspond pas à la commande (devise, montant, code du panier ou client Vindi), ou la facture a été payée après l'annulation de la commande. La note l'explique, et un montant payé est enregistré sur la commande. Vérifiez la commande et le stock, puis finalisez la commande ou remboursez le paiement.
Payment error : Vindi a rejeté la tentative de paiement d'une commande en attente. La note affiche le motif communiqué par l'acquéreur, s'il y en a un. Le client peut toujours payer la même facture, et un paiement ultérieur fait passer la commande en Payment accepted.
Canceled : la facture d'une commande en attente a été annulée chez Vindi. Lorsque vous annulez une commande dans la boutique, sa facture Vindi en attente est aussi annulée et ne peut donc plus être payée. Si cela n'est pas possible, une note vous demande d'annuler la facture dans le tableau de bord Vindi.
Refunded : le paiement a été entièrement remboursé via le module.
Si une deuxième facture est payée pour une commande déjà payée, la commande n'est pas modifiée. Une note vous demande de rembourser un paiement dans Vindi.
Bloc de paiement Vindi
La page de commande affiche un bloc Vindi payment avec la facture et le débit Vindi, l'environnement (avec un badge Sandbox pour les paiements sandbox), le moyen de paiement, le statut, le montant payé et remboursé, l'historique des remboursements, toutes les Bills of this cart et les Vindi notes de la commande.
Remboursements
Dans le bloc Vindi payment, saisissez le montant (le montant non encore remboursé est prérempli), facultativement un motif, puis cliquez sur Refund via Vindi. Confirmez la question Refund this amount through Vindi? This cannot be undone. Les remboursements totaux et partiels des paiements par carte et PIX sont pris en charge. Vous avez besoin du droit de modifier les commandes ; l'accès aux pages des modules n'est pas nécessaire. Les remboursements sont limités au montant réellement encaissé par Vindi : après un écart, vous pouvez donc rembourser jusqu'à ce que le client a payé, et non le total de la commande. Le remboursement est envoyé dans l'environnement du paiement (production ou sandbox), la clé API de cet environnement doit donc être renseignée. Un remboursement total annule aussi la facture chez Vindi et place la commande en Refunded ; un remboursement partiel ne modifie pas le statut. Un remboursement réussi est ajouté à l'historique des remboursements et aux notes, avec le débit Vindi et le statut. Si Vindi ou l'acquéreur refuse le remboursement, le bloc affiche l'erreur et aucun remboursement n'est enregistré. Les remboursements sont disponibles une fois que Vindi a signalé la facture payée.
Vindi ne peut pas rembourser les paiements par boleto. Le bloc affiche Vindi cannot refund boleto payments. Return the money to the customer by bank transfer and record the refund manually.
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 Vindi. Les remboursements effectués dans le tableau de bord Vindi arrivent par le webhook charge_refunded et sont ajoutés aux notes. Le statut de la commande n'est pas modifié automatiquement ; enregistrez-les dans PrestaShop avec un remboursement manuel 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 Vindi Gateway est le premier bloc de la page Modules > Module Manager > VibeFox Vindi Gateway > Configure, au-dessus des réglages. Saisissez la clé dans License key puis 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-vindi 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-le dans votre compte vibefox.net.
Sans clé active, Vindi n'est pas proposé aux clients au 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 moyen de paiement est donc masqué pour vous aussi. Vous pouvez configurer le module avant d'acheter une clé, mais pas le tester au paiement. Un rappel apparaît dans Modules > Module Manager, sous l'onglet Alerts. Les commandes existantes ne sont pas affectées : les factures déjà créées sont toujours confirmées par le webhook Vindi, et les remboursements fonctionnent.
Lorsqu'une licence expire, le module continue de fonctionner, mais les mises à jour et le support 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 licence.
Dépannage
Vindi n'apparaît pas au paiement : vérifiez que la licence est active, que Enable / Disable est activé, que la devise du panier est BRL, qu'au moins un moyen est sélectionné dans Offered methods et que le mode actuel dispose d'une clé API : Sandbox API key en mode sandbox, Live API key en mode production. La page des réglages affiche un avertissement lorsque la clé est absente ou que la devise n'est pas BRL. Dans Payment > Preferences, vérifiez que le module est autorisé pour BRL, pour le pays du client et pour son groupe de clients.
Le paiement a été effectué, mais aucune commande n'a été créée ou la commande reste en Awaiting Vindi payment : le webhook ne fonctionne pas. Dans Vindi, vérifiez que le webhook existe dans le compte utilisé (production ou sandbox), que son URL est exactement celle affichée dans les réglages, jeton compris, et que les quatre événements sont sélectionnés.
Le webhook répond Forbidden : le jeton de l'URL est absent ou incorrect. Recopiez l'URL depuis les réglages.
Le webhook répond Verification failed, retry later : la facture n'a pas pu être lue depuis l'API Vindi (par exemple la clé API de cet environnement a été supprimée), le panier était en cours de mise à jour par une autre requête au même moment, ou la commande n'a pas pu être créée (par exemple, le module est désactivé). Vindi renvoie la notification. Le journal indique la raison.
L'URL du webhook affiche Method not allowed dans le navigateur : c'est normal. L'URL n'accepte que les requêtes provenant de Vindi.
Le client voit This payment method is temporarily unavailable : Vindi a rejeté la clé API. Vérifiez la clé du mode actuel.
Le client voit une erreur lors de la validation de la commande : consultez le champ Log sur la page du module. Les erreurs sont enregistrées même lorsque Debug log est désactivé. Pour le boleto, l'adresse de facturation doit comporter la rue, le code postal, la ville et l'état.
La commande est Vindi payment on hold : lisez les notes du bloc Vindi payment (voir Statuts de commande), puis finalisez la commande ou remboursez le paiement.
Anciennes commandes sandbox après le passage en production : chaque paiement conserve l'environnement de sa facture. Les vérifications, annulations et remboursements des commandes sandbox continuent d'utiliser la clé sandbox tant qu'elle reste dans les réglages.
Le remboursement échoue : lisez le message. Les paiements par boleto ne peuvent pas être remboursés via Vindi, et la clé API de l'environnement du paiement doit être renseignée.
Désinstallation
Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox Vindi 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, le jeton du webhook et les journaux sont supprimés. Sinon, tous les réglages sont conservés pour une réinstallation ultérieure. Les factures et remboursements Vindi des commandes ainsi que les statuts de commande Awaiting Vindi payment et Vindi 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.
Vindi est une marque déposée de son propriétaire respectif. Ce module n'est ni affilié à Vindi ni approuvé par Vindi.