VibeFox Braintree for OpenCart — Aide

Prérequis

OpenCart : 3.0.x (testé sur 3.0.5.0) ou 4.0.2 et ultérieur (testé sur 4.1.0.3).

PHP : 8.0 ou ultérieur.

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. Le 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

Le téléchargement est un fichier zip unique contenant les paquets pour les deux versions d'OpenCart. Décompressez-le sur votre ordinateur. Il contient README.txt, le paquet OpenCart 3 wcp_braintree_gateway-oc3-(version).ocmod.zip et le paquet OpenCart 4 wcp_braintree_gateway.ocmod.zip. Installez uniquement le paquet correspondant à votre version d'OpenCart. La clé de licence est la même pour les deux versions.

OpenCart 3

1. Dans l'administration, allez dans Extensions > Installer, cliquez sur Upload et choisissez le fichier wcp_braintree_gateway-oc3-(version).ocmod.zip. L'extension n'a pas de modifications OCMOD : Extensions > Modifications n'a donc pas besoin d'être actualisé. Au lieu de l'installateur, vous pouvez aussi copier le contenu du dossier upload de ce paquet dans le dossier racine de votre boutique.

2. Allez dans Extensions > Extensions, choisissez le type Payments, repérez VibeFox Braintree Gateway et cliquez sur Install (le bouton vert +). Votre utilisateur administrateur doit avoir le droit de modifier la liste des extensions de paiement.

3. Cliquez sur Edit (le bouton crayon) pour ouvrir la page des réglages. Collez votre clé de licence VibeFox dans License key, dans le bloc de licence en haut de la page, puis cliquez sur Activate (voir la section 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. Laissez Sandbox mode activé et passez une commande de test avec une carte de test sandbox Braintree, par exemple 4111 1111 1111 1111. Saisissez ensuite les identifiants de production et désactivez Sandbox mode pour recevoir de vrais paiements.

OpenCart 4

1. Dans l'administration, allez dans Extensions > Installer, cliquez sur Upload et choisissez le fichier wcp_braintree_gateway.ocmod.zip. Ne renommez pas le fichier : OpenCart 4 tire le code de l'extension du nom du fichier, et un paquet renommé ne fonctionne pas.

2. Le paquet apparaît dans la liste des extensions installées sur la même page. Cliquez sur Install (le bouton vert +) à côté.

3. Allez dans Extensions > Extensions, choisissez le type Payments. Repérez VibeFox Braintree Gateway, cliquez sur Install (le bouton vert +), puis sur Edit (le bouton crayon).

4. Saisissez la clé de licence et les identifiants Braintree, et testez le paiement comme aux étapes 3 à 5 pour OpenCart 3. La page des réglages et ses champs sont identiques dans les deux versions.

Une nouvelle installation démarre avec le mode de paiement désactivé et le mode sandbox activé.

Configuration

Tous les réglages se trouvent sur la page de l'extension : Extensions > Extensions > Payments > VibeFox Braintree Gateway > Edit. Les sections sont listées à gauche ; le bouton Save situé sous la liste enregistre la page entière. 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é au moment du 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. Sans le droit de modifier l'extension, la page affiche les réglages mais ne peut pas les enregistrer.

Lors de l'enregistrement, Title doit comporter de 1 à 128 caractères, Sort Order doit être un nombre entier et Total un nombre égal ou supérieur à 0. Si un champ comporte une erreur, rien n'est enregistré et la page indique le champ concerné.

Braintree

Enable/Disable : active ou désactive les paiements par carte Braintree. Le mode de paiement est masqué au moment du paiement tant que le Merchant ID, la clé publique et la clé privée de l'environnement sélectionné ne sont pas renseignés. Par défaut : désactivé.

Title : le nom du mode de paiement que les clients voient au moment du paiement. C'est aussi le nom du mode de paiement enregistré dans la commande. Par défaut : Credit / debit card. Obligatoire, jusqu'à 128 caractères.

Description : le texte affiché au client à l'étape Confirm Order, au-dessus du formulaire de carte. Par défaut : Pay securely with your credit or debit card via Braintree.

Sort Order : la position de Braintree parmi les modes de paiement au moment du paiement. Laissez le champ vide ou saisissez un nombre entier.

Geo Zone : proposez Braintree uniquement pour les adresses de facturation de la zone géographique sélectionnée. Par défaut : All zones. Les zones géographiques se configurent dans System > Localisation > Geo Zones.

Total : le montant total de la commande, dans la devise par défaut de la boutique, que doit atteindre une commande pour que Braintree soit proposé. Laissez le champ vide pour proposer Braintree quel que soit le montant.

Identifiants de l'API

Connectez-vous au Braintree Control Panel (sandbox ou production, liés dans cette section), 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, aucun argent réel). Par défaut : activé. Désactivez-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. Lorsqu'il est activé, les clients voient SANDBOX / TEST MODE — no real money is charged. à l'étape Confirm Order.

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, enregistrée exactement comme elle a été saisie. 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. Pour supprimer une clé enregistrée, cochez Clear the saved key on save sous le champ puis cliquez sur Save.

