VibeFox Nets Nexi for PrestaShop — Aide

Prérequis

PrestaShop : 8.0 à 9.x.

PHP : 8.0 ou ultérieur avec l'extension cURL. Le module refuse de s'installer sur des versions antérieures de PHP ou sans cURL.

Compte Nets : vous avez besoin des clés secrètes de votre compte Nets Easy (test et production). Seules les clés secrètes sont utilisées. Les clés de checkout ne sont pas nécessaires, car les clients paient sur la page de paiement hébergée de Nets.

Devises et modes de paiement : le module ne restreint pas lui-même les devises ni les pays. Utilisez les devises activées sur votre compte Nets ; une devise non prise en charge est signalée par Nets lors de la création du paiement. Les modes de paiement visibles par le client dépendent de votre contrat Nets, de votre pays et de votre devise.

HTTPS pour les webhooks : Nets n'appelle que des adresses HTTPS publiques d'au plus 256 caractères et sans « & ». Votre boutique a donc besoin de HTTPS et d'URL conviviales pour recevoir les webhooks. Sans webhooks, le paiement est tout de même confirmé lorsque le client revient dans la boutique ou via la vérification de statut sur la page de commande.

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 Nets Nexi 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. Copiez la clé secrète de test depuis le portail de test de Nets Easy et collez-la dans Test Secret Key (voir Configuration).

5. Activez Enable/Disable, laissez Test Mode activé, cliquez sur Save et passez une commande de test. Saisissez ensuite la clé secrète de production et désactivez Test Mode.

À l'installation, le module crée le statut de commande Nets payment on hold. PrestaShop ne rattache un nouveau module de paiement qu'aux pays actifs au moment de l'installation. Vérifiez les devises, les pays et les groupes de clients du module dans Payment > Preferences.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox Nets Nexi Gateway > Configure. Chaque section a son propre bouton Save, qui enregistre toute la page. Au-dessus des champs, la page vous avertit lorsque la clé secrète du mode sélectionné manque, par exemple avec Nets Nexi: enter the Test Secret Key — the payment method is hidden at checkout until the key of the selected mode is set., et affiche Nets Nexi is in test mode: payments go to the Nets test environment and no real money is charged. tant que le mode test est activé.

Nets Nexi (pays nordiques)

Le titre de la section affiche TEST ou LIVE selon le mode sélectionné.

Enable/Disable : Enable Nets Nexi Gateway active ou désactive le mode de paiement. Par défaut : désactivé.

Title : le titre du mode de paiement affiché aux clients lors du paiement. C'est aussi le nom du mode de paiement enregistré dans la commande. Par défaut : Nets Easy. Obligatoire : un titre vide provoque l'erreur Enter a title for the payment method. et rien n'est enregistré.

Description : la description du mode de paiement affichée aux clients lors du paiement. Par défaut : Pay securely with Nets Easy.

Clés API

Copiez les clés secrètes depuis le portail Nets Easy, sous Company > Integration : le portail de test (test.portal.dibspayment.eu) pour la clé de test et le portail de production (portal.dibspayment.eu) pour la clé de production. Les clés de checkout ne sont pas nécessaires.

Test Mode : le mode test utilise test.api.dibspayment.eu avec la clé secrète de test ; le mode production utilise api.dibspayment.eu avec la clé secrète de production. Les remboursements et les captures d'une commande utilisent toujours l'environnement dans lequel elle a été payée. Par défaut : activé. Tant qu'il est activé, les clients voient Test mode: no real money will be charged. sous le mode de paiement.

Test Secret Key : votre clé secrète d'API de l'environnement de test de Nets.

Live Secret Key : votre clé secrète d'API de l'environnement de production de Nets.

Les clés enregistrées ne sont plus jamais 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.

Clear saved secrets : cochez une clé et cliquez sur Save pour la supprimer. Un champ vide conserve la valeur enregistrée.

Paiement

Webhooks : les notifications Nets (webhooks) sont enregistrées automatiquement avec chaque paiement. Rien n'est à configurer dans le portail Nets. La section affiche l'adresse à laquelle elles sont envoyées. Avec des URL conviviales, elle ressemble à https://your-shop/module/wcp_nets_nexi_gateway/webhook, éventuellement avec un code de langue comme /en/. Si l'adresse n'est pas une adresse HTTPS publique, la section vous avertit que la boutique ne reçoit pas les webhooks ; les paiements sont alors confirmés lorsque le client revient dans la boutique ou via Nets: check payment status and capture: sur la page de commande. Les événements suivants sont enregistrés :

