VibeFox Authorize.Net 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.

HTTPS : votre page de paiement doit utiliser HTTPS. Accept.js refuse de fonctionner sur les pages HTTP non sécurisées.

Compte Authorize.Net : il vous faut l'API Login ID, la Transaction Key et la Public Client Key de votre compte Authorize.Net, ainsi qu'une Signature Key si vous utilisez des webhooks. Les comptes de production (account.authorize.net) et de sandbox (sandbox.authorize.net) ont des identifiants différents. Les comptes Authorize.Net sont accessibles aux marchands des États-Unis, du Canada, du Royaume-Uni, d'Europe, d'Australie et de Nouvelle-Zélande.

Devise : la devise du panier doit être USD, CAD, CHF, DKK, EUR, GBP, NOK, PLN, SEK, AUD ou NZD, et votre compte Authorize.Net doit régler dans cette devise. Pour les autres devises, le mode de paiement est masqué sur la page de paiement.

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éversement terminé, cliquez sur Configure, ou retrouvez plus tard VibeFox Authorize.Net 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. Saisissez les identifiants des comptes sandbox et production (voir Configuration). Configurez éventuellement le webhook.

5. Activez Enable/Disable, choisissez le Transaction type et cliquez sur Save. Testez un paiement en mode sandbox avec la carte 4111 1111 1111 1111, une date d'expiration future quelconque et un CVV quelconque, puis désactivez Sandbox mode.

À l'installation, le module crée deux statuts de commande : Authorize.Net payment authorized et Authorize.Net payment on hold. PrestaShop active le nouveau module de paiement pour toutes les devises, tous les pays et tous les groupes de clients. Vous pouvez les restreindre dans Payment > Preferences.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox Authorize.Net Gateway > Configure. Chaque section a son propre bouton Save, qui enregistre toute la page. Au-dessus des champs, la page vous avertit si SSL n'est pas activé pour la boutique (Accept.js ne fonctionne que sur les pages HTTPS), si la devise par défaut de la boutique n'est pas prise en charge par Authorize.Net, si le mode actuel n'a pas d'API Login ID, de Transaction Key ou de Public Client Key (le mode de paiement est alors masqué sur la page de paiement) et si le mode actuel n'a pas de Signature Key (les webhooks sont alors désactivés). Lorsque le mode sandbox est activé, la page affiche Sandbox mode is on: test transactions, no real charges.

Authorize.Net

Enable/Disable : Enable Authorize.Net active ou désactive le mode de paiement. Par défaut : désactivé.

Title : le nom du mode de paiement que voient les clients sur la page de paiement. Il est aussi le nom du mode de paiement enregistré dans la commande. Par défaut : Credit Card. Obligatoire.

Description : le texte affiché sous le mode de paiement sur la page de paiement. Par défaut : Pay securely with your credit card via Authorize.Net.

Identifiants API

Dans Merchant Interface d'Authorize.Net, ouvrez Account > Settings > Security Settings. Sous API Credentials & Keys, copiez l'API Login ID et créez une Transaction Key ainsi qu'une Signature Key. Sous Manage Public Client Key, copiez la Public Client Key. Le sandbox et la production utilisent des identifiants différents. La page affiche les champs des deux modes, vous pouvez donc conserver les deux jeux.

Sandbox mode : utilise le sandbox d'Authorize.Net (transactions de test, aucun débit réel). Il bascule le point d'accès de l'API, Accept.js et l'ensemble des identifiants utilisés pour les nouveaux paiements. Par défaut : activé. Désactivez-le pour encaisser de vrais paiements. Tant qu'il est activé, les clients voient une indication avec la carte de test 4111 1111 1111 1111 sous le mode de paiement.

Sandbox API Login ID et Live API Login ID : l'API Login ID du compte sandbox ou de production.

Sandbox Transaction Key et Live Transaction Key : la Transaction Key de ce compte.

Sandbox Public Client Key et Live Public Client Key : la clé publique utilisée par Accept.js dans le navigateur.

Sandbox Signature Key et Live Signature Key : nécessaires uniquement pour les webhooks. Elle vérifie l'en-tête X-ANET-Signature de chaque notification.

Les Transaction Keys et Signature Keys 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 si vous voulez la modifier.

Clear saved secrets : cochez une clé et 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. Une autorisation expire au bout de 30 jours.

