VibeFox Vindi for WooCommerce — Aide

Prérequis

WordPress : 6.0 ou ultérieur.

WooCommerce : 8.0 ou ultérieur, installé et activé. L'extension refuse de s'activer sans lui.

PHP : 8.0 ou ultérieur.

Devise de la boutique : réal brésilien (BRL). Vindi n'encaisse qu'en BRL, donc le moyen de paiement est masqué pour toute autre devise.

Compte Vindi : vous avez besoin de la clé API de votre compte Vindi. Le sandbox Vindi est un compte de test distinct, avec sa propre clé. Boleto, PIX et 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 WordPress, allez dans Plugins > Add New > Upload Plugin, choisissez le fichier ZIP de l'extension, cliquez sur Install Now puis sur Activate. Vous pouvez aussi envoyer le dossier wcp_vindi_gateway dans /wp-content/plugins/ par FTP.

2. Ouvrez les réglages : WooCommerce > Settings > Payments > Vindi > Manage, ou cliquez sur Settings sous le nom de l'extension sur la page Plugins.

3. Saisissez votre clé de licence VibeFox dans le bloc de licence en haut de la page et cliquez sur Activate.

4. Collez la Sandbox API key et, quand 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 enregistrez. Testez un paiement en mode sandbox, puis décochez Sandbox mode pour accepter de vrais paiements.

Configuration

Tous les réglages se trouvent sur une seule page : WooCommerce > Settings > Payments > Vindi. 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'apparaît pas au paiement. Dans la liste des moyens de paiement, Vindi est signalé comme nécessitant une configuration tant que le mode actuel n'a pas de clé API. À l'enregistrement, les clés sont nettoyées ; 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.

Général

Enable / Disable : Enable Vindi payments active ou désactive le moyen de paiement. Par défaut : off.

Title : le nom du moyen de paiement affiché au paiement. Par défaut : Vindi.

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. Chaque commande 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 : Create new payments in the Vindi sandbox utilise sandbox-app.vindi.com.br avec la clé API du sandbox. Les clients voient une mention TEST MODE au paiement : Vindi sandbox: no real charges. Par défaut : on. Décochez-la 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.

Moyens de paiement

Offered methods : les moyens de paiement que le client peut choisir. Par défaut : credit card. Les moyens doivent aussi être activés dans votre compte Vindi.

Credit card : le client paie sur la page de facturation Vindi.

Boleto, PIX, BolePix (boleto + PIX) : la facture est émise immédiatement et la commande reste En attente. Ces moyens exigent le CPF ou le CNPJ du client, demandé au paiement.

Notifications de paiement (webhook)

Le webhook indique à votre boutique qu'une facture a été payée, annulée ou remboursée. Cette section des réglages affiche l'URL du webhook. Elle ressemble à https://your-site/wc-api/webhook_wc_vindi/?token=... et contient un jeton secret créé par l'extension. Copiez-la exactement telle que 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 :

bill_paid : une facture a été payée.

bill_canceled : une facture a été annulée.

charge_rejected : une tentative de paiement a été refusée.

charge_refunded : un paiement a été remboursé, par exemple depuis le tableau de bord Vindi.

Les requêtes dont le jeton est absent ou incorrect sont rejetées. Chaque notification fait seulement relire la facture via l'API Vindi avant que la commande ne change. Sans le webhook, les paiements par carte, boleto et PIX ne sont confirmés que lorsque le client ouvre la page de confirmation de commande.

Avancé

Debug log : Log API calls and notifications écrit les détails dans WooCommerce > Status > Logs, source wcp_vindi_gateway. Les erreurs et avertissements sont toujours journalisés, même si cette option est désactivée. Les clés et les données clients ne sont jamais journalisées. Par défaut : off.

Delete data on uninstall : Remove the settings, webhook token and logs when the plugin is deleted. Par défaut : off.

Paiement