Chaque webhook doit porter le secret aléatoire que le module a créé pour ce paiement. Les webhooks sans le bon secret sont rejetés. Le webhook indique seulement au module quel paiement a changé : le paiement lui-même est toujours relu depuis l'API Nets avec la clé secrète de l'environnement dans lequel il a été effectué. Le webhook fonctionne pendant que la boutique est en mode maintenance et n'est pas bloqué par la restriction de pays de votre boutique.

Order Status After Payment : le statut de la commande une fois que Nets a confirmé et débité le paiement.

Avancé

Debug log : enregistre les appels à l'API et les changements de statut des paiements dans logs/nng_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les erreurs sont toujours enregistrées. Les clés et les données clients ne sont pas enregistrées. 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 : supprime les réglages et les journaux du module lors de la désinstallation. Les données de paiement enregistrées sur les commandes sont toujours conservées. Par défaut : désactivé.

Paiement

À l'étape de paiement, le client choisit le mode de paiement (par défaut Nets Easy) et confirme. Le module crée un paiement Nets pour le total du panier dans la devise du panier, avec les produits, l'expédition, l'emballage cadeau et les remises comme lignes de commande, puis envoie le client sur la page de paiement hébergée de Nets. La référence du paiement chez Nets est le numéro de panier. L'e-mail, le nom, l'adresse et le numéro de téléphone du client sont transmis à Nets lorsque Nets accepte leur format. Le lien vers la page des conditions générales de votre processus de paiement figure sur la page Nets (la page d'accueil de la boutique si aucune n'est définie). Aucune commande n'existe encore à ce stade.

Après le paiement, le client revient dans votre boutique. La commande n'est marquée payée qu'après confirmation de Nets : le module relit le paiement depuis l'API Nets, compare le montant réservé et la devise avec le panier, débite la réservation et ce n'est qu'alors qu'il crée la commande. Cela se produit lors du webhook ou lorsque le client revient, selon le premier des deux. Le client voit ensuite la page standard de confirmation de commande. Si le paiement n'a pas encore pu être confirmé (Nets était injoignable, ou une autre requête le confirmait à ce moment-là), une page Payment confirmation affiche Your Nets payment is being confirmed. Your order will be created as soon as it is confirmed — please do not pay again. avec les boutons Check again et Back to checkout.

Si le client annule sur la page Nets, il revient au paiement avec le message The Nets payment was cancelled. You can try again or choose another payment method. Si rien n'a été payé, le message est The payment was not completed. You can try again or choose another payment method. Le panier est conservé. Lors d'une nouvelle tentative, le module vérifie d'abord le paiement précédent ; s'il est déjà payé, la commande est créée au lieu d'un nouveau paiement. Sinon, la session Nets précédente est fermée avant qu'une nouvelle ne commence.

Si Nets ne peut pas démarrer le paiement, le client reste à l'étape de paiement avec un message bref, par exemple Nets could not start the payment with the details of this order. Please check your address and phone number, or choose another payment method., This payment method is temporarily unavailable. Please choose another payment method. ou The payment service could not be reached. Please try again in a moment. Un total de panier égal à zéro affiche The order total must be greater than zero to pay with Nets. Les détails sont écrits dans le journal.

Le module n'utilise que la page de paiement hébergée. Il ne propose ni checkout Nets intégré à la page, ni abonnements ou paiements récurrents, ni cartes enregistrées, ni frais de facturation, ni mode autorisation seule, ni captures partielles par expédition.

Commandes et remboursements

Statuts de commande

No order yet: le client a été envoyé vers Nets et n'a pas payé, ou le paiement n'est pas encore confirmé. Seul le panier existe.

Payment accepted or Delivered: Nets a confirmé et débité le paiement. Le statut suit Order Status After Payment. Le paiement est enregistré avec l'identifiant de paiement Nets comme identifiant de transaction, et une note indique l'identifiant de paiement, l'identifiant de débit et le mode de paiement.

Nets payment on hold: le montant ou la devise chez Nets diffère du panier (non capturé), la capture a été refusée, ou le client a payé après l'annulation de la commande (réservé, non capturé). La note l'explique. Rien n'est capturé automatiquement. Après vérification de la commande, capturez avec Nets: check payment status and capture, ou annulez la réservation dans le portail Nets.

Canceled: la réservation d'une commande en attente a été annulée, par exemple dans le portail Nets.

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

Les webhooks répétés et les rechargements ne débitent jamais deux fois et n'ajoutent pas de notes en double ; une commande payée n'est jamais modifiée à nouveau par des événements Nets. Si un ancien lien de paiement est finalisé pour une commande déjà payée, la seconde réservation est libérée automatiquement ; si elle a déjà été débitée, une note vous demande de la rembourser dans le portail Nets.

Bloc de paiement Nets Easy

