VibeFox Braintree 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.

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. Ils 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 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 : les paiements par carte sont confirmés immédiatement.

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 Braintree 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. Copiez le Merchant ID, la clé publique et la clé privée depuis le Braintree Control Panel dans les champs sandbox ou production.

5. Activez Enable/Disable et cliquez sur Save. Gardez Sandbox mode activé et passez une commande de test avec une carte de test Braintree sandbox. Désactivez ensuite Sandbox mode pour accepter de vrais paiements avec les identifiants de production.

À l'installation, le module crée deux statuts de commande : Braintree payment authorized et Braintree 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 Braintree Gateway > Configure. Chaque section a son propre bouton Save, qui enregistre toute la page. Lorsque le mode de paiement est activé mais que le Merchant ID, la clé publique ou la clé privée de l'environnement sélectionné est manquant, la page vous avertit que le mode de paiement est masqué sur la page de paiement tant qu'ils ne sont pas renseignés. Tant que le mode sandbox est activé, la page affiche Sandbox mode is on: test payments, no real money.

Braintree

Enable/Disable: Enable Braintree card payments active ou désactive le mode de paiement. Par défaut : off.

Title: le nom du mode de paiement que le client voit sur la page de paiement. C'est aussi le nom enregistré dans la commande. Par défaut : Credit / debit card. Obligatoire.

Description: le texte affiché sous le mode de paiement sur la page de 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 sont listées, et le Merchant ID est affiché sur la même page. La page n'affiche que les champs d'identifiants de l'environnement sélectionné ; les deux jeux restent enregistrés.

Sandbox mode: utilise le sandbox Braintree (paiements de test, sans argent réel). Par défaut : on. Désactivez-le pour accepter 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. Lorsqu'il est activé, les clients voient SANDBOX / TEST MODE — no real money is charged. sous le mode de paiement.

Sandbox Merchant ID et Live Merchant ID: le Merchant ID du compte sandbox ou 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. Les clés privées enregistrées ne sont jamais réaffichées. Le champ reste vide et affiche Saved — leave empty to keep it. Ne saisissez une nouvelle valeur que si vous voulez la modifier.

Sandbox merchant account ID(s) et Live merchant account ID(s): facultatif. 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 automatiquement annulée et le client n'est pas débité.

Clear saved private keys: cochez Sandbox Private Key ou Live Private Key puis cliquez sur Save pour la supprimer. Un champ vide conserve la valeur enregistrée.

Paiement

Transaction type: la manière dont la carte est débitée.

3-D Secure: le 3-D Secure 2 (Strong Customer Authentication) 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 (contactez le support Braintree si les paiements échouent avec une erreur de configuration 3-D Secure).

Le résultat 3-D Secure est vérifié côté serveur, et pas seulement dans le navigateur, avant le débit de la carte.

Avancé

Debug log: enregistre aussi les appels API et les étapes de paiement dans logs/wc_btg_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les erreurs sont toujours enregistrées, même si l'option est désactivée. Le journal ne contient jamais de clés API, de données de carte ou de données client. 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: lorsqu'elle est activée, la désinstallation du module supprime les réglages de la passerelle et le journal. Les transactions, remboursements et statuts de commande Braintree sont toujours conservés, de sorte que les commandes payées auparavant peuvent encore être remboursées, capturées ou annulées après une réinstallation. Par défaut : off.

Paiement

À l'étape de paiement, le client choisit le mode de paiement (par défaut Credit / debit card) et saisit sa carte dans le formulaire Braintree affiché dans l'option de paiement. Le formulaire n'est chargé depuis Braintree que sur la page de paiement et utilise la langue de la boutique. Avec 3-D Secure activé, le client effectue la vérification de sa banque lors de la validation de la commande ; le total du panier, l'adresse e-mail et l'adresse de facturation sont transmis à cette vérification.

Le module débite ensuite le jeton à usage unique via l'API Braintree pour le total du panier, dans la devise du panier, avec le numéro de panier comme identifiant de commande dans Braintree. Aucune commande n'existe avant cette étape. Le montant et la devise débités sont comparés au panier. La commande n'est créée qu'après l'acceptation du paiement par Braintree, et le client voit la page standard de confirmation de commande de PrestaShop.

Si le paiement échoue, aucune commande n'est créée, la raison est inscrite dans le journal du module, et le client reste à l'étape de paiement avec un message, 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 ou le montant débité ne correspond pas au panier, 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.

Un panier n'est jamais débité deux fois. Un second envoi 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. Si la carte a été débitée mais que PrestaShop n'a pas pu créer la commande, le client voit Your payment was received, but the order could not be completed automatically. Please contact us — do not pay again. La tentative suivante pour le même panier crée la commande à partir de la transaction enregistrée, sans nouveau débit.

Le module ne prend que les paiements par carte. Il ne gère ni cartes enregistrées, ni abonnements ou paiements récurrents, ni PayPal, Venmo, Apple Pay, Google Pay ou modes de paiement locaux, et il n'utilise pas de webhooks Braintree.

Commandes et remboursements

Statuts de commande

Pas encore de commande: le paiement n'a pas été effectué ou a été refusé. Seul le panier existe.