Le client choisit le moyen de paiement (par défaut Vindi). Lorsque plusieurs moyens sont proposés, la zone de paiement affiche Pay with et un choix entre carte de crédit, boleto, PIX ou BolePix. Lorsque boleto, PIX ou BolePix est proposé, la zone affiche aussi un champ CPF or CNPJ. Il est obligatoire lorsque seuls ces moyens sont proposés ; sinon, il affiche Required for boleto and PIX. Le numéro est vérifié grâce à ses chiffres de contrôle. Sur le paiement classique, le champ n'apparaît pas lorsque Brazilian Market on WooCommerce est actif, car cette extension demande déjà le CPF / CNPJ. Son CPF / CNPJ, son numéro de rue et son quartier sont alors utilisés. Si une information 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 la commande est passée, l'extension crée pour cette commande un client Vindi à partir des coordonnées de facturation, ainsi qu'une facture Vindi pour le total de la commande, en une seule échéance.

Credit card : le client est envoyé sur la page de facturation Vindi et y paie. Vindi ne propose pas d'URL de retour pour les factures : le client n'est donc pas renvoyé automatiquement vers la boutique. La commande est confirmée par le webhook, ou lorsque le client ouvre la page de confirmation de commande. Tant que le paiement n'est pas terminé, cette page et la commande dans My account affichent Your payment has not been completed yet. et un bouton Pay at Vindi.

Boleto, PIX et BolePix : la facture est émise immédiatement, la commande passe En attente et le client arrive sur la page de confirmation de commande. Là, et dans My account > Orders, 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 commande en attente du client et l'e-mail de facture contiennent le code PIX et le lien du boleto.

La commande n'est marquée payée qu'après confirmation de Vindi : l'extension lit la facture via l'API Vindi et vérifie qu'elle appartient à la commande (code de commande et client Vindi) et que le montant payé correspond au total de la commande.

Un client peut payer à nouveau une commande non payée depuis la page Pay for order. Si le moyen de paiement, le montant et l'environnement sont identiques, la facture Vindi en attente est réutilisée. Sinon, elle est annulée chez Vindi avant la création d'une nouvelle facture, afin que le client ne puisse pas payer deux fois la même commande. Si la facture précédente a été payée entre-temps, la commande est marquée payée et aucune nouvelle facture n'est créée.

Si Vindi ne peut pas lancer le paiement, le client voit un court message, par exemple lui demandant de vérifier le CPF / CNPJ, l'adresse de facturation, l'e-mail ou le téléphone, ou indiquant que Vindi est momentanément indisponible. Si la même commande est en cours de traitement par une autre requête à ce moment-là, le client est invité à patienter un instant puis à réessayer.

Le moyen de paiement fonctionne sur le paiement classique, sur le bloc Paiement et sur la page Pay for order. Il est compatible avec le stockage haute performance des commandes de WooCommerce (HPOS).

L'extension ne prend que des paiements uniques en une seule échéance. Elle ne gère ni abonnements ni facturation récurrente, ni cartes enregistrées, ni paiement 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

Pending payment : un paiement par carte a été lancé et Vindi ne l'a pas encore confirmé.

On hold : un paiement par boleto, PIX ou BolePix est en attente (note Awaiting ... payment at Vindi.), ou la facture Vindi est en cours de vérification.

Processing or Completed : le paiement a été confirmé. Le statut est attribué de la manière standard de WooCommerce : En cours, ou Terminée pour les commandes ne contenant que des produits virtuels téléchargeables. La note de commande affiche la facture Vindi, le montant et l'environnement. L'ID de transaction est l'ID de la facture Vindi.

On hold after payment : la facture payée ne correspond pas à la commande (montant, code de commande ou client Vindi), ou la facture a été payée après l'annulation de la commande. La note de commande l'explique. Vérifiez la commande et le stock, puis terminez la commande ou remboursez le paiement.

Failed : Vindi a refusé la tentative de paiement. La note indique le motif donné par l'acquéreur, s'il existe. Le client peut toujours payer la même facture, et un paiement ultérieur termine la commande.

Cancelled : la facture a été annulée chez Vindi, ou la commande a été annulée par vous, par le client ou par le délai de réservation du stock de WooCommerce. Lorsqu'une commande est annulée dans la boutique, sa facture Vindi en attente est annulée aussi, de sorte qu'elle ne peut plus être payée. Si ce n'est pas possible, une note vous invite à annuler la facture dans le tableau de bord Vindi. Avant que le délai de réservation du stock n'annule une commande, la facture est vérifiée : si elle a été payée entre-temps, la commande est marquée payée à la place.

