VibeFox Iugu for WooCommerce — Aide

Prérequis

WordPress: 6.0 ou ultérieur.

WooCommerce: 8.0 ou ultérieur, installé et activé. Sans WooCommerce, le plugin refuse de s'activer.

PHP: 8.0 ou ultérieur.

Devise de la boutique: réal brésilien (BRL). Iugu n'encaisse qu'en BRL. Le moyen de paiement est masqué lorsque la boutique, ou la commande de la page Pay for order, utilise une autre devise, ainsi que pour les montants 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 : le jeton détermine si les factures sont des tests ou de vraies factures. 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 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_iugu_gateway dans /wp-content/plugins/ par FTP.

2. Cliquez sur Activate.

3. Réglez la devise de la boutique sur réal brésilien (BRL) dans WooCommerce > Settings > General.

4. Ouvrez les réglages : WooCommerce > Settings > Payments > Iugu > Manage, ou cliquez sur Settings sous le nom du plugin sur la page Plugins.

5. Saisissez votre clé de licence VibeFox dans le bloc de licence en haut de la page et cliquez sur Activate.

6. Saisissez les jetons d'API de test et de production (voir Configuration), laissez Test mode activé, activez Enable / Disable et enregistrez.

7. Passez une commande de test et payez-la avec une carte de test Iugu. Une fois prêt, décochez Test mode.

Configuration

Tous les réglages se trouvent sur une seule page : WooCommerce > Settings > Payments > Iugu. Sous le titre de la passerelle, 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é au paiement) et lorsque la devise de la boutique n'est pas BRL. Dans la liste des moyens de paiement, Iugu est signalé comme nécessitant une configuration tant que le jeton du mode actif n'est pas saisi, et affiche un badge de mode test tant que ce mode est activé.

Général

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

Title: le nom du moyen de paiement affiché au client lors du paiement. Par défaut: Iugu.

Description: le texte affiché sous le moyen de paiement lors du paiement. Par défaut: Pay securely via Iugu. You will be redirected to complete your payment.

Identifiants 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 jeton de type "Live".

Test mode: Use the test API token (no real charges). Par défaut: on. Tant que le mode test est activé, le 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". Utilisé tant que le mode test est activé.

Live API token: le jeton d'API Iugu de type "Live" (production). Utilisé lorsque le mode test est désactivé. Gardez-le secret.

Notifications de paiement

Chaque facture demande à Iugu d'envoyer les changements de statut à l'URL de notification de votre boutique, affichée dans cette section des réglages. Elle ressemble à https://your-site/wc-api/webhook_wc_iugu/. Rien n'est à configurer dans Iugu. Un déclencheur (gatilho) supplémentaire à l'échelle 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 que la commande ne change.

Le plugin réagit aux événements Iugu pouvant modifier le statut d'une facture : invoice.status_changed, invoice.refund, invoice.released, invoice.dunning_action et invoices. Pour chacun, il relit la facture et applique son statut :

paid: la commande est marquée payée après contrôle du montant et de la devise.

authorized or in_analysis: le paiement par carte attend la capture ou est en cours d'analyse. La commande passe En attente.

partially_paid: la facture a été partiellement payée. La commande passe En attente.

expired: la facture a expiré sans paiement. La commande passe en Échec et le client peut payer à nouveau.

canceled: la facture a été annulée. La commande est annulée.

refunded: la facture a été remboursée dans Iugu. La commande passe en Remboursée.

chargeback: le titulaire de la carte a contesté le paiement. Une commande payée passe En attente.

Les autres événements et les factures qui n'appartiennent pas à une commande de cette boutique reçoivent la réponse OK et sont ignorés. Sans notifications, une commande n'est vérifiée que lorsque le client revient à la boutique depuis la page Iugu.

Avancé

Debug log: Log API requests and notifications dans WooCommerce > Status > Logs, source wcp_iugu_gateway, sans jetons ni données clients. Les erreurs sont toujours journalisées. Par défaut: off.

