VibeFox Adyen for WooCommerce — Aide

Prérequis

WordPress: 6.0 ou ultérieur.

WooCommerce: 7.0 ou ultérieur, installé et activé. L'extension refuse de s'activer sans lui.

PHP: 8.0 ou ultérieur.

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 (API credential) doté 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 Customer Area de test est ca-test.adyen.com, celui de production ca-live.adyen.com. Les clés de test et de production sont distinctes.

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_adyen_gateway dans /wp-content/plugins/ par FTP.

2. Cliquez sur Activate.

3. Ouvrez les réglages : WooCommerce > Settings > Payments > Adyen > 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. Saisissez le nom de 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.

6. Dans l'espace Customer Area (test et production), ajoutez un webhook Standard avec l'URL affichée dans les réglages de l'extension (voir Configuration).

7. Activez Enable/Disable. Testez un paiement avec Test mode activé, puis décochez-le.

Configuration

Tous les réglages se trouvent sur une seule page : WooCommerce > Settings > Payments > Adyen. 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 liste ce qui manque : Merchant account, la clé API, la clé HMAC et, en mode production, Live URL prefix. À l'enregistrement, une clé HMAC qui n'est pas hexadécimale et un préfixe d'URL de production contenant d'autres caractères que des lettres, des chiffres et des tirets sont refusés avec une erreur, et la valeur précédente est conservée.

Général

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 que voit le client au paiement. Par défaut : Adyen.

Description: le texte affiché sous le moyen de paiement au paiement. Par défaut : Pay securely via Adyen.

Compte Adyen

Les clés API se créent dans l'espace Customer Area d'Adyen, sous Developers > API credentials. Renseignez les deux jeux de clés ; le réglage Test mode détermine celui qui est utilisé.

Test mode: Use the Adyen test environment (no real money). Lorsqu'il est activé, les liens de paiement et les remboursements sont envoyés à checkout-test.adyen.com avec la clé API de test. Par défaut : activé. Décochez-le pour recevoir de vrais paiements.

Merchant account: le nom de votre compte marchand Adyen (et non celui de la société), par exemple MyShopECOM. Il est généralement identique dans les espaces Customer Area de test et de production.

Identifiants de test

Utilisés lorsque Test mode est activé.

Test API key: depuis l'espace Customer Area de test : Developers > API credentials > votre identifiant > API key.

Test HMAC key: depuis l'espace Customer Area de test : Developers > Webhooks > votre webhook Standard > HMAC key (hexadécimal). 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 Customer Area de production : Developers > API credentials > votre identifiant > API key.

Live HMAC key: depuis l'espace Customer Area de production : Developers > Webhooks > votre webhook Standard > HMAC key (hexadécimal).

Live URL prefix: depuis l'espace Customer Area de production : Developers > API URLs, par exemple 1797a841fbb37ca7-AdyenDemo pour https://1797a841fbb37ca7-AdyenDemo-checkout-live.adyenpayments.com. Vous pouvez coller l'URL complète : le préfixe en est extrait à l'enregistrement.

Webhook

Les commandes ne sont marquées payées que par les webhooks Adyen. Dans l'espace Customer Area (test et production), allez dans Developers > Webhooks et ajoutez un Standard webhook avec l'URL affichée dans cette section des réglages. Elle ressemble à https://your-site/wc-api/adyg_adyen_webhook/. Choisissez la méthode 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 utilisée. Les webhooks sans signature valide sont rejetés, et Adyen les renvoie plus tard. Sans webhook, les commandes restent en « En attente de paiement ».

L'extension traite ces événements :

Les autres événements sont ajoutés aux notes de commande. Les notifications qui ne concernent pas une commande de cette boutique, par exemple le bouton de test de l'espace Customer Area, sont acceptées et ignorées.

Avancé

Order status after payment: le statut de commande défini après un paiement réussi, en un seul changement de statut.

Debug log: Log API calls and webhook events écrit dans WooCommerce > Status > Logs, source wcp_adyen_gateway. Les erreurs sont toujours journalisées. Les journaux ne contiennent jamais de clés API ou HMAC, ni de données personnelles des acheteurs. Par défaut : désactivé.

Delete data on uninstall: Delete the plugin settings and Adyen order meta (PSP references) when the plugin is deleted. Par défaut : désactivé.

Paiement

Le client choisit le moyen de paiement (par défaut Adyen) et passe sa commande. L'extension crée un lien de paiement Adyen pour le total de la commande dans la devise de la commande et envoie le client vers la page de paiement Adyen. Il y paie avec n'importe quel moyen activé dans votre compte Adyen. L'e-mail de facturation, le nom et le pays du client ainsi que la langue de la boutique sont transmis à Adyen, et le paiement apparaît sous le libellé Order # suivi du numéro de commande.

Après le paiement, le client revient sur la page de confirmation de commande de votre boutique. Ce retour ne marque pas la commande comme payée : la commande n'est marquée payée qu'après confirmation d'Adyen par le webhook AUTHORISATION signé, et lorsque le montant et la devise correspondent à la commande.

