VibeFox Niubiz 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 : soles péruviens (PEN) ou dollars américains (USD). Le moyen de paiement n'est proposé que pour les paniers dans l'une de ces devises. Pour les autres devises, il est masqué au moment de la commande.

Compte Niubiz : Niubiz délivre un identifiant marchand (código de comercio), un API user et un API password pour chaque environnement. Les identifiants sandbox viennent de l'équipe d'intégration de Niubiz, les identifiants de production après que Niubiz a certifié votre intégration. Aucun webhook n'a à être configuré : Niubiz répond à l'autorisation immédiatement.

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 Niubiz Payment 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. Laissez Sandbox mode activé et saisissez le merchant ID, l'API user et l'API password de sandbox (voir Configuration).

5. Activez Enable/Disable, cliquez sur Save et effectuez quelques paiements de test avec les cartes de test Niubiz.

6. Une fois que Niubiz a certifié votre intégration, saisissez les identifiants de production et désactivez Sandbox mode.

À l'installation, le module crée le statut de commande Niubiz payment on hold. PrestaShop associe un nouveau module de paiement à toutes les devises, à tous les groupes de clients et aux pays actifs à ce moment-là. Vous pouvez modifier cela dans Payment > Preferences. Vérifiez-y que PEN ou USD est autorisé pour le module.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox Niubiz Payment > Configure. Chaque section a son propre bouton Save, qui enregistre la page entière. Au-dessus des champs, la page vous avertit lorsqu'aucune devise PEN ou USD n'est active dans la boutique, ou lorsque les identifiants du mode actuel sont incomplets (dans les deux cas, le moyen de paiement est masqué au moment de la commande). Si la devise par défaut de la boutique n'est ni PEN ni USD, la page indique que Niubiz n'est proposé que pour les paniers en PEN ou USD. Tant que le mode sandbox est activé, la page affiche Le mode sandbox est activé : les paiements sont envoyés au sandbox Niubiz et aucun débit réel n'est effectué.

Niubiz

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 que voient les clients au moment de la commande. C'est aussi le nom du moyen de paiement enregistré dans la commande. Par défaut : Credit or debit card (Niubiz). Obligatoire : un titre vide n'est pas enregistré et l'ancien est conservé.

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

Identifiants Niubiz

Niubiz vous délivre 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: utilise l'environnement sandbox (QA) de Niubiz, sans débit réel. Il change à la fois les points d'accès de l'API et l'ensemble d'identifiants ci-dessous. Par défaut : activé. Désactivez-le pour les paiements réels. Tant qu'il est activé, les clients voient MODE SANDBOX : utilisez les cartes de test Niubiz — aucun débit réel n'est effectué. sous le moyen de paiement et sur la page de paiement.

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 affiche une erreur et conserve l'ancienne valeur. Les autres champs sont enregistrés.

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, avec la même vérification.

Production API user: l'API user de production.

Production API password: l'API password de production.

Les mots de passe enregistrés ne sont jamais réaffichés. Le champ reste vide et affiche Enregistré — laissez vide pour le conserver. Saisissez une nouvelle valeur uniquement pour la modifier.

Clear saved passwords: cochez un mot de passe et cliquez sur Save pour le supprimer. Un champ vide conserve la valeur enregistrée.

Formulaire de paiement

Logo URL: adresse HTTPS facultative de votre logo affiché dans le formulaire de paiement Niubiz, d'environ 187 × 40 px. Sans elle, le nom de la boutique est affiché. Une adresse qui n'est pas une adresse https:// valide est refusée avec une erreur et l'ancienne valeur est conservée.

Avancé

Debug log: journalise les appels à l'API Niubiz dans logs/niubiz_p_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les erreurs et les avertissements sont toujours journalisés, même lorsque cette option est désactivée. Les identifiants, jetons, données de carte et données client ne sont jamais journalisés. 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: lorsqu'elle est activée, la désinstallation du module supprime ses réglages et son journal. Les données de paiement enregistrées pour les commandes (tentatives Niubiz, notes de commande) et le statut de commande sont toujours conservés. Par défaut : désactivé.

Tunnel de commande