Webhooks (recommandés)

Sans webhooks, les commandes retenues par Fraud Detection Suite, ou capturées ou annulées dans l'interface Authorize.Net, doivent être mises à jour manuellement. Dans Merchant Interface, allez dans Account > Settings > Business Settings > Webhooks et cliquez sur Add Endpoint, dans le compte sandbox comme dans le compte de production. Utilisez l'URL affichée dans Endpoint URL dans cette section. Avec des URL conviviales, elle ressemble à https://your-shop/module/wcp_authorizenet_gateway/webhook, éventuellement avec un code de langue comme /en/. Copiez l'URL exactement telle qu'elle apparaît dans les réglages. Sélectionnez ces événements (ils figurent aussi dans cette section) :

Saisissez la Signature Key de chaque compte dans Sandbox Signature Key ou Live Signature Key. Les webhooks sans signature valide sont rejetés. Une notification doit être signée avec la clé du mode dans lequel le paiement a été effectué ; une notification de l'autre mode ne modifie rien. Pour chaque notification, le module demande aussi à Authorize.Net le statut et le montant actuels de la transaction avant de modifier la commande, de sorte que les notifications répétées ne changent rien.

Avancé

Debug log : écrit les requêtes et réponses de l'API dans logs/wc_ang_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les clés, jetons de carte et données personnelles sont masqués. Par défaut : désactivé. Les erreurs, comme les paiements refusés ou échoués, les erreurs d'API et les remboursements échoués, sont toujours journalisées, même si cette option est désactivée.

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 et le journal. Les transactions Authorize.Net, les remboursements et les statuts de commande du module sont toujours conservés, de sorte que les commandes payées auparavant peuvent encore être capturées et remboursées après une réinstallation. Par défaut : désactivé.

Paiement

À l'étape de paiement, le client choisit le mode de paiement (par défaut Credit Card) et saisit le numéro de carte, la date d'expiration (MM/YY) et le code de sécurité (CVV) dans le formulaire situé dessous. Accept.js n'est chargé que sur la page de paiement. Lorsque le client passe la commande, Accept.js échange les données de la carte contre un jeton à usage unique dans le navigateur. Les champs de carte n'ont pas de noms de formulaire : le numéro de carte et le CVV ne sont donc jamais envoyés à votre serveur.

Le module débite le jeton via l'API Authorize.Net pour le total du panier, dans la devise du panier. L'adresse de facturation, l'adresse e-mail et l'adresse IP sont transmises avec la transaction pour la vérification d'adresse et les filtres antifraude. Le numéro de panier est envoyé comme numéro de facture, car aucune commande n'existe avant le paiement. La commande n'est marquée comme payée qu'après confirmation par Authorize.Net : si la transaction est approuvée, la commande est créée immédiatement et le client voit la page de confirmation de commande standard avec Your card payment has been received. Avec Authorize only, la page affiche Your card payment has been authorized. The amount will be charged when your order is processed. Si Fraud Detection Suite retient la transaction, la page affiche Your payment is being reviewed. We will update your order as soon as the review is complete.

Si la carte est refusée, le client reste à l'étape de paiement et voit Payment failed: suivi de la raison, par exemple une carte refusée, un mauvais code de sécurité ou une carte expirée. Aucune commande n'est créée et le panier est conservé. Les erreurs de configuration et d'API ne sont pas affichées aux clients : ils voient un message général, et les détails sont écrits dans le journal. Si la boutique ne peut pas joindre Authorize.Net, le client voit Payment error: unable to connect to the payment gateway. Please try again. Si les champs de carte sont vides, le formulaire demande Please enter the card number, expiry date and card code.

Un double clic, un second onglet ou un envoi répété ne débitent jamais deux fois un même panier. Une seconde tentative pendant que la première est toujours en cours affiche Your payment is already being processed. Please wait a moment and check your order history before trying again. Si un paiement a été approuvé mais que la commande n'a pas pu être créée, le client voit Your payment was received, but the order could not be completed automatically. Please contact us — do not pay again. La commande est alors créée à partir du paiement approuvé lors de la prochaine tentative ou par le webhook, sans débiter à nouveau la carte.

Si le panier change pendant le traitement du paiement, le montant débité ne correspond plus au panier. La commande passe alors en Authorize.Net payment on hold avec une note, et le paiement est enregistré pour le montant réellement débité.