Si le paiement est refusé, la commande passe à « Échec » et le client peut réessayer. Lorsque le client lance un nouveau paiement pour la même commande, par exemple depuis la page Pay for order, le lien de paiement précédent expire et ne peut donc plus être payé.

Si le lien de paiement ne peut pas être créé, le client voit Payment could not be initiated. Please try again or choose another payment method. La raison est ajoutée aux notes de commande. Si les réglages sont incomplets, le client voit Payment gateway is not configured properly. Please contact the store administrator.

Pour les devises sans décimales, comme JPY, KRW, IDR ou VND, réglez WooCommerce > Settings > General > Number of decimals sur 0. Sinon, le total est arrondi à l'unité entière.

Le moyen de paiement fonctionne avec le paiement classique et avec le bloc Paiement. Il est compatible avec WooCommerce High-Performance Order Storage (HPOS).

L'extension 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 WooCommerce, ni authentification de base pour les webhooks.

Commandes et remboursements

Statuts de commande

Pending payment: le lien de paiement a été créé et Adyen n'a pas encore confirmé le paiement. La note de commande indique le lien de paiement, le montant et l'environnement.

Processing, Completed or On Hold: le paiement a été autorisé. Le statut suit le réglage Order status after payment. La note de commande indique le montant, la référence PSP et le moyen de paiement. L'identifiant de transaction est la référence PSP Adyen.

On hold after payment: Adyen a confirmé un montant ou une devise différent du total de la commande. La note de commande indique les deux valeurs, et la commande n'est pas marquée comme payée. Une commande payée est aussi mise en attente lorsqu'une capture échoue, car l'argent n'a pas été encaissé. Vérifiez le paiement dans l'espace Customer Area.

Failed: le paiement a été refusé. Les commandes payées, en attente et annulées ne sont pas modifiées par un paiement refusé.

Cancelled: le paiement de cette commande a été annulé dans Adyen.

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 à nouveau. Une note vous invite à vérifier dans l'espace Customer Area qu'il ne s'agit pas d'un double débit, et à le rembourser depuis cet espace si nécessaire.

Remboursements

Ouvrez la commande, cliquez sur Refund, saisissez le montant et cliquez sur Refund via Adyen. Les remboursements totaux et partiels sont pris en charge. 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 renseignée. Adyen traite les remboursements de façon asynchrone : la demande est notée sur la commande, et le résultat final est ajouté comme note de commande par le webhook REFUND ou REFUND_FAILED. Si Adyen n'accepte pas la demande, WooCommerce affiche l'erreur et aucun remboursement n'est enregistré. Avec une capture manuelle dans Adyen, seuls les paiements capturés peuvent être remboursés.

Les remboursements effectués dans l'espace Customer Area d'Adyen arrivent par webhook et sont ajoutés aux notes de commande. Ils ne sont pas enregistrés automatiquement comme remboursements WooCommerce.

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 > Adyen. 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, Adyen 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 paiements déjà lancés sont toujours confirmés, et les 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

Adyen n'apparaît pas au paiement : 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 liste ce qui manque.

Le paiement a été effectué, mais la commande reste « En attente de paiement » : le webhook ne fonctionne pas. Dans l'espace Customer Area de l'environnement utilisé (test ou production), vérifiez que le webhook Standard existe, que son URL est exactement celle affichée dans les réglages et que la méthode est JSON. Vérifiez que la clé HMAC de ce webhook est dans le champ correspondant (Test HMAC key ou Live HMAC key). Avec une clé HMAC invalide ou absente, l'extension répond HTTP 401 et Adyen renvoie la notification plus tard ; la commande est donc mise à jour automatiquement une fois la clé 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 « busy, retry later » : la commande était déjà en cours de traitement par une autre notification au même moment. Adyen renvoie automatiquement le webhook.

Erreur de clé HMAC à l'enregistrement : le champ doit contenir la clé HMAC hexadécimale de l'espace Customer Area. La valeur précédente a été conservée.

Le client voit « Payment could not be initiated » : ouvrez les notes de commande ou activez Debug log et consultez WooCommerce > Status > Logs, source wcp_adyen_gateway. Vérifiez la clé API, le compte marchand et, en mode production, le préfixe d'URL de production.

La commande est « En attente » après le paiement : lisez la note de commande. Le montant ou la devise confirmés par Adyen ne correspondaient pas à la commande, ou une capture a échoué. Cela peut aussi venir de votre 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 renseignés. Avec une capture manuelle, seuls les paiements capturés peuvent être remboursés.

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 données Adyen enregistrées sur les commandes (références PSP, liens de paiement, événements traités) ne sont supprimés que si Delete data on uninstall était activé. Sinon, elles sont conservées pour une future réinstallation. Les commandes existantes conservent leurs notes de paiement et leurs identifiants de transaction.

Adyen est une marque de son propriétaire respectif. Cette extension n'est ni affiliée à Adyen ni approuvée par Adyen.