Sandbox merchant account ID(s) et Live merchant account ID(s) : facultatif. Braintree débite dans la devise du compte marchand. Laissez le champ 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 : le 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 également ê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 du 3-D Secure est vérifié côté serveur, et pas seulement dans le navigateur, avant le débit de la carte.

Commandes

OpenCart crée la commande à l'étape Confirm Order sans statut (une commande manquante). Elle n'obtient un statut qu'après l'acceptation du paiement par carte par Braintree. Une carte refusée laisse la commande sans statut, et le client reste à l'étape de confirmation. Chaque champ ci-dessous liste les statuts de commande de votre OpenCart.

Order Status After Payment : une vente a été capturée, ou une autorisation a été capturée depuis l'onglet de la commande. Par défaut : En cours.

Authorized Status : autorisation seule : le montant est réservé, pas encore payé. Par défaut : En attente de paiement, car OpenCart n'a pas de statut En attente ; la note de commande et l'onglet de la commande l'expliquent. Vous pouvez créer votre propre statut dans System > Localisation > Order Statuses et le sélectionner ici.

On Hold (Review) Status : Braintree a renvoyé un statut de transaction inattendu, ou le montant ou la devise débité ne correspondait pas et l'annulation automatique a échoué. Une note explique ce qu'il faut vérifier. Par défaut : En attente de paiement.

Voided Status : l'autorisation a été annulée depuis l'onglet de la commande et le montant bloqué est libéré. Par défaut : Annulée.

Refunded Status : le paiement est entièrement remboursé, ou annulé comme remboursement total avant le règlement. Les remboursements partiels ajoutent seulement une note. Par défaut : Remboursée.

Avancé

Debug log : enregistre aussi les appels à l'API et les étapes de paiement dans wc_btg_debug.log.php, dans le dossier des journaux d'OpenCart (storage/logs). Le fichier ne peut pas être ouvert depuis le web. Les erreurs sont toujours enregistrées, même lorsque cette option est désactivée. Le journal ne contient jamais de clés API ni de données de carte ou de client. 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'il est activé, la désinstallation de l'extension supprime les réglages de la passerelle et le journal. Les transactions et remboursements 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 : désactivé.

Import / Export

Export : Download JSON enregistre les réglages dans un fichier JSON. Les clés privées ne sont pas exportées.

Import : collez le JSON exporté précédemment et cliquez sur Import pour restaurer les réglages. Les clés privées enregistrées sont conservées.

Paiement

À l'étape Payment Method, le client choisit le mode de paiement (par défaut Credit / debit card). À l'étape Confirm Order, le client voit votre description et le formulaire de carte Braintree, chargé depuis Braintree dans la langue de la boutique. OpenCart crée la commande à cette étape, toujours sans statut. Lorsque le client clique sur Confirm Order, le formulaire vérifie la carte et, si le 3-D Secure est activé, le client effectue la vérification de sa banque ; le total de la commande, l'e-mail et l'adresse de facturation sont transmis au formulaire. Seul un jeton à usage unique parvient à votre boutique. Sur OpenCart 4, le client choisit le mode de paiement avec le bouton Choose du bloc de mode de paiement, dans la fenêtre Payment method options. Le formulaire de carte apparaît alors dans le bloc de confirmation, en bas de la page de paiement, au-dessus du bouton Confirm Order. Si la boutique ne demande pas d'adresse de paiement (valeur par défaut d'OpenCart 4), la vérification 3-D Secure utilise l'adresse de livraison à la place.

L'extension débite ensuite ce jeton via l'API Braintree pour le total de la commande dans la devise de la commande, avec le numéro de commande OpenCart comme identifiant de commande dans Braintree. Le montant et la devise débités sont vérifiés par rapport à la commande. La commande ne reçoit son statut qu'une fois que Braintree a accepté le paiement, de la manière standard d'OpenCart, avec les e-mails habituels de commande et la mise à jour des stocks. Le panier est vidé et le client voit la page de confirmation de commande d'OpenCart.

