VibeFox Netopia 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 avec les extensions OpenSSL et DOM.
Devise : la devise de la boutique ou de la commande doit être RON, EUR, USD ou GBP. EUR, USD et GBP doivent être activées sur votre compte Netopia. Pour les autres devises, le mode de paiement est masqué lors du paiement.
Compte Netopia : vous avez besoin d'un compte vendeur Netopia Payments avec un point de vente. Depuis ses paramètres techniques, il vous faut la signature du compte et, pour chaque environnement utilisé (sandbox et production), le certificat public (.cer) et la clé privée (.key). Aucune configuration n'est nécessaire côté Netopia : l'adresse de l'IPN est envoyée avec chaque demande de paiement.
Site public : l'URL de l'IPN (confirmation) doit être accessible depuis Internet, sans être protégée par une connexion, une authentification de base ou une page de maintenance. Les commandes sont mises à jour uniquement par l'IPN de Netopia.
Clé de licence VibeFox : achetée sur vibefox.net. Une clé fonctionne sur un seul domaine.
Installation
1. Dans WordPress, rendez-vous dans Plugins > Add New > Upload Plugin, choisissez le fichier ZIP du plugin et cliquez sur Install Now. Vous pouvez aussi envoyer le dossier wcp_netopia_gateway dans /wp-content/plugins/ par FTP.
2. Cliquez sur Activate.
3. Ouvrez les réglages : WooCommerce > Settings > Payments > Netopia Payments > 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, puis cliquez sur Activate.
5. 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 de l'environnement sandbox et de l'environnement de production. Collez la signature et le contenu complet des fichiers dans les réglages (voir Configuration).
6. Activez Enable/Disable. Testez un paiement en mode sandbox, puis décochez Test mode pour accepter de vrais paiements.
Configuration
Tous les réglages se trouvent sur une seule page : WooCommerce > Settings > Payments > Netopia Payments. Au-dessus des champs, la page vous avertit lorsque la signature du compte, le certificat ou la clé privée de l'environnement actif est absent (le mode de paiement est alors masqué lors 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é. Dans la liste des modes de paiement, Netopia est signalé comme nécessitant une configuration tant que l'environnement actif n'est pas complet. À l'enregistrement, un certificat ou une clé privée invalide est refusé avec une erreur, et la valeur précédente est conservée.
IPN (confirm) URL
Affichée en lecture seule en haut des réglages. Elle ressemble à https://your-site/wc-api/netopia_payment_callback/. Elle est envoyée avec chaque demande de paiement comme URL de confirmation, vous n'avez donc pas besoin de la saisir dans l'administration Netopia. Netopia envoie l'IPN à cette URL ; le plugin la déchiffre avec la clé privée de l'environnement actif et vérifie la signature de votre compte ainsi que la demande de paiement. Netopia signale ces actions :
Une notification contenant un code d'erreur Netopia (par exemple une carte refusée) fait passer une commande non payée en échec. Les notifications qui ne peuvent pas être déchiffrées, qui portent une autre signature de compte ou qui ne répondent pas à une demande de paiement de cette commande sont rejetées et ne modifient rien.
Paiement
Enable/Disable : Enable Netopia Payments active ou désactive le mode de paiement. Par défaut : désactivé.
Title : le titre du mode de paiement affiché lors du paiement. Par défaut : Card Payment (Netopia).
Description : la description du mode de paiement affichée lors du paiement. Par défaut : Pay securely with your credit or debit card via Netopia.
Compte Netopia
Dans l'administration Netopia, rendez-vous 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-en le contenu complet, 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 : Use the Netopia sandbox (sandboxsecure.mobilpay.ro) and the sandbox keys. Bascule la page de paiement et la paire de clés. Par défaut : activé. Désactivez-le pour accepter 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. Il n'est plus jamais affiché après l'enregistrement ; le champ affiche A private key is saved. Laissez-le vide pour conserver la clé enregistrée, ou collez une nouvelle clé pour la remplacer.
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. Il n'est plus jamais affiché après l'enregistrement ; laissez le champ vide pour conserver la clé enregistrée.
Commandes
Order status after payment : le statut d'une commande payée qui doit être expédiée. Les commandes ne contenant que des articles virtuels ou téléchargeables sont de toute façon terminées par WooCommerce. Le statut est appliqué en un seul changement, avec un seul e-mail au client.
Avancé
Debug log : Log requests and IPN processing écrit dans WooCommerce > Status > Logs, source wcp_netopia_gateway. 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 lorsque l'option est désactivée. Par défaut : désactivé.
Delete data on uninstall : Remove the gateway settings and logs when the plugin is deleted (orders are kept). Par défaut : désactivé.
Paiement
Le client choisit le mode de paiement (par défaut Card Payment (Netopia)) et passe la commande. 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 order en solution de secours. La demande de paiement est chiffrée avec votre certificat Netopia et contient le total de la commande dans la devise de la commande, Order # avec le numéro de commande, ainsi que les coordonnées de facturation et de livraison. En mode sandbox, la demande est envoyée au sandbox Netopia.
Le client paie par carte sur la page Netopia et revient sur la page de confirmation de commande de votre boutique. Le retour en lui-même ne marque pas la commande comme payée. La commande n'est marquée payée qu'après confirmation de Netopia par l'IPN. Jusque-là, la page de confirmation affiche Netopia has not confirmed your payment yet. You will receive an e-mail as soon as the payment is confirmed. Pour une commande en attente, elle affiche Your payment is awaiting confirmation. We will e-mail you as soon as the order is confirmed. Si le paiement a été annulé, elle affiche The payment was cancelled at Netopia, so this order was cancelled. You can place a new order at any time.
Si la carte est refusée, la commande passe en échec et le client peut la payer à nouveau depuis la page de commande. Si le plugin n'est pas correctement configuré, la page de paiement affiche Netopia gateway is not configured properly. Please contact the store administrator.
Le mode de paiement fonctionne avec le paiement classique, avec le bloc Paiement et sur la page Pay for order. Il est compatible avec WooCommerce High-Performance Order Storage (HPOS).
Le plugin ne prend en charge que les paiements par carte via le protocole de carte Netopia v1. Il n'offre pas de remboursements ni de captures depuis WooCommerce, ni cartes enregistrées ou paiements en un clic, ni abonnements, paiements échelonnés, SMS, virements bancaires ou paiements en cryptomonnaies, ni Netopia API v2.
Commandes et remboursements
Statuts de commande
Pending payment : le client a été envoyé vers Netopia, ou Netopia n'a pas encore envoyé l'IPN.
Processing or Completed : Netopia a confirmé le paiement. Le statut suit Order status after payment. La note de commande indique le montant, le numéro de carte masqué et la transaction Netopia ; les paiements sandbox sont signalés par [sandbox]. L'identifiant de transaction est celui de la transaction Netopia.
On hold : le paiement est une pré-autorisation en attente de capture dans l'administration Netopia, ou il est en cours de vérification chez Netopia. La commande est marquée payée lorsque Netopia la confirme. Une commande est aussi mise en attente lorsque le montant ou la devise de la facture diffère de la commande, lorsque seule une partie du paiement a été capturée, ou lorsque Netopia confirme le paiement d'une commande annulée. La note de commande l'explique. Vérifiez la transaction dans l'administration Netopia, puis finalisez ou remboursez la commande manuellement.
Failed : Netopia a signalé une erreur, par exemple une carte refusée. Le client peut payer à nouveau.
Cancelled : Netopia a annulé le paiement, ou le client a cliqué sur Cancel order avant de se rendre sur Netopia.
Les notifications tardives ne rétrogradent jamais une commande payé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.
Remboursements
Les remboursements ne se font pas depuis WooCommerce : le protocole de carte Netopia v1 ne dispose pas d'appel de remboursement, il n'y a donc pas de bouton Refund via. Remboursez la transaction dans l'administration Netopia. Netopia envoie alors une IPN de crédit, et le plugin enregistre automatiquement le remboursement sur la commande, avec le motif Refund initiated by Netopia. Les remboursements partiels conservent le statut de la commande ; lorsqu'il n'y a plus rien à rembourser, WooCommerce passe la commande 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 un montant supérieur au solde restant. Le stock n'est pas réapprovisionné automatiquement.
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 > Netopia Payments. Saisissez la clé dans License key et cliquez sur Activate. Le bloc affiche le statut, par exemple la date jusqu'à laquelle la licence est active, ainsi que 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, Netopia n'est pas proposé 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. Les gestionnaires de la boutique connectés voient toujours le mode de paiement, marqué (unlicensed — visible to admins only), afin que vous puissiez 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 remboursements effectués dans l'administration Netopia sont toujours enregistrés.
Lorsqu'une licence expire, le plugin 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
Netopia n'apparaît pas lors 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 la production en mode production) et que la devise de la boutique ou de la commande est RON, EUR, USD ou GBP. La page des réglages affiche un avertissement lorsqu'un élément manque.
Le paiement a été effectué, mais la commande reste en Pending payment : l'IPN n'a pas atteint votre boutique ou a été rejetée. Vérifiez que l'URL de l'IPN (confirmation) indiquée dans les réglages est accessible depuis Internet (ni mode maintenance, ni authentification de base, ni pare-feu). Activez Debug log et recherchez les lignes IPN dans WooCommerce > Status > Logs, source wcp_netopia_gateway. Le retour du client ne marque jamais la commande comme payée à lui seul.
Log shows failed decrypting data : la clé privée ne correspond pas au certificat de l'environnement utilisé par Netopia. L'IPN est déchiffrée avec la clé de l'environnement actif et, pour les paiements lancés avant le changement de mode test, avec la clé de l'autre environnement. Netopia la renvoie à nouveau.
Log shows signature mismatch : la Account signature ne correspond pas au point de vente qui a envoyé l'IPN. Recopiez-la depuis l'administration Netopia.
Log shows unknown payment request : l'IPN ne répond à aucune demande de paiement que votre boutique a faite pour cette commande dans cet environnement (sandbox ou production). Rien n'est modifié.
Log shows gateway not configured : la clé privée ou la signature du compte est absente. Netopia renvoie l'IPN, et le paiement est enregistré une fois les réglages complétés.
Error on save about the certificate or private key : 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.
Order is On hold after payment : lisez la note de commande. Le paiement peut être une pré-autorisation ou être en cours de vérification, le montant ou la devise pouvaient différer, 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 (aucun argent réel n'a été reçu). Vérifiez la transaction dans l'administration Netopia.
A refund made in Netopia does not appear on the order : l'IPN de crédit n'a pas atteint la boutique ou a été rejetée. Consultez le journal. Si nécessaire, créez un remboursement manuel dans WooCommerce.
The license block shows an error : 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, y compris les clés enregistrées, et les journaux ne sont supprimés que si Delete data on uninstall était activé. Sinon, ils sont conservés pour une future réinstallation. Les commandes existantes conservent leurs notes de paiement et leurs identifiants de transaction.
Netopia Payments et mobilPay sont des marques de leurs propriétaires respectifs. Ce plugin n'est pas affilié à Netopia Payments et n'est pas approuvé par cette société.