À l'étape de paiement, le client choisit le moyen de paiement (par défaut Credit or debit card (Niubiz)) et passe la commande. Le module demande à Niubiz un jeton d'accès et une session de paiement pour le total du panier dans la devise du panier, puis ouvre la page de paiement Niubiz payment de votre boutique. Aucune commande n'existe encore à ce stade.

Sur la page de paiement, le formulaire de paiement Niubiz s'ouvre automatiquement. La page indique Effectuez le paiement dans le formulaire de paiement sécurisé Niubiz — les données de votre carte sont saisies chez Niubiz, et non sur ce site. Elle comporte aussi un bouton Pay avec le total du panier pour rouvrir le formulaire, 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 module l'autorise côté serveur avec le montant, la devise et le numéro d'achat de la session, dans l'environnement où la session a été créée. 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 au panier. La commande est alors créée et le client voit la page standard de confirmation de commande.

Carte refusée : aucune commande n'est créée. Le client revient sur la page de paiement avec Votre paiement a été refusé : et le motif de Niubiz, et peut réessayer avec la même carte ou une autre. Le formulaire ne se rouvre pas au-dessus du 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), la commande est créée en Niubiz payment on hold et la page de confirmation affiche Nous n'avons pas pu confirmer votre paiement auprès de Niubiz. Ne payez pas à nouveau : la boutique vérifiera le paiement et vous contactera. Si Niubiz a approuvé un paiement qui ne correspond pas au panier, la page affiche Votre paiement a bien été reçu et est en cours d'examen par la boutique. Nous vous contacterons si autre chose est nécessaire.