Si le paiement échoue, la commande reste sans statut, une note indiquant le motif est ajoutée à la commande, et le client reste à l'étape Confirm Order 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 saisir à nouveau la carte et réessayer immédiatement. Si la devise ou le montant débité 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. 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. Une nouvelle confirmation d'une commande payée mène directement à la page de succès ; pour un paiement autorisé, elle affiche A payment for this order has already been received and is awaiting review. Si la carte a été débitée mais qu'OpenCart n'a pas pu appliquer le statut de 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 avec le même panier applique le statut de cette commande à partir de la transaction enregistrée, sans nouveau débit. OpenCart 3 crée une nouvelle commande à chaque affichage de l'étape Confirm Order, donc un même panier peut avoir plusieurs commandes (OpenCart 4 garde une seule commande pour le paiement et la met à jour, de sorte qu'après une carte refusée le client paie la même commande) : dès qu'une d'elles est payée, une autre commande du même panier n'est pas débitée, et le client voit This cart has already been paid with order #…. Please check your order history — do not pay again.

OpenCart 4 garde la commande à l'étape de paiement jusqu'à l'affichage de la page de succès. Si cette commande a été fermée par la boutique entre-temps (par exemple annulée, autorisation annulée ou remboursée), ou si elle est déjà payée et que le panier a changé depuis (autres produits ou quantités), Confirm Order renvoie le client à l'étape de paiement, ce qui crée une nouvelle commande du panier avec son propre paiement. Le même panier soumis deux fois mène toujours à la page de succès, sans second débit.

L'extension ne prend que les paiements par carte. Elle ne gère ni cartes enregistrées, ni abonnements ou paiements récurrents, ni PayPal, Venmo, Apple Pay, Google Pay ou les modes de paiement locaux, ni webhooks Braintree.

Commandes et remboursements

Statuts de commande

Aucun statut (commande manquante) : le paiement n'a pas été effectué ou a été refusé. Dans Sales > Orders, ces commandes ne s'affichent qu'avec le filtre Order Status réglé sur Missing Orders.

Order Status After Payment (par défaut Processing) : la carte a été débitée (Sale), ou une autorisation a été capturée. Une note indique le montant, l'identifiant de transaction Braintree et le résultat du 3-D Secure.

Authorized Status (par défaut Pending) : les fonds sont seulement autorisés (Authorize only). Une note vous invite à capturer le paiement depuis la page de la commande avant l'expédition.

On Hold (Review) Status (par défaut Pending) : Braintree a renvoyé un statut de transaction inattendu, ou un débit dans une mauvaise devise ou d'un mauvais montant n'a pas pu être annulé automatiquement. La note explique ce qu'il faut vérifier dans le Braintree Control Panel.

Voided Status (par défaut Canceled) : une autorisation a été annulée.

Refunded Status (par défaut Refunded) : le paiement a été entièrement remboursé via l'extension.

Les notes sont des entrées de l'History de la commande, invisibles pour le client.

Onglet VibeFox Braintree Gateway

Dans Sales > Orders, ouvrez une commande payée avec Braintree. En bas de la page de commande, à côté de History et de Additional, l'onglet VibeFox Braintree Gateway affiche le Transaction ID (lié à la transaction dans le Braintree Control Panel de son environnement), accompagné d'un libellé Sandbox pour les paiements sandbox, le Status de la transaction, le Amount et le compte marchand, le résultat du 3-D Secure, les montants Charged / refunded, les boutons de capture, d'annulation et de remboursement, l'historique des remboursements et les Braintree notes de la commande. L'onglet est affiché aux utilisateurs qui ont accès à l'extension ; les boutons nécessitent le droit de la modifier (défini dans System > Users > User Groups).

Capture et annulation

Pour un paiement autorisé, cliquez sur Capture Braintree payment pour débiter le total de la commande, ou sur Void Braintree authorization pour libérer le montant bloqué et annuler la commande. La capture place la commande au statut Order Status After Payment ; l'annulation la place au statut Voided Status. Si l'action échoue, l'erreur s'affiche dans l'onglet et est ajoutée aux notes de la commande.

Remboursements

Dans l'onglet VibeFox Braintree Gateway, saisissez le Amount (le montant non encore remboursé est prérempli), éventuellement un Reason (optional), puis cliquez sur Refund via Braintree. Confirmez la question Rembourser ce montant via Braintree ? Cette action est irréversible. Les remboursements totaux et partiels sont pris en charge, pour un paiement capturé comme pour un paiement en cours de vérification. Les remboursements sont effectués dans le montant et la devise débités par Braintree. 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 invitant à 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 n'accepte pas le remboursement, l'onglet 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 Refunded Status ; un remboursement partiel ne modifie pas le statut. Les changements de statut depuis l'onglet n'avertissent pas le client et ne remettent pas les produits en stock, comme un changement de statut manuel.