Delete Data on Uninstall: Remove the gateway settings and logs when the plugin is deleted. Par défaut: off.

Paiement

Le client choisit le moyen de paiement (par défaut Iugu) et passe la commande. Une adresse e-mail de facturation valide est requise. Le plugin crée une facture Iugu pour le total de la commande en BRL, avec une é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. Le nom et l'e-mail du client sont transmis à Iugu, ainsi que le CPF/CNPJ, le numéro de rue et le quartier issus des champs de « Brazilian Market on WooCommerce » au paiement, lorsqu'ils sont présents. Le téléphone et l'adresse ne sont transmis que dans le format accepté par Iugu (numéros de téléphone brésiliens, adresses brésiliennes avec un CEP à 8 chiffres).

Après le paiement, le client revient sur la page « Commande reçue » de votre boutique. La commande n'est marquée payée qu'après confirmation d'Iugu : la facture est lue depuis l'API Iugu lorsque le client revient et lorsque Iugu envoie une notification. Si le client a généré un code boleto ou PIX et est revenu avant de payer, la commande passe En attente jusqu'à ce qu'Iugu confirme le paiement. Le délai de commande non payée de WooCommerce n'annule pas les commandes dont la facture Iugu est encore ouverte.

Si la facture a été annulée ou a expiré et que la commande peut encore être payée, le client arrive sur la page Pay for order avec le message The Iugu invoice was not paid (it was canceled or has expired). You can pay the order again below. Lorsque le client paie à nouveau, le plugin le renvoie vers la même facture ouverte si le montant n'a pas changé. Sinon, il annule l'ancienne facture dans Iugu et en crée une nouvelle, afin qu'une commande ne puisse pas être payée deux fois via deux factures ouvertes. Si une ancienne facture est tout de même payée, le paiement reste rattaché à la commande.

Si Iugu ne peut pas créer la facture, le client voit un message bref, par exemple Iugu could not create the invoice: suivi de la raison et d'une invitation à vérifier les informations de facturation, ou Could not connect to Iugu. Please try again in a moment. La raison technique est ajoutée aux notes de commande et au journal.

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 ne gère que les paiements uniques. Il ne propose pas de formulaire de carte sur le site, de cartes enregistrées, d'abonnements ni de facturation récurrente, de carnês de paiement (carnê), de paiements fractionnés ni d'options de paiement en plusieurs fois : pour les paiements échelonnés, utilisez les réglages de la page Iugu. Les moyens de paiement proposés sur la page Iugu ne peuvent pas être choisis dans les réglages du plugin : tous les moyens activés dans votre compte Iugu sont proposés.

Commandes et remboursements

Statuts de commande

Pending payment: la facture a été créée et le client n'a pas encore payé.

Processing or Completed: Iugu a confirmé le paiement. WooCommerce applique le statut habituel d'une commande payée. La note de commande indique l'identifiant de la facture Iugu et le moyen de paiement (carte de crédit, boleto ou PIX). L'identifiant de transaction est l'identifiant de la facture Iugu ; sur l'écran de commande, il renvoie vers la facture dans Iugu.

