VibeFox Niubiz for WooCommerce — Aide

Prérequis

WordPress : 5.8 ou ultérieur.

WooCommerce : 6.0 ou ultérieur, installé et activé. Le plugin refuse de s'activer sans lui.

PHP : 8.0 ou ultérieur.

Devise de la boutique : soles péruviens (PEN) ou dollars américains (USD). Pour les autres devises, le moyen de paiement est masqué au moment du paiement.

Compte Niubiz : Niubiz délivre un merchant ID (código de comercio), un API user et un API password pour chaque environnement. Les identifiants sandbox proviennent de l'équipe d'intégration de Niubiz, et les identifiants de production une fois votre intégration certifiée par Niubiz. Aucun webhook n'est à configurer : Niubiz répond immédiatement à l'autorisation.

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_niubiz_payment dans /wp-content/plugins/ par FTP.

2. Cliquez sur Activate.

3. Ouvrez les réglages : WooCommerce > Settings > Payments > Niubiz > 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 Sandbox mode activé et saisissez le merchant ID, l'API user et l'API password du sandbox (voir Configuration).

6. Activez Enable/Disable et effectuez quelques paiements de test avec les cartes de test Niubiz.

7. Une fois votre intégration certifiée par Niubiz, saisissez les identifiants de production et décochez Sandbox mode.

Configuration

Tous les réglages se trouvent sur une seule page : WooCommerce > Settings > Payments > Niubiz. Au-dessus des champs, la page vous avertit lorsque la devise de la boutique n'est ni PEN ni USD, ou lorsque les identifiants du mode en cours sont incomplets (dans les deux cas, le moyen de paiement est masqué au moment du paiement), et affiche Le mode sandbox est activé : les paiements sont envoyés au sandbox Niubiz et aucun débit réel n'est effectué. tant que le mode sandbox est activé. Dans la liste des moyens de paiement, Niubiz est signalé comme nécessitant une configuration tant que le mode en cours ne dispose pas d'identifiants complets.

Général

Enable/Disable : Enable Niubiz payments active ou désactive le moyen de paiement. Par défaut : désactivé.

Title : le nom du moyen de paiement affiché au client au moment du paiement. Par défaut : Credit or debit card (Niubiz).

Description : le texte affiché sous le moyen de paiement au moment du paiement. Par défaut : Pay securely with Visa, Mastercard, American Express or Diners Club in the Niubiz payment form.

Identifiants Niubiz

Niubiz vous fournit un merchant ID, un API user et un API password pour le sandbox et, après certification, pour la production. La documentation développeur se trouve sur desarrolladores.niubiz.com.pe.

Sandbox mode : Use the Niubiz sandbox (QA) environment — no real charges. Change à la fois les points d'accès de l'API et l'ensemble d'identifiants ci-dessous. Par défaut : activé. Décochez-le pour les paiements réels.

Sandbox merchant ID : le code marchand de votre compte sandbox, chiffres uniquement. Les espaces sont supprimés. Si la valeur contient d'autres caractères, la page des réglages affiche une erreur et conserve la valeur précédente.

Sandbox API user : l'API user du sandbox.

Sandbox API password : l'API password du sandbox.

Production merchant ID : le code marchand de votre compte de production (affilié), chiffres uniquement.

Production API user : l'API user de production.

Production API password : l'API password de production.

Formulaire de paiement

Logo URL : adresse HTTPS facultative de votre logo affiché dans le formulaire de paiement Niubiz, environ 187 × 40 px. Sans elle, le nom de la boutique est affiché. Une adresse qui ne commence pas par https:// est refusée et la valeur précédente est conservée.

Avancé

Debug log : Log API calls écrit les requêtes Niubiz dans WooCommerce > Status > Logs, source wcp_niubiz_payment. Les erreurs sont toujours consignées. Les identifiants, les jetons, ainsi que les données de carte et du client ne sont jamais consignés. Par défaut : désactivé.

Delete data on uninstall : Remove the settings and logs of this plugin when it is deleted. La désactivation ne supprime jamais rien. Les données de paiement enregistrées sur les commandes sont conservées. Par défaut : désactivé.