Si une seconde facture est payée pour une commande déjà payée, la commande n'est pas modifiée à nouveau. Une note vous invite à rembourser un paiement dans Vindi.

Remboursements

Ouvrez la commande, cliquez sur Refund, saisissez le montant et cliquez sur Refund via Vindi. Les remboursements totaux et partiels des paiements par carte et PIX sont pris en charge. Un remboursement total annule aussi la facture chez Vindi. 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 réussi est ajouté aux notes de commande avec la transaction Vindi et le statut. Si Vindi ou l'acquéreur refuse le remboursement, WooCommerce affiche l'erreur et aucun remboursement n'est enregistré.

Vindi ne peut pas rembourser les paiements par boleto. L'extension affiche Vindi cannot refund boleto payments. Return the money to the customer by bank transfer and record the refund manually.

Les remboursements effectués dans le tableau de bord Vindi arrivent par le webhook charge_refunded et sont ajoutés aux notes de commande. Ils ne sont pas enregistrés automatiquement comme remboursements WooCommerce. Si nécessaire, créez un remboursement manuel dans WooCommerce sans utiliser Refund via Vindi.

Clé de licence

L'extension fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence se trouve en haut de WooCommerce > Settings > Payments > Vindi. Collez la clé dans License key et cliquez sur Activate. Le bloc affiche le statut, par exemple la date jusqu'à laquelle la licence est active, ainsi que votre domaine. Utilisez Check now pour revérifier 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 seul domaine. Retirer la clé d'un site ne libère pas son emplacement de domaine. Libérez-le dans votre compte vibefox.net.

Sans clé active, Vindi n'est pas affiché 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. Les gestionnaires connectés de la boutique voient toujours le moyen de paiement, marqué (unlicensed — visible to admins only), afin que vous puissiez configurer et tester l'extension avant d'acheter une clé. Un rappel apparaît sur la page Plugins et sur les pages WooCommerce. Les commandes existantes ne sont pas touchées : les paiements déjà lancés sont toujours confirmés, et les remboursements fonctionnent.

Lorsqu'une licence expire, 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

Vindi n'apparaît pas au paiement : vérifiez que la licence est active, que Enable / Disable est activé, que la devise de la boutique 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.

Le paiement a abouti, mais la commande reste Pending payment ou On hold : le webhook ne fonctionne pas. Dans Vindi, vérifiez que le webhook existe dans le compte utilisé (production ou sandbox), que son URL correspond exactement à celle affichée dans les réglages, jeton compris, et que les quatre événements sont sélectionnés. La commande est aussi confirmée lorsque le client ouvre la page de confirmation de commande.

Le webhook répond Forbidden : le jeton dans l'URL est absent ou incorrect. Copiez de nouveau l'URL depuis les réglages.

Le webhook répond Verification failed, retry later ou Order busy, retry later : la facture n'a pas pu être lue via l'API Vindi (par exemple parce que la clé API de cet environnement a été supprimée), ou la commande était mise à jour par une autre requête au même moment. Vindi renvoie la notification.

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 passation de commande : ouvrez les notes de commande ou le journal dans WooCommerce > Status > Logs, source wcp_vindi_gateway. Les erreurs sont journalisé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 On hold après paiement : lisez la note de commande. Le montant payé, le code de commande ou le client Vindi ne correspondait pas à la commande, ou le paiement est arrivé après l'annulation de la commande. Terminez la commande ou remboursez le paiement.

Anciennes commandes sandbox après le passage en production : chaque commande 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.

Le bloc de licence affiche une erreur : suivez le message affiché dans le 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.

Désinstallation

Désactiver l'extension conserve toutes les données. Pour la supprimer, désactivez-la puis supprimez-la sur la page Plugins. La clé de licence et le statut de licence de cette extension sont toujours supprimés. Les réglages de la passerelle, le jeton du webhook, les autres données stockées par l'extension et les journaux ne sont supprimés que si Delete data on uninstall était activé. Sinon, ils sont conservés pour une réinstallation ultérieure. Les commandes existantes conservent leurs notes de paiement, leurs ID de transaction et leurs données Vindi.

Vindi est une marque de son propriétaire respectif. Cette extension n'est ni affiliée à Vindi ni approuvée par Vindi.