VibeFox Braintree for WooCommerce — Aide
Prérequis
WordPress: 6.0 ou ultérieur.
WooCommerce: 8.0 ou ultérieur, installé et activé.
PHP: 8.0 ou ultérieur.
HTTPS: votre site doit utiliser HTTPS.
Compte Braintree : vous avez besoin du Merchant ID, de la clé publique (Public Key) et de la clé privée (Private Key) de votre compte Braintree. Elles se trouvent dans le Braintree Control Panel (sandbox : sandbox.braintreegateway.com, production : www.braintreegateway.com), sous l'icône en forme d'engrenage, API, API Keys. Les comptes sandbox et de production ont des clés différentes. 3-D Secure doit être activé pour votre compte marchand Braintree, sauf si vous réglez 3-D Secure sur Disabled. Aucun webhook n'est nécessaire.
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 et cliquez sur Install Now. Vous pouvez aussi téléverser le dossier wcp_braintree_gateway dans /wp-content/plugins/ par FTP.
2. Cliquez sur Activate.
3. Ouvrez les réglages : WooCommerce > Settings > Payments > Braintree > Manage, ou cliquez sur Settings sous le nom de l'extension sur la page Extensions.
4. Saisissez votre clé de licence VibeFox dans le bloc de licence en haut de la page et cliquez sur Activate.
5. Copiez le Merchant ID, la clé publique et la clé privée depuis le Braintree Control Panel dans les champs sandbox ou production.
6. Activez Enable/Disable. Laissez Sandbox mode activé et passez une commande de test avec une carte de test Braintree, par exemple 4111 1111 1111 1111 avec une date d'expiration future quelconque. Pour 3-D Secure, utilisez les cartes de test 3-D Secure de Braintree.
7. Décochez Sandbox mode pour recevoir de vrais paiements avec les identifiants de production.
Configuration
Tous les réglages se trouvent sur une seule page : WooCommerce > Settings > Payments > Braintree. Lorsque le moyen de paiement est activé mais que le Merchant ID, la clé publique ou la clé privée du mode sélectionné manque, la page vous avertit que le moyen de paiement est masqué au paiement tant qu'ils ne sont pas renseignés. La page n'affiche que les champs d'identifiants du mode sélectionné ; les deux jeux restent enregistrés.
Général
Enable/Disable: Enable Braintree card payments active ou désactive le moyen de paiement. Par défaut : désactivé.
Title: le nom du moyen de paiement que voit le client au paiement. Par défaut : Credit / debit card.
Description: le texte affiché au-dessus du formulaire de carte au paiement. Par défaut : Pay securely with your credit or debit card via Braintree.
Identifiants API
Connectez-vous au Braintree Control Panel (sandbox ou production), cliquez sur l'icône en forme d'engrenage, puis sur API et API Keys. Les clés publique et privée y figurent, et le Merchant ID est affiché sur la même page.
Sandbox mode: Use the Braintree sandbox (test payments, no real money). Par défaut : activé. Décochez-le pour recevoir de vrais paiements avec les identifiants de production. Les remboursements, captures et annulations utilisent toujours l'environnement dans lequel la commande a été payée.
Sandbox Merchant ID et Live Merchant ID: le Merchant ID du compte sandbox ou de production.
Sandbox Public Key et Live Public Key: la clé publique de ce compte.
Sandbox Private Key et Live Private Key: la clé privée de ce compte.
Sandbox merchant account ID(s) et Live merchant account ID(s): facultatifs. Braintree débite dans la devise du compte marchand. Laissez vide pour utiliser votre compte marchand par défaut, saisissez un identifiant (par exemple mystore_EUR) ou un identifiant par devise : EUR=mystore_EUR, USD=mystore_USD. Si la devise débitée ne correspond pas à la devise de la commande, la transaction est annulée automatiquement et le client n'est pas débité.
Paiement
Transaction type: la manière dont la carte est débitée.
3-D Secure: 3-D Secure 2 (authentification forte du client, SCA) est obligatoire pour la plupart des paiements par carte dans l'EEE et au Royaume-Uni. Il doit aussi être activé pour votre compte Braintree.
Avancé
Debug log: Also log API calls and payment steps (errors are always logged). Les journaux se trouvent dans WooCommerce > Status > Logs, source wcp_braintree_gateway. Ils ne contiennent jamais de clés API, de données de carte ni de données clients. Par défaut : désactivé.
Delete data on uninstall: Remove the gateway settings and logs when the plugin is deleted. Par défaut : désactivé.
Paiement
Le client choisit le moyen de paiement (par défaut Credit / debit card) et saisit sa carte dans le formulaire Braintree de la page de paiement. En mode sandbox, le formulaire affiche SANDBOX / TEST MODE — no real money is charged. Lorsque 3-D Secure est activé, le client effectue la vérification de sa banque lors de la validation de la commande.
L'extension débite le jeton à usage unique via l'API Braintree pour le total de la commande dans la devise de la commande, avec le numéro de commande comme identifiant de commande. La commande n'est marquée payée qu'à partir de la réponse authentifiée de Braintree, après contrôle du montant et de la devise débités par rapport à la commande. Si le paiement est approuvé, le client arrive sur la page de confirmation de commande. Les paiements par carte n'ont pas besoin de webhook : le résultat est connu immédiatement.
Si le paiement échoue, la commande reste « En attente de paiement », la raison est ajoutée aux notes de commande, et le client voit un message clair, par exemple Your card was declined. Please use another card or contact your bank., 3-D Secure authentication failed. Please try again or use another card. ou The card security code or billing address could not be verified. Please check your details and try again. Le client peut réessayer immédiatement. Si la devise débitée ne correspond pas à la commande, la transaction est annulée et le client voit This payment could not be processed in the currency of your order. Your card has not been charged. Please choose another payment method or contact us.
Une commande n'est jamais débitée deux fois : une seconde soumission pendant que le paiement est en cours affiche This order is already being paid. Please wait a moment and check your e-mail before trying again.
Le moyen de paiement fonctionne avec le paiement classique, avec le bloc Paiement et sur la page Pay for order. Il est compatible avec WooCommerce High-Performance Order Storage (HPOS).
L'extension ne prend que les paiements par carte. Elle ne gère ni cartes enregistrées (coffre-fort de cartes ou vaulting), ni abonnements WooCommerce ni précommandes, ni PayPal, Venmo, Apple Pay, Google Pay, ACH ou moyens de paiement locaux, ni webhooks Braintree, ni données de niveau 2 ou 3, ni lignes d'articles, ni Fastlane.
Commandes et remboursements
Statuts de commande
Pending payment: le paiement n'a pas encore été effectué ou a été refusé.
Processing or Completed: la carte a été débitée (Sale), ou une autorisation a été capturée. WooCommerce passe la commande à « En cours », ou à « Terminée » pour les commandes ne contenant que des produits virtuels téléchargeables. La note de commande indique le montant, l'identifiant de transaction et le résultat 3-D Secure. L'identifiant de transaction est celui de Braintree ; sur l'écran de commande, il renvoie vers la transaction dans le Braintree Control Panel.
On hold: les fonds sont seulement autorisés (Authorize only). Une commande passe aussi en attente lorsque Braintree renvoie un statut de transaction inattendu, ou lorsqu'un débit dans une devise incorrecte n'a pas pu être annulé automatiquement. La note de commande indique ce qu'il faut vérifier dans le Braintree Control Panel.
Cancelled: une autorisation a été annulée avec Void Braintree authorization.
Capture et annulation
Pour une commande avec une autorisation, ouvrez la commande et choisissez Capture Braintree payment ou Void Braintree authorization dans les actions de commande, puis cliquez sur le bouton de mise à jour. La capture marque la commande comme payée ; l'annulation (void) annule la commande et libère le montant bloqué sur la carte du client. Si l'action échoue, l'erreur s'affiche sur l'écran de commande et est ajoutée aux notes de commande.
Remboursements
Ouvrez la commande, cliquez sur Refund, saisissez le montant et cliquez sur Refund via Credit / debit card (le bouton reprend le titre de votre moyen de paiement). Les remboursements totaux et partiels sont pris en charge. Braintree ne peut rembourser que les transactions réglées, généralement réglées sous 24 heures. Avant le règlement, un remboursement total est effectué sous forme d'annulation (void) ; un remboursement partiel échoue alors avec un message vous demandant d'attendre le règlement. Le remboursement est envoyé à l'environnement (sandbox ou production) dans lequel la commande a été payée. Si Braintree n'accepte pas le remboursement, WooCommerce affiche l'erreur et aucun remboursement n'est enregistré. Un remboursement ou une annulation réussi est ajouté aux notes de commande.
Les litiges (chargebacks) et les refus de règlement ne sont pas synchronisés avec WooCommerce. Vérifiez-les dans le Braintree Control Panel.
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 > Braintree. 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 et votre domaine. Utilisez Check now pour vérifier à nouveau 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, Braintree 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 Extensions et sur les pages WooCommerce. Les commandes existantes ne sont pas affectées : les captures, annulations et 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
Braintree n'apparaît pas au paiement : vérifiez que la licence est active, que Enable/Disable est activé et que le mode sélectionné dispose d'un Merchant ID, d'une clé publique et d'une clé privée. La page des réglages affiche un avertissement lorsqu'une clé manque.
Le paiement a été effectué, mais la commande reste « En attente de paiement » : les paiements par carte sont confirmés immédiatement, sans webhook. Si la note de commande indique que la réponse de Braintree a été perdue, vérifiez dans le Braintree Control Panel s'il existe une transaction portant ce numéro de commande avant d'accepter un autre paiement. Activez Debug log et consultez WooCommerce > Status > Logs, source wcp_braintree_gateway.
Le formulaire de carte affiche « Could not initialize payment form » : les clés du mode sélectionné sont incorrectes, ou l'identifiant du compte marchand n'existe pas dans ce compte. Vérifiez les clés et les identifiants de compte marchand, puis rechargez la page.
3-D Secure échoue pour tous les paiements : 3-D Secure doit être activé pour votre compte marchand Braintree. Contactez le support Braintree, ou réglez 3-D Secure sur Disabled (déconseillé dans l'EEE et au Royaume-Uni, où l'authentification forte SCA est obligatoire).
Le client est informé que le paiement ne peut pas être traité dans la devise de la commande : Braintree a débité dans la devise du compte marchand. Saisissez l'identifiant de compte marchand de la devise de la commande dans le champ du compte marchand du mode en cours.
Un remboursement partiel échoue juste après le paiement : Braintree ne peut rembourser que les transactions réglées, généralement sous 24 heures. Remboursez le montant total pour annuler la transaction immédiatement, ou effectuez le remboursement partiel après le règlement.
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é pour le nouveau domaine. Si le serveur de licences est injoignable, l'extension continue de fonctionner avec le dernier statut connu.
Désinstallation
La désactivation de 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 et les journaux ne sont supprimés que si Delete data on uninstall était activé. Sinon, ils sont conservés pour une future réinstallation. Les données Braintree enregistrées sur les commandes sont toujours conservées, car elles sont nécessaires aux remboursements après une réinstallation. Les commandes existantes conservent leurs notes de paiement et leurs identifiants de transaction.
Braintree est une marque de son propriétaire respectif. Cette extension n'est ni affiliée à Braintree ni approuvée par Braintree.