VibeFox Nexi XPay for PrestaShop — Aide
Prérequis
PrestaShop : 8.0 à 9.x.
PHP : 8.0 ou ultérieur. Le module refuse de s'installer sur les anciennes versions de PHP.
Devise : la devise du panier doit être l'EUR. Pour les autres devises, le moyen de paiement est masqué à la commande.
Compte Nexi XPay : vous avez besoin d'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 les identifiants réels sont distincts : les identifiants de test proviennent de l'espace de test de Nexi XPay ou du portail développeurs (developer.nexi.it), les identifiants réels 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 avec chaque paiement.
Site public : l'URL de notification doit être accessible depuis Internet, sans authentification de base ni règle de pare-feu bloquant Nexi. Le mode maintenance de la boutique ne la bloque pas. Si la notification ne peut pas atteindre la boutique, 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 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 Nexi XPay 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. Laissez Test Mode activé et saisissez l'alias et la clé MAC de test (voir Configuration).
5. Activez Enable/Disable, cliquez sur Save et passez une commande de test. Lorsque tout fonctionne, saisissez l'alias et la clé MAC réels, puis désactivez Test Mode.
À l'installation, le module crée deux statuts de commande : Awaiting Nexi XPay payment et Nexi XPay payment on hold. PrestaShop propose un nouveau module de paiement pour toutes les devises, tous les pays et tous les groupes de clients. Vous pouvez les restreindre dans Payment > Preferences. Un pays activé dans la boutique après l'installation du module doit aussi y être coché.
Configuration
Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox Nexi XPay Gateway > Configure. Chaque section a son propre bouton Save, qui enregistre toute la page. Au-dessus des champs, la page affiche Test mode is on: payments go to the Nexi XPay test environment, no real money is charged. tant que le mode test est activé. Elle vous avertit lorsque la passerelle est activée mais que l'alias ou la clé MAC du mode actuel est vide, ou lorsque la devise par défaut de la boutique n'est pas l'EUR. Dans ces cas, le moyen de paiement est masqué à la commande. Les espaces et sauts de ligne entourant les valeurs collées sont supprimés à l'enregistrement.
Nexi XPay
Enable/Disable : Enable Nexi XPay Gateway active ou désactive le moyen de paiement. Par défaut : off.
Title : le titre du moyen de paiement affiché au client lors de la commande. C'est aussi le nom du moyen de paiement enregistré dans la commande. Par défaut : Credit Card (Nexi). En mode test, le processus de commande et la commande ajoutent (TEST MODE) au titre.
Description : la description du moyen de paiement affichée au client lors de la commande. Par défaut : Pay securely with your credit card via Nexi XPay.
Environnement de test
Les paiements de test partent vers 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 : utilise l'environnement de test de Nexi XPay et les identifiants de test. Désactivez-le pour encaisser de vrais paiements avec les identifiants réels. Par défaut : on.
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 réel
L'alias et la clé MAC réels 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 Nexi XPay réel.
Live MAC Key : la clé de calcul MAC de votre terminal Nexi XPay réel.
Les clés MAC 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.
Supprimer les secrets enregistrés : cochez Test MAC Key ou Live MAC Key, puis cliquez sur Save pour supprimer une clé enregistrée. Un champ vide conserve la valeur enregistrée.
Paiement
Notification URL : affichée à titre indicatif. Elle est transmise à Nexi avec chaque paiement, donc rien n'est à configurer dans le back-office Nexi. Avec les URL conviviales, elle ressemble à https://your-shop/module/wcp_nexi_gateway/s2s?id_cart={id_cart}, éventuellement avec un code de langue tel que /it/, et avec le numéro du panier à 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 sont 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 ce panier. Les résultats qui ne passent pas la vérification sont rejetés et ne modifient rien.
Capture : moment où l'argent est prélevé.
Order Status After Payment : le statut de la commande après un paiement réussi.
Avancé
Debug Log : consigne les événements de paiement dans logs/nexi_ip_debug.log.php dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les clés MAC, les MAC, les données de carte et les adresses e-mail ne sont pas consignés. 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 : off.
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 tous ses réglages et le journal. Les données de paiement Nexi XPay des commandes et les statuts de commande sont conservés. Par défaut : off.
Processus de commande
À l'étape de paiement, le client choisit le moyen de paiement (par défaut Credit Card (Nexi)) et confirme. La page suivante affiche Redirecting to Nexi XPay for payment... et envoie automatiquement le client sur la page de Nexi XPay, avec un bouton Pay Now en solution de secours. Le paiement est envoyé en EUR pour le total du panier, avec un nouveau code de transaction, l'e-mail du client, la description Cart, le numéro du panier et le nom de votre boutique. La page Nexi s'ouvre dans la langue du panier si celle-ci est l'italien, l'anglais, l'espagnol, le français, l'allemand, le japonais, le chinois, l'arabe, le russe ou le portugais ; sinon, elle s'ouvre en anglais. Aucune commande n'existe encore à ce stade.
Le client paie et revient sur 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 du panier : issu de la notification serveur à serveur ou du retour signé du client, selon celui qui arrive en premier. La commande est alors créée et le client voit la page standard de confirmation de commande avec Your Nexi XPay payment has been received. Si Nexi signale le paiement comme en attente, la page affiche Your payment is pending confirmation from Nexi XPay. We will update your order as soon as the payment is confirmed. Pour une commande en attente (capture différée ou vérification manuelle), elle affiche We have received your Nexi XPay payment authorization. Your order will be processed shortly. Si un paiement en attente échoue par la suite, la page affiche The payment was not completed. Please contact us.
Si le résultat n'a pas encore été traité au retour du client, une page affiche We have not received the payment confirmation from Nexi XPay yet. If you completed the payment, your order will be updated shortly. avec un bouton Check again. La notification crée la commande dès son arrivée.
Si le paiement est refusé, ou si le client annule sur la page Nexi, il revient à la commande et voit l'un de ces messages : The payment was not completed. Please try again or choose a different payment method., Payment was cancelled. Please try again. ou We could not confirm the payment. If your card was charged, please contact us before paying again. Aucune commande n'est créée et le panier est conservé, afin que le client puisse payer à nouveau. Si le panier a déjà une commande (par exemple s'il a été payé dans un autre onglet), le client accède à la confirmation de commande au lieu d'un nouveau paiement.
Si le module n'est pas configuré pour le mode actuel, le client voit This payment method is not available right now. Please choose another payment method.
La notification fonctionne lorsque la boutique est en mode maintenance et n'est pas bloquée par la restriction géographique de votre boutique.
Le module n'accepte les paiements que sur la page Nexi XPay. Il ne gère ni remboursements depuis PrestaShop, ni cartes enregistrées ou OneClick, ni abonnements ou paiements récurrents, ni Pay-By-Link, ni champs intégrés XPay Build, ni moyens de paiement sélectionnés dans PrestaShop : la page Nexi affiche les moyens activés sur votre terminal.
Commandes et remboursements
Statuts de commande
Pas encore de commande : le client a été envoyé vers Nexi et n'a pas payé, a annulé ou a été refusé, ou Nexi n'a pas encore confirmé le paiement. Seul le panier existe.
Payment accepted, Delivered or Nexi XPay payment on hold : Nexi a confirmé le paiement. Le statut suit Order Status After Payment. Le paiement est enregistré avec le code de transaction Nexi comme ID de transaction, et une note indique le code d'autorisation, le code de transaction, la marque de carte et le message de Nexi.
Nexi XPay payment on hold (authorized) : la capture différée est sélectionnée et le paiement n'est qu'autorisé. Capturez-le avec Capture Nexi XPay payment sur la page de la commande.
Awaiting Nexi XPay payment : Nexi a signalé le paiement comme en attente de confirmation. La commande est mise à jour par le résultat final.
Nexi XPay payment on hold after payment : le montant ou la devise reçus de Nexi ne correspondaient pas au panier (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 l'explique. Vérifiez le paiement dans le back-office Nexi XPay, puis traitez ou remboursez la commande.
Erreur de paiement : un paiement en attente a échoué. Le même panier ne peut pas être payé à nouveau : le client doit passer une nouvelle commande.
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 invite à le rembourser dans le back-office Nexi XPay s'il s'agit d'un doublon.
Bloc de paiement Nexi XPay
La page de la commande affiche un bloc Nexi XPay payment avec le code de transaction (codTrans), le statut et le résultat Nexi, le mode de capture, le montant envoyé à Nexi et le montant reçu, le code d'autorisation, la marque de carte, le message de Nexi et la date, un badge Test environment pour les paiements de test, ainsi que les Nexi XPay notes de la commande.
Capture différée
Pour une commande autorisée en attente, cliquez sur Capture Nexi XPay payment dans le bloc (le bouton affiche le montant) et confirmez la question Capture the authorized amount through Nexi XPay? Vous devez avoir le droit de modifier les commandes. Le module capture le montant autorisé dans l'environnement du paiement, avec les clés de cet environnement, enregistre le paiement et définit le statut selon Order Status After Payment. Si la capture échoue, le bloc affiche l'erreur, une note est ajoutée et la commande reste en attente. Une seconde capture du même paiement est refusée.
Remboursements
Les remboursements ne se font pas depuis PrestaShop : il n'existe donc pas de bouton de remboursement pour Nexi XPay. Effectuez le remboursement dans le back-office Nexi XPay, puis enregistrez-le manuellement dans PrestaShop. Les boutons de remboursement standard de PrestaShop sur la page de la commande ne renvoient pas d'argent via Nexi.
Clé de licence
Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Nexi XPay Gateway est le premier bloc de Modules > Module Manager > VibeFox Nexi XPay 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-nexi 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 : celui 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é active, Nexi XPay n'est pas affiché aux clients lors de la 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 de PrestaShop ne sait pas que vous êtes connecté au back-office ; le moyen de paiement est donc aussi masqué pour vous : vous pouvez configurer le module avant d'acheter une clé, mais pas le tester lors de la 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 paiements autorisés peuvent toujours être capturés.
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 suivant 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 la licence.
Dépannage
Nexi XPay n'apparaît pas à la commande : vérifiez que la licence est active, que Enable/Disable est activé, que le mode actuel dispose des deux identifiants (Test Alias et Test MAC Key en mode test, Live Alias et Live MAC Key en mode réel) et que la devise du panier est l'EUR. La page des réglages affiche un avertissement dans ces cas. Dans Payment > Preferences, vérifiez que le module est autorisé pour l'EUR, le pays du client et le groupe du client.
Le paiement a été effectué, mais aucune commande n'a été créée : 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 réel) du paiement, et activez Debug Log pour voir ce que Nexi a envoyé dans le champ Log de la page du module.
La notification répond invalid_mac ou invalid_alias : la clé MAC ou l'alias dans les réglages ne correspond pas au terminal qui a envoyé le résultat. Copiez-les à nouveau 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 ce panier. 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 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 (par exemple, le module est désactivé). Nexi renouvelle la notification.
L'URL de notification affiche method_not_allowed dans le navigateur : c'est normal. L'URL n'accepte que les requêtes provenant de Nexi.
La commande est en Nexi XPay payment on hold after payment : lisez les Nexi XPay notes dans le bloc de la commande. La capture différée est sélectionnée (capturez le paiement avec le bouton), le montant ou la devise ne correspondait pas, un paiement est arrivé pour une commande annulée, ou Nexi XPay payment on hold est sélectionné comme statut après paiement.
Capture Nexi XPay payment est absent ou échoue : le bouton n'apparaît que pour les commandes Nexi XPay en attente comme autorisées avec capture différée, et seulement pour les employés autorisés à modifier les commandes. Si l'alias ou la clé MAC de l'environnement du paiement est vide, le bloc l'indique. Si la capture échoue, lisez l'erreur dans le bloc et dans les notes, par exemple Nexi XPay refused the capture avec le code et le message de Nexi.
Les paiements de test ne confirment pas un paiement réel : chaque paiement est vérifié avec les clés de l'environnement dans lequel il a été lancé. Passez Test Mode sur le mode souhaité et utilisez l'alias et la clé MAC de ce mode.
Désinstallation
Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox Nexi XPay 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 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 données de paiement Nexi XPay des commandes et les statuts de commande Awaiting Nexi XPay payment et Nexi XPay payment on hold sont toujours conservés, de sorte que les paiements autorisés peuvent être capturés après une réinstallation. Les commandes existantes conservent leurs notes de paiement et leurs ID de transaction.
Nexi et XPay sont des marques déposées de leurs titulaires respectifs. Ce module n'est ni affilié à Nexi ni approuvé par Nexi.