VibeFox Adyen 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 Adyen : vous avez besoin du nom de votre compte marchand Adyen, d'une clé API et d'une clé HMAC pour chaque environnement utilisé (test et production) et, pour les paiements réels, du préfixe d'URL de production. La clé API appartient à un identifiant API disposant des rôles Checkout webservice et Merchant PAL webservice. La clé HMAC est générée pour le webhook Standard (voir Configuration). L'espace client de test est ca-test.adyen.com, celui de production est ca-live.adyen.com. Les clés de test et de production sont distinctes. Aucune clé client n'est nécessaire, car la page de paiement est hébergée par Adyen.
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 Adyen 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 de configuration du module, puis cliquez sur Activate (voir Clé de licence).
4. Saisissez votre compte marchand, la clé API de test et la clé HMAC de test, puis plus tard la clé API de production, la clé HMAC de production et le préfixe d'URL de production.
5. Dans l'espace client Adyen (test et production), ajoutez un webhook Standard avec l'URL affichée dans la section Webhook du module (voir Configuration).
6. Activez Enable/Disable et cliquez sur Save. Testez un paiement avec Test mode activé, puis désactivez-le.
À l'installation, le module crée le statut de commande Adyen payment on hold. PrestaShop active le module de paiement pour les devises, pays et groupes de clients actifs à ce moment-là. Vérifiez-les et modifiez-les dans Payment > Preferences ; les pays que vous ajoutez plus tard doivent y être cochés.
Configuration
Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox Adyen Gateway > Configure. Chaque section a son propre bouton Save, qui enregistre la page entière. Tant que les réglages du mode en cours sont incomplets, la page affiche Adyen is hidden at checkout until the test settings are complete (ou les réglages de production) et indique ce qui manque : Merchant account, la clé API, la clé HMAC et, en mode production, Live URL prefix. Tant que le mode test est activé, la page affiche Test mode is on: payment links and refunds go to the Adyen test environment, no real money. Lors de l'enregistrement, une clé HMAC non hexadécimale et un préfixe d'URL de production contenant d'autres caractères que des lettres, des chiffres et des tirets ne sont pas enregistrés : un avertissement indique le champ, et la valeur précédente est conservée.
Adyen
Enable/Disable : Enable Adyen payment gateway active ou désactive le moyen de paiement. Par défaut : désactivé.
Title : le nom du moyen de paiement affiché aux clients au moment du paiement. C'est aussi le nom du moyen de paiement enregistré dans la commande. Par défaut : Adyen. Obligatoire.
Description : le texte affiché sous le moyen de paiement lors du paiement. Par défaut : Pay securely via Adyen.
Compte Adyen
Les clés API se créent dans l'espace client Adyen, sous Developers > API credentials. Renseignez les deux jeux de clés ; l'interrupteur Test mode détermine celui qui est utilisé.
Test mode : utilise l'environnement de test d'Adyen (aucun argent réel). Lorsqu'il est activé, les liens de paiement et les remboursements passent par checkout-test.adyen.com avec la clé API de test. Par défaut : activé. Désactivez-le pour encaisser de vrais paiements. Tant qu'il est activé, les clients voient Test mode: no real payment is taken. sous le moyen de paiement.
Merchant account : le nom de votre compte marchand Adyen (et non le compte de l'entreprise), par exemple MyShopECOM. Il est généralement le même dans l'espace client de test et dans celui de production.
Identifiants de test
Utilisés lorsque Test mode est activé.
Test API key : depuis l'espace client de test : Developers > API credentials > votre identifiant > API key.
Test HMAC key : depuis l'espace client de test : Developers > Webhooks > votre webhook Standard > HMAC key (hexadécimale). Obligatoire : les webhooks sans signature valide sont rejetés.
Identifiants de production
Utilisés lorsque Test mode est désactivé.
Live API key : depuis l'espace client de production : Developers > API credentials > votre identifiant > API key.
Live HMAC key : depuis l'espace client de production : Developers > Webhooks > votre webhook Standard > HMAC key (hexadécimale).
Live URL prefix : depuis l'espace client de production : Developers > API URLs, par exemple 1797a841fbb37ca7-AdyenDemo à partir de https://1797a841fbb37ca7-AdyenDemo-checkout-live.adyenpayments.com. Vous pouvez coller l'URL complète ; le préfixe en est extrait à l'enregistrement.
Les clés API et les clés HMAC enregistrées ne sont plus jamais affichées. Le champ reste vide et son indication se termine par Saved — leave empty to keep it. Ne saisissez une nouvelle valeur que si vous voulez la modifier.
Clear saved secrets : cochez une clé puis cliquez sur Save pour la supprimer. Un champ vide conserve la valeur enregistrée.
Webhook
Les commandes ne sont créées que par les webhooks Adyen. Dans l'espace client (test et production), allez dans Developers > Webhooks et ajoutez un Standard webhook avec l'URL affichée dans Webhook URL dans cette section. Avec les URL conviviales, elle ressemble à https://your-shop/module/wcp_adyen_gateway/webhook, éventuellement avec un code de langue comme /en/. Copiez l'URL exactement telle qu'elle apparaît dans les réglages, car Adyen ne suit pas les redirections. Choisissez le format JSON, activez Generate HMAC key et copiez la clé dans Test HMAC key ou Live HMAC key.
L'environnement de chaque notification détermine la clé HMAC, et une notification n'est appliquée qu'à un lien de paiement créé dans le même environnement et avec le même compte marchand. Une notification de test ne confirme jamais un paiement réel. Les webhooks sans signature valide sont rejetés avec le code HTTP 401, et Adyen les renvoie plus tard. Sans webhook, aucune commande n'est créée.
Le module gère ces événements :
Les autres événements sont ajoutés aux notes de commande. Les notifications qui ne concernent pas un panier de cette boutique, par exemple le bouton de test de l'espace client, sont acceptées et ignorées. Le webhook fonctionne lorsque la boutique est en mode maintenance et n'est pas bloqué par la restriction géographique de votre boutique.
Avancé
Order status after payment: le statut de commande défini par un webhook AUTHORISATION réussi.
Les écarts de montant ou de devise et les captures échouées passent toujours en Adyen payment on hold.
Debug log : écrit les appels API et les événements de webhook dans logs/adyg_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les erreurs sont toujours journalisées, même lorsque l'interrupteur est désactivé. Les journaux ne contiennent jamais de clés API ou HMAC ni de données personnelles des acheteurs. 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 du module supprime les réglages du module, les enregistrements de paiements Adyen (références PSP, événements de webhook, remboursements) et les journaux. Le statut de commande Adyen payment on hold et les commandes sont conservés. Par défaut : désactivé.
Tunnel de commande
À l'étape de paiement, le client choisit le moyen de paiement (par défaut Adyen) et voit la note You will be redirected to Adyen to complete the payment securely. Après confirmation, le module crée un lien de paiement Adyen pour le total du panier dans la devise du panier et envoie le client vers la page de paiement d'Adyen. Il y paie avec n'importe quel moyen activé dans votre compte Adyen. L'adresse e-mail, le nom et le pays de facturation du client ainsi que la langue de la boutique sont transmis à Adyen, et le paiement apparaît sous la forme Cart # suivie du numéro du panier. Aucune commande n'existe encore à ce stade.
Après le paiement, le client revient dans votre boutique. Ce retour ne crée ni ne paie aucune commande : la commande n'est marquée payée qu'après confirmation par Adyen au moyen du webhook AUTHORISATION signé, et à condition que le montant et la devise correspondent au panier. Si le webhook est déjà arrivé, le client voit la page standard de confirmation de commande avec Your payment with Adyen has been received. (ou Your payment with Adyen has been received and is being reviewed by the store. pour une commande mise en attente). Si Adyen a annulé le paiement avant cela, la page affiche Your Adyen payment was not completed. Please contact us about this order. Si le webhook n'est pas encore arrivé, une page Payment confirmation affiche Your payment is being confirmed by Adyen. Your order will be created as soon as Adyen confirms the payment, and you will receive an e-mail. avec les boutons Check again et Back to checkout, destinés au client qui n'a pas terminé son paiement.
Si le paiement est refusé, aucune commande n'est créée et le client peut réessayer. Lorsque le client lance un nouveau paiement pour le même panier, le lien de paiement précédent expire et ne peut plus être payé. Si le panier a déjà une commande, le client est dirigé vers la confirmation de cette commande au lieu d'un nouveau paiement.
Si le lien de paiement ne peut pas être créé, le client reste dans le tunnel de commande avec Payment could not be initiated. Please try again or choose another payment method. La raison est écrite dans le journal. Si les réglages sont incomplets, le message est Payment gateway is not configured properly. Please contact the store administrator.
Les développeurs peuvent modifier la requête de lien de paiement avec le hook actionAdygPaymentLinkRequest.
Le module ne gère ni abonnements ni paiements récurrents, ni cartes enregistrées, ni champs de carte sur le site (Drop-in ou Components), ni boutons de capture ou d'annulation dans PrestaShop, ni authentification de base pour les webhooks.
Commandes et remboursements
Statuts de commande
No order yet: le client a été envoyé vers Adyen et n'a pas payé, le paiement a été refusé ou Adyen n'a pas encore confirmé le paiement. Seul le panier existe.
Payment accepted, Delivered or Adyen payment on hold: le paiement a été autorisé. Le statut suit Order status after payment. Le paiement est enregistré avec la référence PSP Adyen comme identifiant de transaction, et une note indique le montant, la référence PSP et le moyen de paiement.
Adyen payment on hold after payment: Adyen a confirmé un montant ou une devise différents du total du panier (par exemple, le panier a été modifié après le début du paiement), une capture a échoué, ou le paiement est arrivé après l'annulation de la commande. La note l'explique. Vérifiez le paiement dans l'espace client, puis traitez la commande ou remboursez le paiement.
Canceled: le paiement de cette commande a été annulé dans Adyen.
Refunded: le paiement a été entièrement remboursé via le module.
Si un second paiement réussi arrive pour une commande déjà payée, par exemple depuis un ancien lien de paiement, la commande n'est pas modifiée. Une note vous demande de vérifier dans l'espace client s'il s'agit d'un double débit et de le rembourser depuis cet espace si nécessaire.
Bloc de paiement Adyen
La page de commande affiche un bloc Adyen payment avec la référence PSP, le lien de paiement, le compte marchand et l'environnement, le statut du paiement, le montant payé et remboursé, un badge Test mode pour les paiements de test, l'historique des remboursements et les Adyen notes : les notes que le module ajoute à la commande (paiement autorisé, écart de montant, paiement en double, capture, annulation, résultats des remboursements), les plus récentes en premier. Ces notes sont des messages privés de la commande ; PrestaShop 8.2 et 9 ne les affichent nulle part ailleurs sur la page de commande.
Remboursements
Dans le bloc Adyen payment, saisissez le montant (le montant non encore remboursé est prérempli), facultativement un motif, puis cliquez sur Refund via Adyen. Confirmez la question Refund this amount through Adyen? This cannot be undone. Les remboursements totaux et partiels sont pris en charge. Vous devez disposer du droit de modifier les commandes. Les remboursements sont effectués au montant et dans la devise qu'Adyen a autorisés ; ainsi, après un écart de montant ou de devise, vous pouvez rembourser jusqu'au montant réellement payé par le client, et non le total de la commande. Le remboursement est envoyé à l'environnement et au compte marchand avec lesquels le paiement a été effectué ; la clé API de cet environnement doit donc être configurée. Si Adyen n'accepte pas la demande, le bloc affiche l'erreur et aucun remboursement n'est enregistré.
Adyen traite les remboursements de manière asynchrone : la demande est ajoutée à l'historique des remboursements et aux notes avec le statut received, et le résultat final arrive par le webhook REFUND ou REFUND_FAILED. Un remboursement échoué ne compte plus comme remboursé. Lorsque les remboursements envoyés atteignent le montant payé, la commande passe en Refunded. Un remboursement partiel ne modifie pas le statut. Avec une capture manuelle dans Adyen, seuls les paiements capturés peuvent être remboursés.
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 Adyen. Les remboursements effectués dans l'espace client d'Adyen arrivent par webhook et sont ajoutés aux notes. Le statut de la commande et les avoirs ne sont pas modifiés automatiquement.
Clé de licence
Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Adyen Gateway est le premier bloc de Modules > Module Manager > VibeFox Adyen 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-adyen 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 : 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 cet emplacement dans votre compte vibefox.net.
Sans clé active, Adyen n'est pas affiché aux clients dans le tunnel de commande. Si un paiement est tout de même lancé, le client voit This payment method is not available. Please choose another one. La vitrine PrestaShop ne sait pas que vous êtes connecté au back-office : le moyen de paiement est donc masqué pour vous aussi. Vous pouvez configurer le module avant d'acheter une clé, mais pas le tester dans le tunnel de commande. Un rappel apparaît dans Modules > Module Manager, sur l'onglet Alerts. Les commandes existantes ne sont pas affectées : les paiements déjà lancés sont toujours confirmés, et les 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é à 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
Adyen n'apparaît pas dans le tunnel de commande : vérifiez que la licence est active, que Enable/Disable est activé et que les réglages du mode en cours sont complets : Merchant account, la clé API et la clé HMAC de ce mode et, en mode production, Live URL prefix. La page des réglages indique ce qui 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.
Le paiement a abouti, mais aucune commande n'a été créée : le webhook ne fonctionne pas. Dans l'espace client de l'environnement utilisé (test ou production), vérifiez que le webhook Standard existe, que son URL est exactement celle affichée dans Webhook URL et que la méthode est JSON. Vérifiez que la clé HMAC de ce webhook se trouve dans le champ correspondant (Test HMAC key ou Live HMAC key). Avec une clé HMAC invalide ou absente, le module répond HTTP 401 et Adyen renouvelle l'envoi plus tard ; la commande est donc créée automatiquement dès que la clé est corrigée. Le journal affiche Webhook rejected: invalid HMAC signature ou indique que la clé HMAC n'est pas configurée.
Le webhook répond [rejected] HMAC key not configured : la clé HMAC de l'environnement de la notification est vide. Collez-la dans les réglages.
Le webhook répond [rejected] busy, retry later : le panier était en cours de traitement par un autre envoi au même moment, ou la commande n'a pas pu être créée (par exemple, parce que le module est désactivé). Adyen renouvelle automatiquement le webhook. La raison figure dans le journal.
L'URL du webhook affiche [rejected] POST required in the browser : c'est normal. L'URL n'accepte que les notifications d'Adyen.
L'avertissement sur la clé HMAC à l'enregistrement : le champ doit contenir la clé HMAC hexadécimale de l'espace client. La valeur précédente a été conservée.
Le client voit Payment could not be initiated : consultez le champ Log de la page du module (les erreurs sont toujours journalisées). Vérifiez la clé API, le compte marchand et, en mode production, le préfixe d'URL de production.
La commande est Adyen payment on hold après le paiement : lisez la note de la commande. Le montant ou la devise confirmés par Adyen ne correspondaient pas au panier, une capture a échoué, ou le paiement est arrivé après une annulation. Cela peut aussi venir du réglage Order status after payment.
Le remboursement échoue : la commande doit avoir une référence PSP Adyen, qui arrive avec le webhook AUTHORISATION. Les identifiants de l'environnement dans lequel le paiement a été effectué doivent être configurés ; sinon, le bloc indique que les identifiants ne sont pas configurés. Avec une capture manuelle, seuls les paiements capturés peuvent être remboursés.
Désinstallation
Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox Adyen 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 du module, les enregistrements de paiements Adyen (références PSP, événements de webhook, remboursements) et les journaux sont supprimés. S'il est désactivé, tous ces éléments sont conservés en vue d'une réinstallation ultérieure, de sorte que les commandes payées auparavant peuvent encore être remboursées. Le statut de commande Adyen payment on hold reste toujours en place. Les commandes existantes conservent leurs notes de paiement et leurs identifiants de transaction.
Adyen est une marque commerciale de son propriétaire respectif. Ce module n'est ni affilié à Adyen ni approuvé par Adyen.