Payment accepted: la carte a été débitée (Sale), ou une autorisation a été capturée. Le paiement est enregistré avec l'identifiant de transaction Braintree, et une note privée dans les messages de la commande indique le montant, l'identifiant de transaction et le résultat 3-D Secure.

Braintree payment authorized: les fonds sont seulement autorisés (Authorize only). Aucun paiement n'est enregistré tant que vous ne l'avez pas capturé.

Braintree payment on hold: Braintree a renvoyé un statut de transaction inattendu, ou un débit dans une devise ou pour un montant incorrect n'a pas pu être annulé automatiquement. La note explique ce qu'il faut vérifier dans le Braintree Control Panel.

Canceled: une autorisation a été annulée.

Refunded: le paiement a été entièrement remboursé via le module.

Si une autre transaction arrive pour une commande déjà enregistrée, la commande n'est pas modifiée. Une note vous demande de la vérifier dans le Braintree Control Panel et de l'annuler ou de la rembourser.

Bloc Braintree payment

La page de commande affiche un bloc Braintree payment avec l'identifiant de transaction (lié à la transaction dans le Braintree Control Panel de son environnement), le statut de la transaction, le montant et le compte marchand, le résultat 3-D Secure, le montant débité et remboursé, un badge Sandbox pour les paiements sandbox et l'historique des remboursements. Les boutons du bloc nécessitent le droit de modifier les commandes ; l'accès aux pages Modules n'est pas nécessaire.

Capture et annulation

Pour une commande au statut Braintree payment authorized, cliquez sur Capture Braintree payment pour débiter le total de la commande, ou sur Void Braintree authorization pour libérer le montant bloqué. La capture passe la commande au statut Payment accepted et enregistre le paiement ; l'annulation la passe au statut Canceled. Si l'action échoue, l'erreur est affichée dans le bloc et ajoutée aux notes de la commande.

Remboursements

Dans le bloc Braintree payment, saisissez le montant (le montant non encore remboursé est pré-rempli), éventuellement un motif, puis cliquez sur Refund via Braintree. Confirmez la question Refund this amount through Braintree? This cannot be undone. Les remboursements totaux et partiels sont pris en charge. Les remboursements sont effectués dans le montant et la devise débités par Braintree ; ainsi, après un écart de montant ou de devise, vous pouvez rembourser jusqu'à concurrence de ce que le client a réellement payé. Braintree ne rembourse que les transactions réglées, généralement sous 24 heures. Avant le règlement, un remboursement total est effectué sous forme d'annulation ; un remboursement partiel échoue alors avec un message indiquant d'attendre le règlement. Le remboursement est envoyé à l'environnement (sandbox ou production) du paiement, les identifiants de cet environnement doivent donc être renseignés. Si Braintree refuse 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. Un remboursement total place la commande au statut Refunded ; un remboursement partiel ne modifie pas le statut.

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 Braintree. Les litiges (contestations de débit), les refus de règlement et les remboursements effectués dans le Braintree Control Panel ne sont pas synchronisés avec PrestaShop.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Braintree Gateway est le premier bloc de Modules > Module Manager > VibeFox Braintree 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-braintree 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, Braintree n'est pas proposé aux clients sur la page 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 captures, annulations et 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

Braintree n'apparaît pas sur la page de paiement : vérifiez que la licence est active, que Enable/Disable est activé et que l'environnement 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. Dans Payment > Preferences, vérifiez que le module est autorisé pour la devise du panier, le pays du client et le groupe du client.

La carte a été débitée, mais aucune commande n'a été créée : les paiements par carte sont confirmés immédiatement, sans webhook. Consultez le champ Log sur la page du module. Si le journal indique que la réponse de Braintree a été perdue, vérifiez dans le Braintree Control Panel s'il existe une transaction ayant le numéro de panier comme identifiant de commande avant d'accepter un autre paiement. Si la commande n'a pas pu être créée après le débit, la tentative de paiement suivante pour le même panier la crée sans nouveau débit.

Le formulaire de carte affiche Could not initialize payment form : les clés de l'environnement 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ù la SCA est obligatoire).

Le client est informé que le paiement n'a pas pu être traité dans la devise de la commande : Braintree a débité dans la devise du compte marchand. Saisissez l'identifiant de compte marchand correspondant à la devise du panier dans le champ de compte marchand de l'environnement actuel.

Le client voit le message The order total must be greater than zero to pay by card : le total du panier est égal à zéro, par exemple après un bon de réduction. Ces commandes ne peuvent pas être payées par carte.

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 maintenant, ou effectuez le remboursement partiel après le règlement.

Un remboursement, une capture ou une annulation échoue avec un message concernant l'environnement : le paiement a été effectué dans l'environnement sandbox ou production, et les identifiants de cet environnement ne sont pas renseignés. Saisissez-les et réessayez.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox Braintree 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 de la passerelle et le journal sont supprimés. S'il est désactivé, tous les réglages sont conservés pour une future réinstallation. Les transactions et remboursements Braintree ainsi que les statuts de commande Braintree payment authorized et Braintree payment on hold sont toujours conservés, de sorte que les commandes payées auparavant peuvent encore être remboursées, capturées ou annulées 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. Ce module n'est ni affilié à Braintree ni approuvé par Braintree.