Les retours de produits dans Sales > Returns ne renvoient pas d'argent via Braintree. Les litiges (chargebacks), les refus de règlement et les remboursements effectués dans le Braintree Control Panel ne sont pas synchronisés avec OpenCart.

Clé de licence

L'extension fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Braintree Gateway est le premier bloc de Extensions > Extensions > Payments > VibeFox Braintree Gateway > Edit, au-dessus des réglages. Collez 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: opencart-payment-braintree et le lien Manage licenses and domains in your account, qui ouvre votre compte vibefox.net. Seuls les utilisateurs administrateurs disposant du droit Modify sur l'extension peuvent modifier la clé. Les textes du bloc suivent la langue de l'administration (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, l'extension continue de fonctionner avec le dernier statut connu.

Une clé fonctionne sur un seul domaine : l'adresse de la boutique définie dans la configuration d'OpenCart. 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 affiché aux clients au moment du paiement. Si un paiement est tout de même lancé, le client voit This payment method is not available. Please choose another one. Un utilisateur administrateur connecté à l'administration dans le même navigateur voit toujours le mode de paiement dans la boutique, marqué (unlicensed — visible to admins only), afin que vous puissiez configurer et tester l'extension avant d'acheter une clé. Sur OpenCart 4, cet aperçu n'est pas disponible : la boutique ne voit pas la connexion à l'administration, donc sans clé active, le mode de paiement est masqué pour tout le monde. Après avoir ouvert une fois la page Edit, un rappel apparaît sur le Dashboard de l'administration. Fermez-le avec × pour le masquer pendant 7 jours. 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, l'extension continue de fonctionner, mais les mises à jour et l'assistance nécessitent un renouvellement. Le statut est vérifié à nouveau automatiquement lorsque vous ouvrez le Dashboard de l'administration ou la page Edit : 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 de l'extension supprime toujours la clé de licence et le statut de licence.

Dépannage

Braintree n'apparaît pas au moment du 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. Vérifiez également que l'adresse de facturation se trouve dans la Geo Zone sélectionnée et que la commande atteint le Total défini dans les réglages.

La carte a été débitée, mais la commande reste sans statut : les paiements par carte sont confirmés immédiatement, sans webhook. Consultez les notes de la commande et le champ Log sur la page de l'extension. Si une note indique que la réponse de Braintree a été perdue, recherchez dans le Braintree Control Panel une transaction portant ce numéro de commande avant d'accepter un autre paiement. Si le statut n'a pas pu être appliqué après le débit, la tentative de paiement suivante avec le même panier l'appliquera 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 de compte marchand n'existe pas dans ce compte. Vérifiez les clés et les identifiants de comptes marchands, puis rechargez la page.

Le client voit Your session has expired. Please refresh the page and try again. : la session de paiement a changé pendant que le formulaire était ouvert. Le client doit recharger la page de paiement.

Le 3-D Secure échoue pour chaque paiement : le 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 du compte marchand de la devise de la commande dans le champ de compte marchand de l'environnement actuel.

Le client voit The order total must be greater than zero to pay by card. : le total de la commande est nul, par exemple après un bon d'achat. 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.

Aucun bouton dans l'onglet, ou un message concernant l'environnement : votre groupe d'utilisateurs n'a pas le droit de modifier l'extension, ou 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 Extensions > Extensions, choisissez le type Payments et cliquez sur Uninstall (le bouton rouge −) à côté de VibeFox Braintree Gateway. La clé de licence et le statut de licence de cette extension sont toujours supprimés. OpenCart supprime toujours ses propres réglages de l'extension : Enable/Disable, Sort Order, Geo Zone, Total et les statuts de commande de la section Orders, qui reprennent leurs valeurs par défaut lors d'une réinstallation. Si Delete data on uninstall est activé, les autres réglages de la passerelle (titre, description, mode sandbox, identifiants, comptes marchands, type de transaction, 3-D Secure, journal de débogage) et le journal sont supprimés. S'il est désactivé, ils sont conservés pour une réinstallation ultérieure. Les transactions et remboursements 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. Les commandes existantes conservent leurs notes de paiement.

Sur OpenCart 4, pour supprimer aussi les fichiers de l'extension, allez dans Extensions > Installer après la désinstallation, cliquez sur Uninstall (le bouton orange −) à côté de VibeFox Braintree Gateway dans la liste des extensions installées, puis sur Delete (le bouton rouge en forme de corbeille) pour supprimer le paquet envoyé.

Braintree est une marque déposée de son titulaire. Cette extension n'est ni affiliée à Braintree ni approuvée par Braintree.