VibeFox PagSeguro for WooCommerce — Aide

Prérequis

WordPress : 6.0 ou ultérieur.

WooCommerce : 8.0 ou ultérieur, installé et actif. L'extension refuse de s'activer sans lui.

PHP : 8.0 ou ultérieur.

Devise : réal brésilien (BRL). Le moyen de paiement n'apparaît pas au moment du paiement lorsque la devise de la boutique (ou, sur la page Pay for order, celle de la commande) n'est pas BRL.

HTTPS : votre site doit être accessible depuis Internet en HTTPS pour que PagBank puisse transmettre ses notifications de paiement.

Compte PagBank : un jeton de production pour les paiements réels et un jeton sandbox pour les tests. Production : connectez-vous à votre compte PagBank, ouvrez Venda online > Integrações et cliquez sur Gerar token ; PagBank envoie le jeton par e-mail. Sandbox : créez un compte sandbox dans le portail développeurs de PagBank et copiez son jeton. Les jetons sandbox et production ne fonctionnent que dans leur propre environnement.

Clé de licence VibeFox : achetée sur vibefox.net. Une clé fonctionne pour un seul domaine.

Installation

1. Dans WordPress, allez dans Plugins > Add New > Upload Plugin, choisissez le fichier ZIP de l'extension et cliquez sur Install Now. Vous pouvez aussi envoyer le dossier wcp_pagseguro_gateway dans /wp-content/plugins/ par FTP.

2. Cliquez sur Activate.

3. Ouvrez les réglages : WooCommerce > Settings > Payments > PagSeguro / PagBank > Manage, ou cliquez sur Settings sous le nom de l'extension 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. Saisissez le jeton sandbox et, pour encaisser de vrais paiements, le jeton de production.

6. Activez Enable / Disable et enregistrez. Effectuez des paiements de test avec Sandbox Mode activé, puis désactivez-le pour encaisser de vrais paiements.

Configuration

Tous les réglages se trouvent sur une seule page : WooCommerce > Settings > Payments > PagSeguro / PagBank. Sous le titre, la page indique le mode actuel : SANDBOX MODE (les paiements sont créés dans le sandbox PagBank, sans débit réel) ou LIVE (les paiements sont créés avec le jeton de production). Elle vous avertit lorsque le jeton du mode actuel est manquant (le moyen de paiement est alors masqué au moment du paiement) et lorsque la devise de la boutique n'est pas BRL. Dans la liste des moyens de paiement, PagBank est signalé comme nécessitant une configuration tant que le jeton du mode actuel n'est pas saisi, et un badge de mode test s'affiche tant que le mode sandbox est activé.

Général

Enable / Disable : Enable PagSeguro/PagBank 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 du paiement. Par défaut : PagSeguro / PagBank.

Description : le texte affiché sous le moyen de paiement au moment du paiement. Par défaut : Pay securely via PagSeguro/PagBank. You will be redirected to complete your payment.

Compte PagBank

Cette section explique où obtenir les jetons et fournit des liens vers votre compte PagBank ainsi que vers la page PagBank consacrée aux jetons.

Sandbox Mode : Enable sandbox/test mode (no real charges). Les nouveaux paiements sont envoyés au sandbox PagBank avec le jeton sandbox, et une mention SANDBOX MODE s'affiche au moment du paiement. Les vérifications de statut et les remboursements d'une commande utilisent toujours l'environnement et le jeton avec lesquels son paiement a été créé. Par défaut : activé.

Sandbox token : le jeton sandbox PagBank. Il est utilisé tant que le mode sandbox est activé.

Production token : le jeton de production PagBank. Il est utilisé lorsque le mode sandbox est désactivé. Gardez-le secret.

Le jeton unique de la version 1.0 est transféré automatiquement : si le mode sandbox était activé, il devient le jeton sandbox ; sinon, il reste le jeton de production.

Notifications de paiement

Chaque paiement indique à PagBank où transmettre les changements de statut ; il n'y a donc rien à configurer dans PagBank. La section affiche l'URL de notification. Elle ressemble à ceci : https://your-site/wc-api/webhook_wc_pagseguro/. Cette adresse doit être accessible depuis Internet en HTTPS.

Les notifications qui contiennent un en-tête x-authenticity-token sont vérifiées avec le jeton de l'environnement de la commande ; une signature invalide est rejetée. Le contenu de la notification n'est jamais considéré comme fiable : l'extension lit toujours le paiement et la commande PagBank depuis l'API PagBank (statut, montant et devise) avant de modifier la commande.

Avancé