Le webhook fonctionne même lorsque la boutique est en mode maintenance, et il n'est pas bloqué par la restriction par pays de votre boutique.

Le module ne gère ni cartes enregistrées ni profils clients, ni abonnements ou paiements récurrents, ni eCheck/ACH, Apple Pay, Google Pay, PayPal ou 3-D Secure, ni capture partielle d'une autorisation, ni conversion automatique de devise.

Commandes et remboursements

Statuts de commande

No order : la carte a été refusée ou le paiement a échoué. Seul le panier existe.

Payment accepted : la carte a été débitée (Authorize and capture), ou une autorisation a été capturée. Le paiement est enregistré avec le Trans ID Authorize.Net comme identifiant de transaction, et une note indique le montant, le Trans ID, le code d'autorisation, le type de carte et les quatre derniers chiffres.

Authorize.Net payment authorized : les fonds sont seulement autorisés (Authorize only). Capturez-les avant l'expédition.

Authorize.Net payment on hold : Fraud Detection Suite a retenu la transaction pour examen, le montant débité ne correspond pas au total de la commande, ou une capture signalée par webhook ne correspond pas au montant de la commande. La note l'explique. Approuvez ou refusez une transaction retenue dans l'interface Authorize.Net ; avec les webhooks, la commande est mise à jour automatiquement.

Canceled : un webhook a signalé que la transaction avait été refusée, annulée ou expirée avant le paiement de la commande, ou vous avez annulé une autorisation qui n'avait pas été capturée. Si la transaction d'une commande payée est annulée dans l'interface Authorize.Net, son statut ne change pas et une note d'avertissement est ajoutée.

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

Si une seconde transaction est approuvée pour un panier qui a déjà une commande, la commande n'est pas modifiée. Une note vous invite à vérifier le doublon et à l'annuler ou le rembourser dans l'interface Authorize.Net.

Bloc de paiement Authorize.Net

La page de commande affiche un bloc Authorize.Net payment avec le Trans ID, le type de transaction, le statut de la transaction, la carte et le code d'autorisation, le montant débité, le total de la commande et le montant remboursé, un badge Sandbox pour les paiements sandbox, l'historique des remboursements et les Authorize.Net notes de la commande. La capture et les remboursements nécessitent seulement le droit de modifier les commandes, et non l'accès aux pages des modules.

Capture

Pour une commande en Authorize.Net payment authorized, cliquez sur Capture payment dans le bloc et confirmez Capture the authorized amount through Authorize.Net? Le montant autorisé est capturé, le paiement est enregistré avec le Trans ID et la commande passe en Payment accepted. Si la capture échoue, l'erreur est affichée et ajoutée aux notes. Vous pouvez aussi capturer dans l'interface Authorize.Net ; avec les webhooks, la commande est mise à jour automatiquement.

Remboursements

Dans le bloc, saisissez le montant (le montant non encore remboursé est prérempli), éventuellement un motif, cliquez sur Refund via Authorize.Net et confirmez Refund this amount through Authorize.Net? This cannot be undone. Un remboursement du montant total annule d'abord la transaction si elle n'est pas encore réglée, ou une autorisation non capturée. Les transactions réglées, généralement après 24 heures, peuvent être remboursées en totalité ou en partie. Avant le règlement, un remboursement partiel n'est pas possible : remboursez le montant total pour annuler la transaction, ou réessayez après le règlement. Les remboursements sont effectués dans le montant et la devise débités par Authorize.Net ; ainsi, après un écart de montant, vous pouvez rembourser jusqu'au montant que le client a réellement payé, et non le total de la commande. Si Authorize.Net refuse le remboursement, le bloc affiche l'erreur et aucun remboursement n'est enregistré. Un remboursement ou une annulation réussi est ajouté à l'historique des remboursements et aux notes. Un remboursement total fait passer la commande en Refunded (Canceled lorsque seule une autorisation a été annulée). Un remboursement partiel ne change pas le statut. Tant qu'une transaction est retenue pour examen, les remboursements ne sont pas proposés.