Demande refusée : si Niubiz refuse la demande elle-même (par exemple identifiants invalides ou numéro d'achat en double), aucune commande n'est créée et le client voit Niubiz n'a pas pu traiter le paiement et votre carte n'a pas été débitée. Le motif est écrit dans le journal.

Panier modifié : si le total du panier change après l'ouverture du formulaire (par exemple dans un autre onglet du navigateur), le paiement n'est pas autorisé et le client voit Votre panier a changé depuis l'ouverture du formulaire de paiement, votre carte n'a donc pas été débitée. Veuillez vérifier le total et payer à nouveau.

Session expirée : une session de paiement Niubiz dure jusqu'à 20 minutes. Si elle a déjà été utilisée, qu'il lui reste moins de 5 minutes, qu'elle appartient à un autre mode ou à un autre merchant ID, ou que le total du panier a changé, la page de paiement crée une nouvelle session.

Chaque tentative de paiement reçoit un nouveau numéro d'achat : l'identifiant du panier 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.

Le module ne prend que des paiements uniques par carte. Il ne gère ni remboursements ni annulations depuis PrestaShop, ni cartes enregistrées, abonnements ou paiements récurrents, ni choix de paiement en plusieurs fois (cuotas), ni les paiements PagoEfectivo, Yape ou autres portefeuilles et paiements QR. Les commandes mises en attente parce qu'une réponse a été perdue ne sont pas revérifiées automatiquement.

Commandes

Statuts de commande

No order yet: le client est sur la page de paiement et n'a pas payé, ou la carte a été refusée ou la demande a été rejetée. Seul le panier existe. Les refus et rejets sont écrits dans le journal du module.

Payment accepted: Niubiz a approuvé le paiement et la réponse correspondait au panier. Le paiement est enregistré avec l'identifiant de transaction Niubiz, et une note affiche l'environnement, l'identifiant de transaction, le code d'autorisation, le numéro d'achat et la marque de carte avec le numéro masqué.

Niubiz payment on hold, approved but not matching: Niubiz a approuvé un paiement dont le numéro d'achat, le montant ou la devise diffère du panier, ou dont la réponse ne contient ni le montant ni la devise. La commande n'est pas marquée payée. Si l'approbation est dans la devise du panier, le montant approuvé est enregistré comme un paiement avec son identifiant de transaction. La note liste les écarts. Vérifiez la transaction dans la console Niubiz.

Niubiz payment on hold, no definitive answer: Niubiz n'a pas répondu clairement, la carte a donc peut-être été débitée. Aucun paiement n'est enregistré. 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 Payment accepted ; sinon, annulez-la.

Si un second paiement reçoit une réponse pour un panier qui a déjà une commande, aucune seconde commande n'est créée. Une note sur la commande indique le numéro d'achat, l'identifiant de transaction et le montant, afin que vous puissiez le vérifier dans la console Niubiz et le rembourser ou l'annuler si besoin.

Bloc de paiement Niubiz

La page de commande affiche un bloc Niubiz payment avec le numéro d'achat, l'environnement (sandbox ou production), l'identifiant de transaction, le code d'autorisation, la carte et les notes de la commande. Pour une commande en Niubiz payment on hold, le bloc vous rappelle de vérifier le numéro d'achat dans la console Niubiz. Le bloc est en lecture seule.

Remboursements

Les remboursements et annulations ne sont pas disponibles depuis PrestaShop. Remboursez ou annulez la transaction dans la console Niubiz, puis mettez la commande à jour manuellement. Les boutons de remboursement standard de PrestaShop sur la page de commande ne renvoient pas d'argent via Niubiz.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Niubiz Payment est le premier bloc de Modules > Module Manager > VibeFox Niubiz Payment > 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-niubiz 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 Clé introuvable, Cette clé appartient à un autre produit, Limite de domaines atteinte ou Licence expirée le 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, Niubiz n'est pas affiché aux clients au moment de la commande. Si un paiement est lancé malgré tout, le client voit Ce moyen de paiement n'est pas disponible. Veuillez en choisir un autre. La vitrine PrestaShop ne sait pas que vous êtes connecté au back-office ; le moyen de paiement est donc masqué aussi pour vous : vous pouvez configurer le module avant d'acheter une clé, mais pas le tester au moment 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.

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 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 licence.

Dépannage

Niubiz n'apparaît pas au moment de la commande : 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 actuel sont renseignés (champs sandbox en mode sandbox, champs de production sinon) et que la devise du panier est PEN ou USD. La page des réglages affiche un avertissement si les identifiants ou les devises sont incorrects. 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 : Niubiz n'a pas de webhook pour ce formulaire de paiement ; la commande n'est donc créée que par la réponse à l'autorisation. Si le client n'a pas terminé le formulaire, il n'y a pas de commande. Sinon, consultez le champ Log sur la page du module et recherchez le numéro d'achat dans la console Niubiz. Si Niubiz a répondu mais que la commande n'a pas pu être créée (par exemple parce que le module était désactivé), le client voit Votre paiement a été reçu, mais la commande n'a pas pu être finalisée automatiquement. Veuillez nous contacter — ne payez pas à nouveau., et le module tente à nouveau de créer la commande lorsque le client rouvre la page de paiement.

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 actuel, ainsi que l'accès de votre serveur à l'API Niubiz. Activez Debug log pour plus de détails.

Le client voit « Nous n'avons pas pu lancer le paiement Niubiz » : Niubiz n'a pas créé la session de paiement. Vérifiez le merchant ID du mode actuel et le journal.

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

Le client voit « Cette commande est déjà en cours de paiement » : une autre demande est en train d'autoriser le même panier. Le client attend un instant et vérifie ses e-mails avant de réessayer.

Le journal indique que 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 Niubiz payment on hold : lisez les notes du bloc Niubiz payment. Niubiz n'a pas donné de réponse définitive, ou a approuvé un paiement qui ne correspond pas au panier. Recherchez le numéro d'achat dans la console Niubiz et passez la commande en Payment accepted 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. L'ancienne valeur est conservée.

Pour les développeurs : si Niubiz demande l'envoi de champs antifraude propres au marchand (MDD), un autre module peut les ajouter avec le hook actionNiubizPMerchantDefineData. Les données du titulaire envoyées avec la session de paiement peuvent être modifiées avec le hook actionNiubizPCardholderData.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox Niubiz Payment 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 tentatives de paiement Niubiz (numéros d'achat, environnement, identifiants de transaction) et le statut de commande Niubiz payment on hold sont toujours conservés comme historique de paiement. Les commandes existantes conservent leurs notes de paiement et leurs identifiants de transaction.

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