Debug log : Log API requests and notifications écrit les détails dans WooCommerce > Status > Logs, source wcp_pagseguro_gateway. Les erreurs sont toujours journalisées. Les journaux ne contiennent ni jetons ni données clients. Par défaut : désactivé.

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

Paiement

Le client choisit le moyen de paiement (par défaut PagSeguro / PagBank) et valide sa commande. L'extension crée un paiement PagBank pour le total exact de la commande en BRL, sous la forme d'un seul article, Order # suivi du numéro de commande et du nom de votre boutique, puis envoie le client sur la page de paiement de PagBank. Le nom et l'e-mail du client, le CPF ou CNPJ issu des champs de l'extension Brazilian Market on WooCommerce ainsi qu'un numéro de téléphone brésilien sont renseignés lorsque la boutique les possède ; le client peut les compléter ou les corriger sur la page PagBank. Le client paie avec les moyens de paiement activés dans votre compte PagBank, par exemple carte de crédit, PIX ou boleto.

La page de paiement expire 5 minutes avant que le délai Hold stock de WooCommerce n'annule la commande impayée (au minimum 10 minutes), ou au bout de 120 minutes si le stock n'est pas réservé.

Après le paiement, le client revient sur la boutique. Ce retour est vérifié de la même façon qu'une notification : l'extension lit le paiement via l'API PagBank, et un simple retour ne marque jamais une commande comme payée. Une commande payée, ou un paiement en attente (boleto, PIX, analyse), mène à la page de confirmation de commande ; la commande est confirmée par la notification si PagBank ne l'a pas encore signalée.

Si le paiement n'a pas abouti, le client revient à la page Pay for order avec The PagBank payment was not completed. You can pay the order again below., The PagBank payment page has expired. You can pay the order again below. ou The payment was declined by PagBank. Please try again with another card or payment method. Si le paiement a été annulé et la commande avec lui, le client est renvoyé au panier avec The PagBank payment was cancelled, so the order was cancelled.

Lorsque le client paie à nouveau, le paiement PagBank ouvert est réutilisé si le montant et l'environnement sont identiques et s'il n'expire pas dans les 10 minutes. Sinon, le paiement précédent est désactivé et ne peut plus être réglé. Un paiement effectué auparavant sur la page précédente compte toujours pour la commande.

Si PagBank ne peut pas démarrer le paiement, le client voit un court message, par exemple PagBank did not accept your billing details (CPF/CNPJ). Please check them and try again. ou Could not connect to PagBank. Please try again in a moment. La raison donnée par PagBank est ajoutée aux notes de la commande.

Le moyen de paiement fonctionne sur le paiement classique, sur le bloc Paiement et sur la page Pay for order. Il est compatible avec le stockage haute performance des commandes de WooCommerce (HPOS).

L'extension ne propose ni formulaire de carte sur le site, ni cartes enregistrées, ni abonnements ou paiements récurrents, ni paiements fractionnés ou places de marché. Les moyens de paiement et les versements en plusieurs fois sont ceux configurés dans votre compte PagBank.

Commandes et remboursements

Statuts de commande

Pending payment : le client a été envoyé vers PagBank et n'a pas encore payé. Une note indique l'ID du paiement PagBank et l'environnement. Si la page de paiement expire sans règlement, une note le signale et le statut ne change pas.

Processing : le paiement est confirmé. C'est le statut standard de WooCommerce après paiement ; les commandes ne contenant que des produits téléchargeables virtuels passent en « Terminée ». La note de commande indique le montant, le moyen de paiement et l'ID de débit PagBank, qui est aussi l'ID de transaction de la commande.

On hold : un boleto ou un PIX a été généré et attend d'être réglé ; le paiement est en cours d'analyse ; un paiement par carte a été autorisé mais pas capturé (capturez-le dans PagBank) ; le montant ou la devise payés ne correspondent pas à la commande ; ou un paiement est arrivé après que WooCommerce a annulé la commande impayée (vérifiez le stock, puis finalisez la commande ou remboursez le paiement dans PagBank). La note de commande explique la situation.

Failed : le paiement a été refusé. Le client peut payer à nouveau depuis la page Pay for order.

Cancelled : le paiement a été annulé, par exemple un boleto ou un PIX expiré.

Refunded : le paiement a été entièrement remboursé depuis le tableau de bord PagBank.

Chaque statut PagBank n'est appliqué qu'une seule fois : les notifications ou retours répétés n'ajoutent donc ni notes, ni e-mails, ni décrémentations de stock. Si un second paiement arrive pour une commande déjà payée, une note vous invite à le rembourser dans PagBank.

Remboursements

