VibeFox Netopia for PrestaShop — Aide
Prérequis
PrestaShop : 8.0 à 9.x.
PHP : 8.0 ou ultérieur avec les extensions OpenSSL, DOM et SimpleXML. Le module refuse de s'installer sans elles.
Devise : la devise du panier doit être RON, EUR, USD ou GBP. EUR, USD et GBP doivent être activées sur votre compte Netopia. Pour les autres devises, le moyen de paiement est masqué au moment du paiement.
Compte Netopia : vous avez besoin d'un compte vendeur Netopia Payments avec un point de vente. Dans ses paramètres techniques, il faut la signature du compte et, pour chaque environnement utilisé (sandbox et production), le certificat public (.cer) et la clé privée (.key). Rien n'est à configurer côté Netopia : l'adresse IPN est envoyée avec chaque demande de paiement.
Boutique publique : l'URL IPN (confirmation) doit être accessible depuis Internet, et non derrière une connexion ou une authentification de base. Les commandes ne sont créées que par l'IPN de Netopia.
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 Netopia Gateway dans la liste des modules et cliquez sur Configure.
3. Saisissez votre clé de licence VibeFox dans le champ License key du bloc de licence en haut de la page Configure et cliquez sur Activate (voir Clé de licence).
4. Dans l'administration Netopia, ouvrez votre point de vente, copiez la signature du compte et téléchargez le certificat et la clé privée des environnements sandbox et production. Collez la signature et le contenu complet des fichiers dans les réglages (voir Configuration).
5. Activez Enable/Disable et cliquez sur Save. Testez un paiement en mode sandbox, puis désactivez Test mode pour encaisser de vrais paiements.
À l'installation, le module crée deux statuts de commande, Awaiting Netopia payment et Netopia 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 limiter dans Payment > Preferences.
Configuration
Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox Netopia Gateway > Configure. Chaque section a son propre bouton Save, qui enregistre la page entière. Au-dessus des champs, la page vous avertit si la signature du compte, le certificat ou la clé privée de l'environnement actif manque (le moyen de paiement est alors masqué au moment du paiement), et affiche Test mode is on: payments go to the Netopia sandbox and no real money is charged. tant que le mode test est activé. À l'enregistrement, un certificat ou une clé privée non valide est rejeté avec une erreur et la valeur précédente est conservée ; les autres champs sont enregistrés.
IPN (confirm) URL
Elle est affichée en lecture seule en haut de la page. Avec les URL conviviales, elle ressemble à https://your-shop/module/wcp_netopia_gateway/notify, éventuellement avec un code de langue comme /en/. Elle est envoyée avec chaque demande de paiement comme URL de confirmation : vous n'avez donc pas à la saisir dans l'administration Netopia. Netopia envoie l'IPN à cette URL. Le module la déchiffre avec la clé privée de l'environnement dans lequel le paiement a été lancé, et vérifie la signature de votre compte ainsi que la demande de paiement. Netopia signale ces actions :
Une notification portant un code d'erreur Netopia (par exemple une carte refusée) place une commande en attente dans Payment error ; sans commande, le client peut payer à nouveau. Les notifications qui ne peuvent pas être déchiffrées, qui portent une autre signature de compte ou qui ne répondent à aucune demande de paiement de ce panier sont rejetées et ne modifient rien.
Paiement
Enable/Disable: Enable Netopia Payments active ou désactive le moyen de paiement. Par défaut : off.
Title: le titre du moyen de paiement affiché au moment du paiement. C'est aussi le nom du moyen de paiement enregistré dans la commande. Par défaut : Card Payment (Netopia).
Description: la description du moyen de paiement affichée au moment du paiement. Par défaut : Pay securely with your credit or debit card via Netopia.
Compte Netopia
Dans l'administration Netopia, allez dans Seller accounts > your point of sale > Technical settings : copiez la signature du compte et téléchargez le certificat public (.cer) et la clé privée (.key) de chaque environnement. Ouvrez les fichiers dans un éditeur de texte et collez tout leur contenu, y compris les lignes BEGIN/END.
Account signature: la signature du compte vendeur (format XXXX-XXXX-XXXX-XXXX-XXXX), identique pour le sandbox et la production.
Test mode: utilise le sandbox Netopia (sandboxsecure.mobilpay.ro) et les clés sandbox. Par défaut : on. Désactivez-le pour encaisser de vrais paiements avec les clés de production.
Sandbox public certificate (.cer): le contenu du fichier du certificat public sandbox. Il sert à chiffrer la demande de paiement.
Sandbox private key (.key): le contenu du fichier de la clé privée sandbox. Il sert à déchiffrer l'IPN.
Live public certificate (.cer): le contenu du fichier du certificat public de production.
Live private key (.key): le contenu du fichier de la clé privée de production.
Les clés privées enregistrées ne sont jamais réaffichées. Le champ reste vide et son texte d'aide commence par A private key is saved. Laissez-le vide pour conserver la clé enregistrée, ou collez une nouvelle clé pour la remplacer. Un champ de certificat vide supprime le certificat.
Clear saved private keys: cochez une clé et cliquez sur Save pour la supprimer. Un champ vide conserve la clé enregistrée.
Commandes
Order status after payment: le statut d'une commande payée.
Avancé
Debug log: enregistre les requêtes et le traitement des IPN dans logs/netopia_p_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les données de carte, les clés et les données clients ne sont pas journalisées. Les erreurs, par exemple les IPN rejetées, sont toujours journalisées, même si 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: supprime, lors de la désinstallation du module, les réglages de la passerelle, les enregistrements de paiement Netopia du module et le journal. Les commandes sont conservées. Par défaut : off.
Paiement
À l'étape de paiement, le client choisit le moyen de paiement (par défaut Card Payment (Netopia)) et confirme. La page suivante affiche Redirecting you to Netopia for secure payment… et envoie automatiquement le client vers la page de paiement Netopia, avec les boutons Proceed to payment et Cancel (retour au paiement) en solution de secours. La demande de paiement est chiffrée avec votre certificat Netopia et contient le total du panier dans la devise du panier, Cart # avec le numéro du panier, ainsi que les coordonnées de facturation et de livraison. En mode sandbox, la demande est envoyée au sandbox Netopia. Aucune commande n'existe encore à ce stade.
Le client paie par carte sur la page Netopia et revient dans votre boutique. Le retour lui-même ne crée ni ne paie jamais une commande. La commande n'est marquée payée qu'après confirmation de Netopia par l'IPN. Si la commande existe, le client voit la page standard de confirmation de commande. Pour une commande en attente, elle affiche Netopia has not confirmed your payment yet. You will receive an e-mail as soon as the payment is confirmed. Pour une commande mise en attente, elle affiche Your payment is awaiting confirmation. We will e-mail you as soon as the order is confirmed. Pour une commande annulée, elle affiche The payment was cancelled at Netopia, so this order was cancelled. You can place a new order at any time. Pour une commande avec erreur de paiement, elle affiche The payment was declined by Netopia.
Si l'IPN n'est pas encore arrivée lorsque le client revient, une page Payment confirmation affiche le même texte « pas encore confirmé », avec les boutons Check again et Back to checkout. La commande est créée dès que l'IPN arrive.
Si Netopia a signalé une annulation ou un refus avant la création de toute commande, le client revient au paiement avec The payment was cancelled at Netopia. You can try again or choose another payment method. ou The payment was declined by Netopia. You can try again or choose another payment method. Le panier est conservé. Chaque nouvelle tentative est une nouvelle demande de paiement ; les demandes précédentes du panier restent valables, de sorte qu'une IPN tardive d'une tentative antérieure est tout de même enregistrée.
Si le module n'est pas correctement configuré, le client reste au paiement avec Netopia gateway is not configured properly. Please contact the store administrator. Les autres messages sont Netopia cannot process payments in suivi de la devise, This order has nothing to pay. et Payment encryption failed. Please try again or contact support. La raison technique est écrite dans le journal.
L'IPN fonctionne pendant que la boutique est en mode maintenance et n'est pas bloquée par la restriction par pays de votre boutique.
Le module n'accepte les paiements par carte que via le protocole de carte Netopia v1. Il n'offre ni remboursements ni captures depuis PrestaShop, ni cartes enregistrées ou paiements en un clic, ni abonnements, paiements échelonnés ou autres moyens de paiement, ni Netopia API v2.
Commandes et remboursements
Statuts de commande
Aucune commande pour le moment : le client a été envoyé vers Netopia et n'a pas encore payé, ou Netopia n'a pas encore envoyé l'IPN. Seul le panier existe.
Payment accepted or Delivered: Netopia a confirmé le paiement. Le statut suit Order status after payment. Le paiement est enregistré avec la transaction Netopia comme ID de transaction, et une note privée indique le montant, le numéro de carte masqué et la transaction Netopia ; les paiements sandbox sont marqués [sandbox].
Awaiting Netopia payment: le paiement est une préautorisation en attente de capture dans l'administration Netopia, ou il est en cours de contrôle chez Netopia. Aucun paiement n'est encore enregistré. La commande passe au statut payé lorsque Netopia la confirme.
Netopia payment on hold: le montant ou la devise de la facture diffère du panier ou de la commande, seule une partie du paiement a été capturée, Netopia a confirmé le paiement d'une commande annulée ou d'une commande passée avec un autre moyen de paiement, ou un paiement sandbox (test) a été confirmé alors que la boutique est en mode production (aucun argent réel n'a été reçu, donc aucun paiement n'est enregistré). La note l'explique. Vérifiez la transaction dans l'administration Netopia, puis traitez la commande ou remboursez le paiement là-bas.
Payment error: Netopia a signalé une erreur, par exemple une carte refusée, pour une commande en attente.
Canceled: Netopia a annulé le paiement d'une commande en attente.
Refunded: le paiement a été entièrement remboursé dans l'administration Netopia.
Les notifications tardives ne rétrogradent jamais une commande payée ou clôturée. Si Netopia confirme un autre paiement pour une commande déjà payée, une note vous demande de rembourser le doublon dans l'administration Netopia.
Bloc Netopia
La page de commande affiche un bloc Netopia Payments avec la transaction Netopia, l'environnement (sandbox ou production), la demande de paiement, la dernière action IPN, la carte masquée, les montants payé, remboursé et restant, ainsi que l'historique des remboursements. Le bloc est en lecture seule.
Remboursements
Les remboursements ne se font pas depuis PrestaShop : le protocole de carte Netopia v1 n'a pas d'appel de remboursement. Remboursez la transaction dans l'administration Netopia. Netopia envoie alors une IPN d'avoir, et le module enregistre automatiquement le remboursement sur la commande avec la note Netopia refund processed: et le montant. Un remboursement partiel conserve le statut de la commande ; lorsqu'il ne reste plus rien à rembourser, la commande passe en Refunded. Pour les commandes en EUR, USD et GBP, le montant remboursé, que Netopia indique en RON, est reconverti dans la devise de la commande. Un remboursement n'est jamais enregistré deux fois, ni pour plus que le montant restant. Si Netopia signale une erreur pour le remboursement, seule une note est ajoutée.
Le module ne crée pas d'avoirs et ne remet pas les produits en stock. Les boutons de remboursement standard de PrestaShop sur la page de commande ne renvoient pas d'argent via Netopia.
Clé de licence
Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Netopia Gateway est le premier bloc de la page Modules > Module Manager > VibeFox Netopia Gateway > Configure, au-dessus des réglages. Saisissez la clé dans le champ 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-netopia et le lien Manage licenses and domains in your account, qui ouvre votre compte vibefox.net. Seuls les employés disposant de la permission 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 l'emplacement dans votre compte vibefox.net.
Sans clé active, Netopia n'est pas proposé aux clients au moment 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 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 vous ne pouvez pas le tester au moment 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à lancés sont toujours confirmés, et les remboursements effectués dans l'administration Netopia sont toujours enregistrés.
Lorsqu'une licence expire, le module continue de fonctionner, mais les mises à jour et l'assistance 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 la licence.
Dépannage
Netopia n'apparaît pas au moment du paiement : vérifiez que la licence est active, que Enable/Disable est activé, que l'environnement actif est complet (Account signature plus le certificat et la clé privée du sandbox en mode test, ou ceux de production en mode production) et que la devise du panier est RON, EUR, USD ou GBP. La page des réglages affiche un avertissement lorsque quelque chose 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 : l'IPN n'a pas atteint votre boutique ou a été rejetée. Vérifiez que l'URL IPN (confirmation) indiquée dans les réglages est accessible depuis Internet (ni authentification de base ni pare-feu). Consultez le champ Log sur la page du module : les IPN rejetées sont toujours journalisées. Activez Debug log pour voir chaque IPN. Le simple retour du client ne crée jamais de commande.
Le journal affiche failed decrypting data : la clé privée ne correspond pas au certificat utilisé par Netopia. L'IPN est déchiffrée avec la clé privée enregistrée de chaque environnement ; gardez donc enregistrée la clé de l'autre environnement tant que ses paiements sont en cours. Netopia renvoie l'IPN.
Le journal affiche signature mismatch : la Account signature diffère du point de vente qui a envoyé l'IPN. Recopiez-la depuis l'administration Netopia.
Le journal affiche unknown payment request : l'IPN ne correspond à aucune demande de paiement que votre boutique a faite pour ce panier dans cet environnement (sandbox ou production). Rien n'est modifié.
Le journal affiche gateway not configured : aucune clé privée ni aucune signature de compte n'est enregistrée. Netopia renvoie l'IPN, et le paiement est enregistré une fois les réglages complétés.
Le journal affiche busy, retry later or processing failed : le panier était en cours de traitement par une autre requête au même moment, ou la commande n'a pas pu être créée (par exemple parce que le module est désactivé). Netopia renvoie automatiquement l'IPN.
Erreur à l'enregistrement concernant le certificat ou la clé privée : le texte collé n'est pas un certificat ou une clé valide. Collez le contenu complet du fichier, y compris les lignes BEGIN/END. La valeur précédente a été conservée.
La commande est en Netopia payment on hold après le paiement : lisez la note privée de la commande (voir Statuts de commande). Le montant ou la devise différait, seule une partie a été capturée, la commande avait été annulée, ou un paiement sandbox a été confirmé alors que la boutique était en mode production. Vérifiez la transaction dans l'administration Netopia.
Un remboursement effectué dans Netopia n'apparaît pas sur la commande : l'IPN d'avoir n'a pas atteint la boutique ou a été rejetée. Consultez le journal.
Désinstallation
Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox Netopia 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 de la passerelle (y compris les clés enregistrées), les enregistrements de paiement Netopia du module (affichés dans le bloc Netopia des commandes) et le journal sont supprimés. S'il est désactivé, tout est conservé pour une réinstallation ultérieure. Les commandes et les statuts Awaiting Netopia payment et Netopia payment on hold ne sont jamais supprimés. Les commandes existantes conservent leurs notes de paiement et leurs ID de transaction.
Netopia Payments et mobilPay sont des marques de leurs titulaires respectifs. Ce module n'est ni affilié à Netopia Payments ni approuvé par cette société.