Les réglages de la version 1.0, qui n'avait qu'un jeu d'identifiants, sont transférés automatiquement : vers les champs sandbox si le mode test était activé, sinon vers les champs de production.

Paiement

Le client choisit le moyen de paiement (par défaut Credit or debit card (Niubiz)) et passe la commande. Le plugin demande à Niubiz un jeton d'accès et une session de paiement pour le montant total de la commande, puis envoie le client sur la page de paiement de la commande de votre boutique. En mode sandbox, le paiement et la page de paiement affichent MODE SANDBOX : utilisez les cartes de test Niubiz — aucun débit réel n'est effectué.

Sur la page de paiement, le formulaire de paiement Niubiz s'ouvre automatiquement. La page comporte aussi un bouton Pay avec le montant de la commande pour rouvrir le formulaire, un bouton Cancel order et un lien Choose another payment method. JavaScript est requis. Si le formulaire Niubiz ne peut pas être chargé, la page affiche Le formulaire de paiement Niubiz n'a pas pu être chargé. Veuillez recharger la page ou réessayer plus tard.

Le client saisit sa carte dans le formulaire Niubiz. Niubiz renvoie à votre boutique un jeton à usage unique, et le plugin l'autorise côté serveur avec le montant, la devise et le numéro d'achat propres à la commande. Le paiement est débité immédiatement. La commande n'est marquée payée que lorsque Niubiz approuve le paiement et que la réponse correspond à la commande. Le client voit ensuite la page de confirmation de commande.

Carte refusée : le client revient à la page de paiement avec Votre paiement a été refusé : et le motif donné par Niubiz, et peut réessayer avec la même carte ou une autre. Le formulaire ne se rouvre pas par-dessus le message ; le client clique sur Pay.

Aucune réponse de Niubiz : si Niubiz ne donne pas de réponse définitive (délai dépassé, erreur serveur, réponse illisible), le client voit la page de confirmation de commande avec Nous n'avons pas pu confirmer votre paiement auprès de Niubiz. Veuillez ne pas payer à nouveau : la boutique vérifiera le paiement et vous contactera.

Session expirée : la session de paiement dure jusqu'à 20 minutes. Lorsqu'elle est utilisée ou sur le point d'expirer, ou lorsque le montant de la commande ou le mode change, la page de paiement crée une nouvelle session.

Chaque tentative de paiement reçoit un nouveau numéro d'achat : l'ID de la commande suivi d'un numéro de tentative à trois chiffres (jusqu'à 12 caractères), car Niubiz exige un numéro d'achat unique pour chaque autorisation. Un client peut payer à nouveau une commande impayée ou en échec depuis la page Pay for order.

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 que des paiements uniques par carte. Il n'offre ni remboursements ni annulations depuis WooCommerce, ni cartes enregistrées, abonnements ou paiements récurrents, ni choix de paiement en plusieurs fois (cuotas), ni PagoEfectivo, Yape ou autres portefeuilles et paiements par QR. Les commandes passées en attente parce qu'une réponse a été perdue ne sont pas revérifiées automatiquement.

Commandes

Statuts de commande

En attente de paiement : le client a été envoyé sur la page de paiement et n'a pas encore payé.

En cours : Niubiz a approuvé le paiement et la réponse correspondait à la commande. Les commandes ne comportant que des produits virtuels téléchargeables passent en Terminée, comme d'habitude dans WooCommerce. La note de commande indique l'environnement, l'ID de transaction, le code d'autorisation, le numéro d'achat et la marque de la carte avec le numéro masqué. L'ID de transaction de la commande est l'ID de transaction Niubiz.

Échec : la carte a été refusée. La note de commande indique le motif Niubiz, le code d'action et le numéro d'achat. Le client peut payer à nouveau.

En attente, approuvé mais ne correspondant pas : Niubiz a approuvé un paiement dont le numéro d'achat, le montant ou la devise diffère de la commande, ou dont la réponse ne contient pas le montant ou la devise. La commande n'est pas marquée payée ; la note énumère les écarts. Vérifiez la transaction dans la console Niubiz. Le client voit Votre paiement a été reçu et est en cours de vérification par la boutique.

En attente, sans réponse définitive : Niubiz n'a pas répondu clairement, la carte a donc peut-être été débitée. La note indique le numéro d'achat. Recherchez-le dans la console Niubiz : si la transaction est approuvée et correcte, passez la commande en En cours ; sinon, annulez-la.

