VibeFox Nexi XPay for WooCommerce — Aide
Prérequis
WordPress : 6.0 ou ultérieur.
WooCommerce : 7.0 ou ultérieur, installé et activé.
PHP : 8.0 ou ultérieur.
Devise : la devise de la boutique ou de la commande doit être EUR. Pour les autres devises, le moyen de paiement est masqué au moment du paiement.
Compte Nexi XPay : il vous faut un compte marchand Nexi XPay (intégration par redirection « Pagamento Semplice ») avec l'alias (identifiant de terminal) et la clé MAC de votre terminal. Les identifiants de test et de production sont distincts : ceux de test proviennent de l'espace de test de Nexi XPay ou du portail développeurs (developer.nexi.it), ceux de production de votre back-office Nexi XPay une fois le compte marchand activé. Rien n'est à configurer dans le back-office Nexi : l'adresse de notification est transmise à chaque paiement.
Site public : l'URL de notification doit être accessible depuis Internet, sans mode maintenance, authentification de base ni règle de pare-feu bloquant Nexi. Sinon, le paiement est tout de même confirmé par le retour signé du client.
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 du plugin et cliquez sur Install Now. Vous pouvez aussi envoyer le dossier wcp_nexi_gateway dans /wp-content/plugins/ par FTP.
2. Cliquez sur Activate.
3. Ouvrez les réglages : WooCommerce > Settings > Payments > Nexi XPay > Manage, ou cliquez sur Settings sous le nom du plugin sur la page Plugins.
4. Saisissez votre clé de licence VibeFox dans le bloc de licence en haut de la page et cliquez sur Activate.
5. Gardez Test Mode activé et saisissez l'alias et la clé MAC de test (voir Configuration).
6. Activez Enable/Disable et passez une commande de test. Quand tout fonctionne, saisissez l'alias et la clé MAC de production et décochez Test Mode.
Configuration
Tous les réglages se trouvent sur une seule page : WooCommerce > Settings > Payments > Nexi XPay. Au-dessus des champs, la page affiche Le mode test est activé : les paiements sont envoyés à l'environnement de test de Nexi XPay, aucun argent réel n'est débité. tant que le mode test est activé, et vous alerte lorsque la passerelle est activée mais que l'alias ou la clé MAC du mode en cours est vide, ou lorsque la devise de la boutique n'est pas EUR. Dans les deux cas, le moyen de paiement est masqué au moment du paiement. Les espaces et sauts de ligne autour des clés collées sont supprimés à l'enregistrement.
Général
Enable/Disable : Enable Nexi XPay Gateway active ou désactive le moyen de paiement. Par défaut : désactivé.
Title : le titre du moyen de paiement affiché au client au moment du paiement. Par défaut : Credit Card (Nexi). En mode test, la page de paiement ajoute (TEST MODE) au titre.
Description : la description du moyen de paiement affichée au client au moment du paiement. Par défaut : Pay securely with your credit card via Nexi XPay.
Environnement de test
Les paiements de test sont envoyés à int-ecommerce.nexi.it et ne débitent jamais de vraies cartes. Obtenez l'alias et la clé MAC de test dans l'espace de test de Nexi XPay ou sur le portail développeurs (developer.nexi.it).
Test Mode : Enable test mode utilise l'environnement de test de Nexi XPay et les identifiants de test. Décochez-le pour encaisser de vrais paiements avec les identifiants de production. Par défaut : activé.
Test Alias : l'alias (identifiant de terminal) de votre terminal de test Nexi XPay.
Test MAC Key : la clé de calcul MAC de votre terminal de test Nexi XPay.
Environnement de production
L'alias et la clé MAC de production sont affichés dans votre back-office Nexi XPay (ecommerce.nexi.it) une fois votre compte marchand activé.
Live Alias : l'alias (identifiant de terminal) de votre terminal de production Nexi XPay.
Live MAC Key : la clé de calcul MAC de votre terminal de production Nexi XPay.
Paiement
L'URL de notification est transmise à Nexi à chaque paiement : il n'y a donc rien à configurer dans le back-office. La section l'affiche ; elle ressemble à https://your-site/wp-json/wc-nexi-gateway/v1/s2s/{order_id}, avec le numéro de commande à la fin. Nexi envoie le résultat du paiement à cette URL de serveur à serveur et le transmet aussi avec le retour du client. Les deux sont signés de la même manière et vérifiés avec la clé MAC de l'environnement dans lequel le paiement a été effectué, l'alias de cet environnement et le code de transaction émis pour cette commande. Les résultats qui échouent à la vérification sont rejetés et ne modifient rien.
Capture : moment où l'argent est encaissé.
Order Status After Payment : le statut de la commande après un paiement réussi. Le statut est défini immédiatement, avec un seul changement de statut et un seul e-mail.
Avancé
Debug Log : Enable logging consigne les événements de paiement dans WooCommerce > Status > Logs, source wcp_nexi_gateway. Les clés MAC, les données de carte et les adresses e-mail ne sont pas consignées. Les erreurs et avertissements, par exemple un échec de vérification MAC, sont toujours consignés, même lorsque l'option est désactivée. Par défaut : désactivé.
Delete Data on Uninstall : Remove all plugin settings and logs when uninstalled. Par défaut : désactivé.
Paiement
Le client choisit le moyen de paiement (par défaut Credit Card (Nexi)) et passe la commande. La page suivante affiche Redirection vers Nexi XPay pour le paiement... et envoie automatiquement le client vers la page Nexi XPay, avec un bouton Pay Now en secours. Le paiement est envoyé en EUR avec un nouveau code de transaction, l'e-mail du client et la description Order, le numéro de commande et le nom de votre site. La page Nexi s'ouvre dans la langue de la boutique si elle est en italien, anglais, espagnol, français, allemand, japonais, chinois, arabe, russe ou portugais, sinon en anglais.
Le client paie puis revient sur la page de confirmation de commande de votre boutique. La commande n'est marquée comme payée qu'après un résultat Nexi vérifié, avec le montant et la devise exacts de la commande : que ce soit par la notification serveur à serveur ou par le retour signé du client, selon celui qui arrive en premier.
Si le paiement est refusé ou si le client annule sur la page Nexi, il revient au paiement (ou à la page Pay for order si le panier est vide) et voit l'un de ces messages : Le paiement n'a pas été finalisé. Veuillez réessayer ou choisir un autre moyen de paiement., Le paiement a été annulé. Veuillez réessayer. ou Nous n'avons pas pu confirmer le paiement. Si votre carte a été débitée, veuillez nous contacter avant de payer à nouveau. Annuler sur la page Nexi laisse la commande inchangée, le client peut donc payer à nouveau.
Si le plugin n'est pas configuré pour le mode en cours, le client voit Ce moyen de paiement n'est pas disponible pour le moment. Veuillez choisir un autre moyen de paiement.
Le moyen de paiement fonctionne sur le paiement classique, sur le bloc Paiement et sur la page Pay for order. Il est compatible avec WooCommerce High-Performance Order Storage (HPOS).
Le plugin n'accepte les paiements que sur la page Nexi XPay. Il n'offre pas de remboursement depuis WooCommerce, ni de cartes enregistrées ou OneClick, ni d'abonnements ou de paiements récurrents, ni de Pay-By-Link, ni de champs XPay Build intégrés, ni de moyens de paiement sélectionnés dans WooCommerce : la page Nexi affiche les moyens activés sur votre terminal.
Commandes et remboursements
Statuts de commande
En attente de paiement : le client a été envoyé vers Nexi et n'a pas encore payé, ou a annulé sur la page Nexi.
En cours, Terminée ou En attente : Nexi a confirmé le paiement. Le statut suit Order Status After Payment. La note de commande indique le code d'autorisation, le code de transaction, la marque de la carte et le message de Nexi. L'ID de transaction est le code de transaction Nexi.
En attente (autorisée) : la capture différée est sélectionnée et le paiement n'est qu'autorisé. Capturez-le avec l'action de commande Capture Nexi XPay payment.
En attente (paiement en cours de confirmation) : Nexi a signalé le paiement comme en attente de confirmation. La commande est mise à jour par le résultat final.
En attente après paiement : le montant ou la devise reçus de Nexi ne correspondaient pas à la commande (la commande n'est pas marquée comme payée), ou un paiement réussi est arrivé pour une commande déjà annulée. La note de commande l'explique. Vérifiez le paiement dans le back-office Nexi XPay et traitez ou remboursez la commande.
Échec : la dernière tentative de paiement a été refusée, annulée ou s'est terminée par une erreur. Le client peut payer à nouveau.
Une commande payée n'est jamais rétrogradée par un échec ultérieur. Si un autre paiement réussi arrive pour une commande déjà payée, une note vous demande de le rembourser dans le back-office Nexi XPay s'il s'agit d'un doublon.
Capture différée
Pour une commande autorisée en attente, ouvrez la commande, choisissez Capture Nexi XPay payment dans les actions de commande et cliquez sur la flèche. Le plugin capture le montant autorisé dans l'environnement du paiement et marque la commande comme payée avec le statut défini dans Order Status After Payment. Si la capture échoue, l'erreur s'affiche sur l'écran de la commande et est ajoutée aux notes de commande, et la commande reste en attente.
Remboursements
Les remboursements ne se font pas depuis WooCommerce, il n'y a donc pas de bouton Refund via. Effectuez le remboursement dans le back-office Nexi XPay, puis enregistrez-le manuellement dans WooCommerce.
Clé de licence
Le plugin fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence se trouve en haut de WooCommerce > Settings > Payments > Nexi XPay. 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 l'emplacement dans votre compte vibefox.net.
Sans clé active, Nexi XPay n'est pas affiché aux clients au moment du paiement. Si un paiement est tout de même lancé, le client voit Ce moyen de paiement n'est pas disponible. Veuillez en choisir un autre. Les gestionnaires de la boutique connectés voient toujours le moyen de paiement, marqué (unlicensed — visible to admins only), afin de pouvoir configurer et tester le plugin avant d'acheter une clé. Un rappel apparaît sur la page Plugins 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 paiements différés peuvent toujours être capturés.
Lorsqu'une licence expire, le plugin continue de fonctionner, mais les mises à jour et le support nécessitent un renouvellement. Le statut est vérifié à nouveau automatiquement en arrière-plan.
Dépannage
Nexi XPay n'apparaît pas au paiement : vérifiez que la licence est active, que Enable/Disable est activé, que le mode en cours dispose des deux identifiants (Test Alias et Test MAC Key en mode test, Live Alias et Live MAC Key en mode production) et que la devise de la boutique ou de la commande est EUR. La page des réglages affiche un avertissement dans ces cas.
Le paiement a abouti, mais la commande reste en attente de paiement : ni la notification ni le retour du client n'ont été acceptés. Vérifiez que la boutique est accessible depuis Internet, que la clé MAC et l'alias correspondent à l'environnement (test ou production) du paiement, et activez Debug Log pour voir ce que Nexi a envoyé dans WooCommerce > Status > Logs, source wcp_nexi_gateway.
La notification répond invalid_mac ou invalid_alias : la clé MAC ou l'alias dans les réglages ne correspondent pas au terminal qui a envoyé le résultat. Recopiez-les depuis l'espace de test ou le back-office Nexi.
La notification répond unknown_transaction : le code de transaction n'a pas été émis par cette boutique pour cette commande. Le résultat est ignoré.
La notification répond not_configured ou busy : l'alias ou la clé MAC de l'environnement du paiement est vide, ou une autre requête était en train de mettre à jour la commande au même moment. Nexi relance la notification.
La commande est en attente après paiement : lisez la note de commande. La capture différée est sélectionnée (capturez le paiement avec l'action de commande), le montant ou la devise ne correspondaient pas, un paiement est arrivé pour une commande annulée, le paiement est en attente chez Nexi, ou En attente est sélectionné comme statut après paiement.
Capture Nexi XPay payment est absent ou échoue : l'action n'apparaît que pour les commandes Nexi en attente comme autorisées avec capture différée. En cas d'échec, lisez l'erreur dans les notes de commande ; la capture utilise les clés de l'environnement dans lequel le paiement a été effectué.
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, le plugin continue de fonctionner avec le dernier statut connu.
Désinstallation
Désactiver le plugin conserve toutes les données. Pour le supprimer, désactivez-le puis supprimez-le sur la page Plugins. La clé de licence et le statut de licence de ce plugin sont toujours supprimés. Les réglages de la passerelle et les journaux ne sont supprimés que si Delete Data on Uninstall était activé. Sinon, ils sont conservés pour une réinstallation ultérieure. Les commandes existantes conservent leurs notes de paiement et leurs ID de transaction.
Nexi et XPay sont des marques de leurs détenteurs respectifs. Ce plugin n'est ni affilié à Nexi ni approuvé par Nexi.