On hold: le client a généré un boleto ou PIX et est revenu à la boutique (paiement en attente), le paiement par carte est autorisé mais pas encore capturé (capturez-le dans Iugu : la commande sera terminée dès qu'Iugu signalera la facture comme payée), le paiement est en cours d'analyse, la facture n'a été payée que partiellement, un litige (chargeback) a été ouvert, ou le montant ou la devise payés ne correspondaient pas à la commande. Un paiement arrivé après l'annulation de la commande la place aussi En attente plutôt que de la rouvrir silencieusement. Les notes de commande indiquent le cas.

Failed: la facture a expiré sans paiement. Le client peut payer à nouveau la commande.

Cancelled: la facture a été annulée dans Iugu.

Refunded: la facture ayant payé la commande a été remboursée dans Iugu.

Si une autre facture de la même commande est également payée, la commande n'est plus modifiée. Une note vous invite à rembourser le paiement en double dans Iugu.

Remboursements

Ouvrez la commande, cliquez sur Refund, saisissez le montant et cliquez sur Refund via Iugu. Le remboursement est envoyé avec le jeton du mode dans lequel la facture a été créée.

Credit card: remboursements totaux ou partiels.

PIX: remboursements totaux uniquement.

Boleto: ne peut pas être remboursé via Iugu. Restituez l'argent au client par virement bancaire, puis enregistrez le remboursement manuellement sans utiliser Refund via Iugu.

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 lorsque Iugu le confirme. Si Iugu refuse le remboursement ou ne le confirme pas, WooCommerce affiche l'erreur et aucun remboursement n'est enregistré. Un remboursement réussi est ajouté aux notes de commande avec l'identifiant de la facture et le motif.

Un remboursement total effectué dans le tableau de bord Iugu passe la commande en Remboursée. Les remboursements partiels effectués dans le tableau de bord ne sont pas importés.

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 > Iugu. 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, 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 l'emplacement dans votre compte vibefox.net.

Sans clé active, Iugu n'est pas affiché 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. Les gestionnaires connectés de la boutique voient toujours le moyen 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 fonctionnent.

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

Iugu n'apparaît pas au paiement: vérifiez que la licence est active, que Enable / Disable est activé et que le jeton du mode actif est défini : Test API token en mode test, Live API token en mode réel. La devise de la boutique doit être BRL et le total de la commande d'au moins R$ 1,00. La page des réglages affiche un avertissement lorsque le jeton ou la devise est incorrect.

Le paiement a abouti, mais la commande reste Pending payment: la notification d'Iugu n'a pas atteint votre boutique ou n'a pas pu être vérifiée. Activez le Debug log et consultez WooCommerce > Status > Logs, source wcp_iugu_gateway. Vérifiez que votre site est accessible depuis Internet à l'URL de notification affichée dans les réglages, et que le jeton du mode dans lequel la facture a été créée est toujours saisi. La commande est aussi vérifiée lorsque le client revient à la boutique après paiement.

Notification answers verification failed: la facture n'a pas pu être lue depuis l'API Iugu à ce moment-là, par exemple à cause d'une erreur réseau ou d'un jeton incorrect. Iugu renouvelle la notification.

Notification answers invalid invoice id: la notification ne contenait pas d'identifiant de facture valide. Rien n'est modifié.

La commande est On hold: lisez les notes de commande. Un boleto ou PIX n'est pas encore payé, un paiement par carte attend la capture, le paiement est en cours d'analyse, partiellement payé ou contesté, le montant payé ne correspondait pas à la commande, ou le paiement est arrivé après l'annulation de la commande.

The customer sees "Iugu payments are not available right now": le jeton d'API est absent ou incorrect. Vérifiez le jeton du mode actif.

Le remboursement échoue: lisez le message. Les paiements boleto ne peuvent pas être remboursés via Iugu, les paiements PIX ne peuvent être remboursés qu'en totalité, et seules les factures payées peuvent être remboursées. Si Iugu n'a pas confirmé le remboursement, vérifiez la facture dans Iugu avant de réessayer.

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é sur le nouveau domaine. Si le serveur de licences est injoignable, le plugin continue de fonctionner avec le dernier statut connu.

Les développeurs peuvent modifier la requête de facture, par exemple limiter les moyens de paiement avec payable_with, grâce au filtre wc_igu_invoice_data.

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é ; sinon, ils sont conservés pour une future réinstallation. Les commandes existantes conservent leurs notes de paiement et leurs identifiants de transaction.

Iugu est une marque déposée de son titulaire respectif. Ce plugin n'est ni affilié à Iugu ni approuvé par Iugu.