Ouvrez la commande, cliquez sur Refund, saisissez le montant et cliquez sur Refund via PagSeguro / PagBank (le bouton reprend le titre de votre moyen de paiement). Les remboursements totaux et partiels sont pris en charge. Le remboursement est envoyé dans l'environnement et avec le jeton utilisés pour le paiement. Un remboursement n'est enregistré que lorsque PagBank le confirme ; sinon, WooCommerce affiche l'erreur, par exemple PagBank refund failed: ... ou PagBank did not confirm the refund, et rien n'est enregistré. Les remboursements de paiements boleto et les remboursements partiels de PIX suivent les règles de PagBank. Un remboursement réussi est ajouté aux notes de commande avec l'ID de débit.

Les remboursements effectués dans le tableau de bord PagBank ne sont pas importés comme lignes de remboursement WooCommerce. Un remboursement total place la commande en « Remboursée » ; un remboursement partiel ajoute une note indiquant le montant remboursé, et vous pouvez ajouter le remboursement à la commande manuellement.

Clé de licence

L'extension fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence se trouve en haut de WooCommerce > Settings > Payments > PagSeguro / PagBank. 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 pour un seul domaine. Retirer la clé d'un site ne libère pas l'emplacement de domaine correspondant ; libérez-le dans votre compte vibefox.net.

Sans clé active, PagBank 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 de la boutique connectés voient toujours le moyen de paiement, marqué (unlicensed — visible to admins only), afin que vous puissiez configurer et tester l'extension avant d'acheter une clé. Un rappel apparaît sur la page Plugins et sur les pages WooCommerce. Les commandes existantes ne sont pas concernées : les paiements déjà lancés sont toujours confirmés et les remboursements fonctionnent.

Lorsqu'une licence expire, l'extension 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

PagBank n'apparaît pas au moment du paiement : vérifiez que la licence est active, que Enable / Disable est activé, que le jeton du mode actuel est renseigné (Sandbox token en mode sandbox, Production token en mode live) et que la devise de la boutique est BRL. La page des réglages affiche un avertissement dans chacun de ces cas.

Le paiement a abouti, mais la commande reste « En attente de paiement » : PagBank n'a pas encore signalé le paiement et le client n'est pas revenu sur la boutique. La commande est mise à jour dès que la notification arrive. Vérifiez que votre site est accessible depuis Internet en HTTPS, et consultez WooCommerce > Status > Logs, source wcp_pagseguro_gateway.

La notification répond Invalid signature : le x-authenticity-token ne correspond pas au jeton de l'environnement dans lequel la commande a été payée. Vérifiez que le bon jeton est saisi dans les réglages.

La notification répond Verification failed, retry later : l'API PagBank n'a pas pu être jointe, le jeton de l'environnement de la commande est absent, ou la commande était en cours de mise à jour par une autre requête au même moment. PagBank renouvelle la notification.

La notification répond Order not found : la commande n'existe pas dans cette boutique ou a été payée avec un autre moyen de paiement. Rien n'est modifié.

Le client voit This order is already being processed : une notification ou le retour du client était en train de mettre à jour la commande au même moment. Le client peut réessayer dans un instant.

Le client voit PagBank payments are temporarily unavailable : le jeton du mode actuel est absent ou PagBank l'a refusé.

Le client voit PagSeguro/PagBank only accepts payments in Brazilian Real (BRL) : la commande est dans une autre devise.

La commande est On hold avec la note Amount/currency does not match : PagBank a signalé un paiement dont le montant ou la devise diffère du total de la commande, par exemple parce que la commande a été modifiée après la création de la page de paiement. Comparez les montants dans PagBank, puis finalisez ou remboursez la commande manuellement.

Le remboursement échoue avec un message concernant le jeton : le paiement a été effectué en sandbox ou en production, et le jeton de cet environnement est absent ou refusé. Saisissez le bon jeton et réessayez.

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, l'extension continue de fonctionner avec le dernier statut connu.

Désinstallation

Désactiver l'extension conserve toutes les données. Pour la supprimer, désactivez-la puis supprimez-la sur la page Plugins. La clé de licence et le statut de licence de cette extension sont toujours supprimés. Les réglages de la passerelle, les autres options de l'extension et ses journaux ne sont supprimés que si Delete Data on Uninstall était activé. Sinon, ils restent en place pour une réinstallation ultérieure. Les commandes existantes conservent leurs notes de paiement, leurs ID de transaction et leurs données PagBank.

PagSeguro et PagBank sont des marques déposées de leur titulaire respectif. Cette extension n'est ni affiliée ni approuvée par PagSeguro ou PagBank.