La page de commande affiche un bloc Nets Easy payment avec l'identifiant de paiement, l'identifiant de débit, l'environnement (avec un badge Test environment pour les paiements de test), le statut, les montants réservés et débités chez Nets, le total de la commande et le montant remboursé, l'historique des remboursements et les Nets notes de la commande. Les boutons du bloc fonctionnent pour tout employé autorisé à modifier les commandes ; l'accès aux pages Modules n'est pas nécessaire.

Nets: check payment status and capture: affiché pour les commandes non encore payées. Il relit le paiement chez Nets et capture une réservation qui correspond à la commande, y compris après une capture échouée ou après que vous avez vérifié une commande en attente. Si rien ne change, une note explique pourquoi, par exemple que le client n'a pas encore terminé le paiement.

Remboursements

Dans le bloc Nets Easy payment, saisissez le montant (le montant non encore remboursé est prérempli), éventuellement un motif, puis cliquez sur Refund via Nets. Confirmez la question Refund this amount through Nets? This cannot be undone. Les remboursements totaux et partiels sont possibles une fois le paiement débité ; un paiement seulement réservé peut être annulé dans le portail Nets. Le remboursement porte sur le débit de la commande dans l'environnement où elle a été payée. Si Nets refuse le remboursement, le bloc affiche l'erreur et aucun remboursement n'est enregistré. Un remboursement réussi est ajouté à l'historique des remboursements et aux notes, avec l'identifiant de remboursement Nets. Un remboursement total place la commande en Refunded ; un remboursement partiel ne modifie pas le statut.

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 Nets. Les remboursements effectués dans le portail Nets ne sont pas synchronisés ; mettez la commande à jour manuellement si besoin.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Nets Nexi Gateway est le premier bloc de Modules > Module Manager > VibeFox Nets Nexi 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-nets-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, Nets n'est pas affiché aux clients lors du paiement. 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 du paiement. Un rappel apparaît dans Modules > Module Manager, sur l'onglet Alerts. Les commandes existantes ne sont pas affectées : les paiements déjà commencé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 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

Nets Nexi n'apparaît pas au paiement : vérifiez que la licence est active, que Enable/Disable est activé et que le mode sélectionné dispose d'une clé secrète : Test Secret Key en mode test, Live Secret Key en mode production. La page des réglages affiche un avertissement lorsque la clé 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 été effectué, mais aucune commande n'a été créée : le webhook n'a pas atteint votre boutique. Vérifiez que la boutique utilise HTTPS et des URL conviviales, afin que l'adresse dans Webhooks soit une adresse HTTPS publique sans « & », et que la clé secrète de l'environnement du paiement est renseignée. La commande est aussi créée lorsque le client revient dans la boutique après avoir payé.

Le webhook répond Unauthorized : le webhook ne contenait pas le secret de ce paiement. Les webhooks ne sont acceptés qu'avec le secret enregistré lors du paiement.

Le webhook répond Busy, retry later, Payment lookup failed ou Payment not reserved yet : une autre requête confirmait le même panier, l'API Nets était injoignable, ou la réservation n'était pas encore visible. Nets relance automatiquement le webhook.

Le webhook répond Order could not be created, retry later : la commande n'a pas pu être créée, par exemple parce que le module est désactivé. Activez Debug log pour voir la raison.

L'URL du webhook affiche Method not allowed dans le navigateur : c'est normal. L'adresse n'accepte que les requêtes de Nets.

Le client voit une erreur en choisissant Nets : activez Debug log et consultez le champ Log sur la page du module. This payment method is temporarily unavailable. Please choose another payment method. signale généralement une clé secrète erronée ou absente. Une devise refusée est signalée par Nets dans le journal.

La commande est en Nets payment on hold après le paiement : lisez les Nets notes du bloc. Si la capture a été refusée, réessayez avec Nets: check payment status and capture ou débitez-la dans le portail Nets. Si le montant ou la devise diffère, vérifiez le paiement dans le portail Nets. Si le client a payé après l'annulation, vérifiez la commande, puis capturez ou annulez la réservation.

Refund via Nets est absent ou échoue : les remboursements ne sont possibles qu'après le débit du paiement ; le bloc affiche alors un identifiant de débit. Un remboursement utilise la clé secrète de l'environnement dans lequel la commande a été payée, cette clé doit donc être renseignée ; sinon, le bloc indique quelle clé d'environnement manque.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox Nets Nexi 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 Nets des commandes (paiements, débits et remboursements) et le statut de commande Nets payment on hold sont toujours conservés, afin que les commandes payées auparavant puissent encore être remboursées après une réinstallation. Les commandes existantes conservent leurs notes de paiement et leurs identifiants de transaction.

Nets, Nets Easy et Nexi sont des marques de leurs détenteurs respectifs. Ce module n'est ni affilié ni approuvé par Nets ni par Nexi.