Annulée : le client a cliqué sur Cancel order sur la page de paiement, ou la commande a été annulée par vous ou par le délai de réservation du stock WooCommerce.

Lorsque Niubiz refuse la requête elle-même (par exemple un numéro d'achat en double, HTTP 406 ou identifiants invalides), le statut de la commande ne change pas. Une note indique que la carte n'a pas été débitée, et le client peut réessayer avec un nouveau numéro d'achat.

Remboursements

Les remboursements et annulations ne sont pas disponibles depuis WooCommerce. Remboursez ou annulez la transaction dans la console Niubiz, puis mettez la commande à jour manuellement, par exemple avec un remboursement manuel 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 > Niubiz. 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, Niubiz 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 dans le formulaire Niubiz sont toujours autorisé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

Niubiz n'apparaît pas au paiement : vérifiez que la licence est active, que Enable/Disable est activé, que le merchant ID, l'API user et l'API password du mode en cours sont renseignés (champs sandbox en mode sandbox, champs de production sinon) et que la devise est PEN ou USD. Sur la page Pay for order, c'est la devise de la commande qui compte. La page des réglages affiche un avertissement lorsque les identifiants ou la devise sont incorrects.

Le paiement a abouti, mais la commande reste En attente de paiement : Niubiz n'a pas de webhook pour ce formulaire de paiement, la commande n'est donc mise à jour que par la réponse à l'autorisation. Si la commande est En attente avec une note, recherchez le numéro d'achat dans la console Niubiz. Si elle reste En attente de paiement, le client n'a pas terminé le formulaire ; consultez WooCommerce > Status > Logs, source wcp_niubiz_payment.

Le client voit Nous n'avons pas pu nous connecter à Niubiz : le jeton d'accès n'a pas pu être obtenu. Vérifiez l'API user et l'API password du mode en cours, et que votre serveur peut joindre l'API Niubiz. Activez le Debug log pour les détails.

Le client voit Nous n'avons pas pu démarrer le paiement Niubiz : Niubiz n'a pas créé la session de paiement. Vérifiez le merchant ID du mode en cours et le journal.

Le client voit Cette tentative de paiement a déjà été traitée : le même formulaire a été envoyé deux fois. Le client relance le paiement depuis la page de paiement ; la carte n'est pas débitée deux fois.

Le client voit Votre session de paiement a expiré et votre carte n'a pas été débitée : la page de paiement est restée ouverte trop longtemps. Le client réessaie sur la même page.

Note de commande : Niubiz a signalé une autorisation en double : Niubiz connaît déjà ce numéro d'achat. Vérifiez-le dans la console Niubiz ; le client peut réessayer avec un nouveau numéro d'achat.

La commande est En attente avec une note Niubiz : lisez la note. Niubiz n'a pas donné de réponse définitive, ou a approuvé un paiement qui ne correspond pas à la commande. Recherchez le numéro d'achat dans la console Niubiz et passez la commande en En cours ou annulez-la.

Erreur lors de l'enregistrement des réglages : un merchant ID ne doit contenir que des chiffres, et l'URL du logo doit être une adresse https:// valide. La valeur précédente est conservée.

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.

Pour les développeurs : si Niubiz demande d'envoyer des champs antifraude propres au marchand (MDD), ajoutez-les avec le filtre niubiz_p_merchant_define_data. Les clés sont MDD suivi d'un numéro, et les valeurs peuvent compter jusqu'à 100 caractères. Autres filtres : niubiz_p_cardholder_data (données du porteur envoyées avec la session de paiement), niubiz_p_purchase_number (numéro d'achat d'une tentative, de 1 à 12 lettres ou chiffres, unique par tentative) et niubiz_p_icon (icône du moyen de paiement).

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é. Les données Niubiz enregistrées sur les commandes (ID de transaction, numéro d'achat, carte masquée) constituent l'historique des paiements et sont toujours conservées. Les commandes existantes conservent leurs notes de paiement et leurs ID de transaction.

Niubiz est une marque de son propriétaire. Ce plugin n'est ni affilié à Niubiz ni approuvé par Niubiz.