VibeFox Iugu 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: réal brésilien (BRL). Iugu ne facture qu'en BRL. Le moyen de paiement est masqué pour les paniers dans une autre devise et pour les totaux inférieurs à R$ 1,00 (le minimum d'Iugu).
Compte Iugu: vous avez besoin de deux jetons d'API depuis le tableau de bord Iugu, l'un de type "Test" et l'autre de type "Live" (voir Configuration). Iugu utilise une seule adresse d'API pour les deux : c'est le jeton qui détermine si les factures sont des factures de test ou réelles. Aucun webhook n'a besoin d'être configuré dans Iugu.
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 VibeFox Iugu Gateway plus tard 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 de configuration, puis cliquez sur Activate (voir Clé de licence).
4. Saisissez les jetons d'API de test et de production (voir Configuration), gardez Test mode activé, activez Enable / Disable et cliquez sur Save.
5. Passez une commande de test et payez-la sur la page Iugu avec un paiement de test Iugu. Lorsque tout est prêt, désactivez Test mode.
À l'installation, le module crée deux statuts de commande : Awaiting Iugu payment et Iugu 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. Iugu n'est de toute façon proposé que pour les paniers en BRL.
Configuration
Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox Iugu Gateway > Configure. Chaque section a son propre bouton Save, qui enregistre toute la page. Au-dessus des champs, la page affiche TEST MODE (les factures sont créées avec le jeton d'API de test, sans débit réel) ou LIVE. Elle vous avertit lorsque le jeton du mode actif est manquant (le moyen de paiement est alors masqué à la commande) et lorsque la devise par défaut de la boutique n'est pas BRL (Iugu n'est alors pas proposé pour les paniers dans les autres devises).
Iugu
Enable / Disable: Enable Iugu payments active ou désactive le moyen de paiement. Par défaut : off.
Title: le nom du moyen de paiement que voient les clients à l'étape de paiement. C'est aussi le nom du moyen de paiement enregistré dans la commande. Par défaut : Iugu. Obligatoire.
Description: le texte affiché sous le moyen de paiement à l'étape de paiement. Par défaut : Pay securely via Iugu. You will be redirected to complete your payment.
Identifiants d'API
Créez les jetons d'API dans Iugu Alia (alia.iugu.com) : Settings > API integration > New. Créez un jeton de type "Test" et un de type "Live".
Test mode: utilise le jeton d'API de test, donc aucun débit réel n'est effectué. Par défaut : on. Lorsque le mode test est activé, la page de paiement affiche SANDBOX — Test mode enabled. No real charges. au-dessus de la description. Les vérifications de statut et les remboursements d'une commande utilisent toujours le jeton du mode dans lequel sa facture a été créée : changer de mode ne casse donc pas les anciennes commandes.
Test API token: le jeton d'API Iugu de type "Test". Il est utilisé lorsque le mode test est activé.
Live API token: le jeton d'API Iugu de type "Live" (production). Il est utilisé lorsque le mode test est désactivé. Gardez-le secret.
Les jetons enregistrés ne sont plus jamais affichés. Le champ reste vide et affiche Saved — leave empty to keep it. Saisissez une nouvelle valeur uniquement si vous souhaitez la modifier.
Clear saved tokens: cochez un jeton et cliquez sur Save pour le supprimer. Un champ vide conserve la valeur enregistrée.
Notifications de paiement
Notification URL: chaque facture demande à Iugu de signaler les changements de statut à cette URL de votre boutique. Avec des URL conviviales, elle ressemble à ceci : https://your-shop/module/wcp_iugu_gateway/webhook. Il n'y a rien à configurer dans Iugu. Un déclencheur (gatilho) supplémentaire au niveau du compte pointant vers la même URL est sans conséquence. Les notifications ne contiennent aucune donnée de paiement sur laquelle la boutique se fie : la facture est toujours relue depuis l'API Iugu (statut, montant, devise) avant qu'une commande ne soit créée ou modifiée.
Le module réagit aux événements Iugu susceptibles de modifier le statut d'une facture : invoice.status_changed, invoice.refund, invoice.released, invoice.dunning_action et invoices. Pour chacun d'eux, il relit la facture et applique son statut :
Les autres événements et les factures qui n'ont pas été créées par votre boutique reçoivent une réponse HTTP 200 et sont ignorés, sans aucune requête vers Iugu. Sans notifications, une facture n'est vérifiée que lorsque le client revient dans la boutique depuis la page Iugu.
Avancé
Debug log: écrit les requêtes et notifications Iugu dans logs/wc_igu_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les jetons et les données client ne sont pas journalisés. Les erreurs et les avertissements sont toujours écrits, même lorsque l'interrupteur est désactivé. 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: lorsqu'il est activé, la désinstallation du module supprime les réglages de la passerelle et le journal. Les commandes, les références des factures Iugu, les remboursements et les statuts de commande du module sont toujours conservés, de sorte que les anciennes commandes fonctionnent encore après une réinstallation. Par défaut : off.
Paiement
À l'étape de paiement, le client choisit le moyen de paiement (par défaut Iugu) et confirme. Une adresse e-mail client valide est requise. Le module crée une facture Iugu pour le total du panier en BRL, à échéance de 3 jours, et envoie le client sur la page de facture Iugu. Il y paie par carte de crédit, boleto ou PIX, avec les moyens activés dans votre compte Iugu. La facture affiche Order # et le numéro du panier. Le nom et l'e-mail du client sont transmis à Iugu, ainsi que l'entreprise et le CPF/CNPJ provenant du champ Identification number ou VAT number de l'adresse, lorsqu'ils sont présents. Le téléphone et l'adresse ne sont envoyés que dans le format accepté par Iugu (numéros de téléphone brésiliens, adresses brésiliennes avec un CEP à 8 chiffres ; le numéro de rue est envoyé sous la forme s/n). Aucune commande n'existe encore à ce stade.
Après le paiement, le client revient dans votre boutique. La commande n'est marquée comme payée que lorsqu'Iugu la confirme : la facture est relue depuis l'API Iugu lorsque le client revient et lorsqu'Iugu envoie une notification. La commande est alors créée et le client voit la page standard de confirmation de commande avec Your payment with Iugu has been received.
Si le client a généré un code boleto ou PIX et est revenu avant de payer, la commande est créée en Awaiting Iugu payment et la page de confirmation affiche Your Iugu invoice is awaiting payment (boleto / PIX). The order will be confirmed as soon as Iugu reports the payment. La commande passe en Payment accepted lorsqu'Iugu signale l'encaissement, par notification ou lorsque le client rouvre le lien de retour. Si Iugu n'a pas encore pu être joint au retour du client, une page Payment confirmation affiche We are confirming your payment with Iugu. The order will be updated automatically — please do not pay again. avec un bouton Check again et un bouton Back to checkout. Une commande dont la facture a été annulée ou a expiré sans paiement affiche Your Iugu payment was not completed. Please contact us about this order. sur la page de confirmation.
Si la facture a été annulée ou a expiré avant qu'une commande n'existe, le client revient à l'étape de paiement avec The Iugu invoice was not paid (it was canceled or has expired). You can pay again below. Le panier est conservé. Lorsque le client paie à nouveau, le module le renvoie vers la même facture ouverte si le montant et le mode n'ont pas changé. Sinon, il annule l'ancienne facture dans Iugu et en crée une nouvelle, afin qu'un même panier ne puisse pas être payé deux fois via deux factures ouvertes. Si une ancienne facture est tout de même payée, le paiement reste rattaché au panier.
Si Iugu ne peut pas créer la facture, le client reste à l'étape de paiement avec un court message, par exemple Iugu could not create the invoice: suivi de la raison et d'une demande de vérifier les informations de facturation, ou Could not connect to Iugu. Please try again in a moment. La raison technique est écrite dans le journal.
L'URL de notification fonctionne même lorsque la boutique est en mode maintenance et n'est pas bloquée par la restriction de pays de votre boutique.
Le module ne gère que les paiements uniques. Il ne propose ni formulaire de carte sur le site, ni cartes enregistrées, ni abonnements ni facturation récurrente, ni carnês de paiement (carnê), ni paiements fractionnés, ni options de paiement en plusieurs fois : utilisez les réglages de la page Iugu pour les paiements en plusieurs fois. Les moyens de paiement proposés sur la page Iugu ne peuvent pas être choisis dans les réglages du module : tous les moyens activés dans votre compte Iugu sont proposés. Une commande en Payment error ou Canceled ne peut pas être payée à nouveau depuis la boutique ; le client passe une nouvelle commande.
Commandes et remboursements
Statuts de commande
No order yet: le client a été envoyé vers Iugu et n'a pas encore payé, ou Iugu n'a pas encore confirmé le paiement. Seul le panier existe.
Payment accepted: Iugu a confirmé le paiement. Le paiement est enregistré avec l'identifiant de la facture Iugu comme identifiant de transaction, et une note indique l'identifiant de la facture et le moyen de paiement (carte de crédit, boleto ou PIX).
Awaiting Iugu payment: le client est revenu avec un boleto ou un PIX émis. La commande passe en Payment accepted lorsqu'Iugu signale le paiement.
Iugu payment on hold: le paiement par carte est autorisé mais pas encore capturé (capturez-le dans Iugu, et la commande est finalisée une fois qu'Iugu signale la facture payée), le paiement est en cours d'analyse, la facture n'a été payée que partiellement, un litige (chargeback) a été ouvert, Iugu a signalé un montant ou une devise différents de ceux du panier (par exemple, si le panier a été modifié après la création de la facture), ou le paiement est arrivé après l'annulation de la commande. Les notes l'expliquent. Vérifiez la commande et traitez-la ou remboursez le paiement.
Payment error: la facture d'une commande en attente a expiré sans paiement. Si Iugu signale plus tard que la facture est payée, la commande passe en Payment accepted.
Canceled: la facture d'une commande en attente a été annulée dans Iugu.
Refunded: le paiement a été intégralement remboursé via le module ou dans le tableau de bord Iugu.
Si une autre facture du même panier est également payée, la commande ne change pas. Une note vous demande de rembourser le paiement en double dans Iugu.
Bloc de paiement Iugu
La page de commande affiche un bloc Iugu payment avec l'identifiant de la facture Iugu (lié à la facture dans Iugu), le moyen de paiement, le statut, le montant encaissé par Iugu et le montant remboursé, un badge Test mode pour les factures de test, l'historique des remboursements et les Iugu notes de la commande.
Remboursements
Dans le bloc Iugu payment, saisissez le montant (le montant non encore remboursé est prérempli), éventuellement un motif, puis cliquez sur Refund via Iugu. Confirmez la question Refund this amount through Iugu? This cannot be undone. Vous devez disposer du droit de modifier les commandes. Le remboursement est envoyé avec le jeton du mode dans lequel la facture a été créée : ce jeton doit donc être renseigné.
Les remboursements sont calculés à partir du montant qu'Iugu a réellement encaissé pour la facture : après un écart de montant, vous pouvez donc rembourser jusqu'au montant payé par le client, et non jusqu'au total de la commande. Seules les factures payées peuvent être remboursées, et pas au-delà du montant encore remboursable dans Iugu. Un remboursement n'est considéré comme effectué que lorsqu'Iugu le confirme. Si Iugu refuse le remboursement ou ne le confirme pas, 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 la facture et le motif. Un remboursement total fait passer la commande en Refunded. Un remboursement partiel ne modifie pas le statut. Les remboursements sont disponibles dès qu'Iugu a signalé la facture comme payée.
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 Iugu.
Un remboursement total effectué dans le tableau de bord Iugu fait passer la commande en Refunded avec une note. Les remboursements partiels effectués dans le tableau de bord ne sont pas importés.
Clé de licence
Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Iugu Gateway est le premier bloc de Modules > Module Manager > VibeFox Iugu 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) et 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. Plus bas figurent la ligne Product: presta-payment-iugu 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 l'emplacement dans votre compte vibefox.net.
Sans clé active, Iugu n'est pas affiché aux clients à l'étape de 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 masqué pour vous aussi. Vous pouvez configurer le module avant d'acheter une clé, mais pas le tester à l'étape de paiement. Un rappel apparaît dans Modules > Module Manager, dans l'onglet Alerts. Les commandes existantes ne sont pas affectées : les paiements déjà lancé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 que vous travaillez 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
Iugu n'apparaît pas à l'étape de paiement : vérifiez que la licence est active, que Enable / Disable est activé et que le jeton du mode actif est renseigné : Test API token en mode test, Live API token en mode production. La devise du panier doit être BRL et le total d'au moins R$ 1,00. Dans Payment > Preferences, vérifiez que le module est autorisé pour la devise BRL, le pays du client et le groupe du client. La page des réglages affiche un avertissement si le jeton ou la devise est incorrect.
Le paiement a abouti, mais aucune commande n'a été créée : la notification d'Iugu n'a pas atteint votre boutique ou n'a pas pu être vérifiée. Activez Debug log et consultez le champ Log de la page du module. Vérifiez que votre boutique est accessible depuis Internet à l'adresse Notification URL et que le jeton du mode dans lequel la facture a été créée est toujours saisi. La facture est aussi vérifiée lorsque le client revient dans la boutique après le paiement.
Notification answers verification failed: la facture n'a pas pu être relue depuis l'API Iugu à ce moment-là, par exemple à cause d'une erreur réseau, d'un jeton incorrect ou de l'absence du jeton du mode de la facture. Iugu relance la notification.
Notification answers busy: 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é). Iugu relance la notification. Le journal indique la raison.
Notification answers invalid invoice id: la notification ne contenait pas d'identifiant de facture valide. Rien n'est modifié.
Commande en Iugu payment on hold : lisez les Iugu notes dans le bloc de la commande. Un paiement par carte attend la capture, le paiement est en cours d'analyse, partiellement payé ou contesté, le montant payé ne correspond pas au panier, ou le paiement est arrivé après l'annulation de la commande.
Le client voit « Iugu payments are not available right now » : le jeton d'API est manquant ou incorrect. Vérifiez le jeton du mode actif.
Le client voit « This order already has an Iugu payment that the store has to review » : une facture antérieure du panier est autorisée, en cours d'analyse ou partiellement payée, mais aucune commande n'a pu être créée. Vérifiez la facture dans Iugu et le journal.
Échec du remboursement : lisez le message dans le bloc. Les paiements par boleto ne peuvent pas être remboursés via Iugu, les paiements PIX ne peuvent l'être qu'en totalité, et seules les factures payées peuvent être remboursées. Si le message indique que le paiement a été effectué en mode test ou production et qu'aucun jeton n'est configuré, saisissez le jeton de ce mode. Si Iugu n'a pas confirmé le remboursement, vérifiez la facture dans Iugu avant de réessayer.
Les développeurs peuvent modifier la requête de facture, par exemple pour limiter les moyens de paiement avec payable_with, dans le hook actionWcpIuguInvoiceData.
Désinstallation
Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox Iugu 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 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 références de factures Iugu et les remboursements, ainsi que les statuts de commande Awaiting Iugu payment et Iugu payment on hold, sont toujours conservés : les commandes payées auparavant peuvent donc encore être remboursées, et les notifications tardives restent rattachées après une réinstallation. Les commandes existantes conservent leurs notes de paiement et leurs identifiants de transaction.
Iugu est une marque de son propriétaire respectif. Ce module n'est ni affilié à Iugu ni approuvé par Iugu.