Les captures, remboursements et vérifications de webhooks d'une commande utilisent les identifiants du mode dans lequel la commande a été payée. Les commandes de l'autre mode peuvent donc encore être capturées et remboursées après le changement de Sandbox mode. Conservez les identifiants de ce mode dans leurs champs jusqu'à ce que ces commandes soient traitées.

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 Authorize.Net. Les remboursements effectués dans l'interface Authorize.Net ne sont pas signalés à la boutique : mettez la commande à jour manuellement.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Authorize.Net Gateway est le premier bloc de Modules > Module Manager > VibeFox Authorize.Net 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-authorizenet 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 domaine : le domaine 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é de licence active, le paiement par carte Authorize.Net n'est pas proposé aux clients sur la page de paiement. Si un paiement est lancé malgré tout, le client voit This payment method is not available. Please choose another one. La boutique 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 sur la page 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 et 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

Authorize.Net n'apparaît pas sur la page de paiement : vérifiez que la licence est active, que Enable/Disable est activé et que le mode actuel dispose d'une API Login ID, d'une Transaction Key et d'une Public Client Key. La page des réglages affiche un avertissement si l'une d'elles manque. Vérifiez que la devise du panier est prise en charge et, dans Payment > Preferences, que le module est autorisé pour la devise du panier, le pays du client et le groupe du client.

Le paiement a abouti, mais la commande reste en Authorize.Net payment on hold ou authorized : le type de transaction est Authorize only (capturez-la dans le bloc de la commande), ou Authorize.Net a retenu la transaction pour examen. Approuvez-la ou refusez-la dans l'interface Authorize.Net. Pour que ces commandes soient mises à jour automatiquement, configurez le webhook : vérifiez que le point de terminaison existe dans le compte du mode utilisé, que son URL est exactement celle affichée dans Endpoint URL, que les quatre événements sont sélectionnés et que la Signature Key de ce compte est saisie.

Webhook answers webhooks are not configured : aucune Signature Key n'est saisie pour aucun des deux modes.

Webhook answers invalid signature : la Signature Key appartient à un autre compte, ou une clé a été modifiée dans Authorize.Net. Recréez ou recopiez la Signature Key et collez-la dans le champ de son mode.

Webhook answers mode mismatch : la notification a été signée avec la clé d'un mode, mais le paiement a été effectué dans l'autre mode. Vérifiez que les Signature Keys sandbox et live ne sont pas inversées.

Webhook answers verification failed, retry later : la boutique n'a pas pu lire la transaction depuis l'API Authorize.Net, ou les identifiants du mode du paiement sont absents. Authorize.Net renouvelle la livraison.

Webhook answers busy, retry later : la commande é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. Authorize.Net renouvelle la livraison. Consultez le champ Log pour connaître la raison.

L'URL du webhook affiche method not allowed dans le navigateur : c'est normal. L'URL n'accepte que les requêtes d'Authorize.Net.

Le formulaire de carte affiche The secure card form (Accept.js) could not be loaded : la page de paiement doit utiliser HTTPS, et la Public Client Key et l'API Login ID du mode actuel doivent être corrects.

Payment error: the card could not be tokenized : Accept.js n'a renvoyé aucun jeton. Le client doit saisir à nouveau les données de la carte et réessayer.

Le client voit une erreur générale : consultez le champ Log sur la page du module ; les erreurs y sont toujours écrites. Une devise non prise en charge par le compte est refusée par Authorize.Net.

Un remboursement partiel échoue parce que la transaction n'est pas encore réglée : remboursez le montant total pour annuler la transaction, ou réessayez après le règlement, généralement dans les 24 heures.

Le remboursement ou la capture échoue avec un message concernant le mode : le paiement a été effectué en mode sandbox ou production, et l'API Login ID et la Transaction Key de ce mode ne sont pas renseignées. Saisissez-les et réessayez.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox Authorize.Net 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 et le journal sont supprimés. S'il est désactivé, tous les réglages sont conservés pour une réinstallation ultérieure. Les transactions et remboursements Authorize.Net ainsi que les statuts de commande Authorize.Net payment authorized et Authorize.Net payment on hold sont toujours conservés, de sorte que les commandes payées auparavant peuvent encore être capturées et remboursées après une réinstallation. Les commandes existantes conservent leurs notes de paiement et leurs identifiants de transaction.

Authorize.Net est une marque déposée de son propriétaire. Ce module n'est ni affilié à Authorize.Net ni approuvé par cette société.