VibeFox PagSeguro 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). Le moyen de paiement n'est affiché que pour les paniers en BRL.

HTTPS : votre boutique doit être accessible depuis Internet en HTTPS pour que PagBank puisse envoyer les 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 de production ne fonctionnent que dans leur propre environnement.

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échargement terminé, cliquez sur Configure, ou trouvez plus tard VibeFox PagSeguro Gateway dans la liste des modules et cliquez sur Configure.

3. Saisissez votre clé de licence VibeFox dans License key, dans le bloc de licence en haut de la page Configure, puis cliquez sur Activate (voir Clé de licence).

4. Saisissez le jeton sandbox et, pour encaisser de vrais paiements, le jeton de production.

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

À l'installation, le module crée deux statuts de commande, Awaiting PagBank payment et PagBank 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 ; la devise BRL doit rester autorisée pour le module.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox PagSeguro Gateway > Configure. Chaque section a son propre bouton Save, qui enregistre la page entière. Au-dessus des champs, la page affiche 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 checkout) et lorsque la devise par défaut de la boutique n'est pas BRL (le moyen de paiement n'est alors pas proposé pour les paniers dans d'autres devises).

PagSeguro / PagBank

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 checkout. C'est aussi le nom du moyen de paiement enregistré dans la commande. Par défaut : PagSeguro / PagBank. Obligatoire.

Description : le texte affiché sous le moyen de paiement au checkout. 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 renvoie 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 les clients voient SANDBOX MODE — Using test environment. No real charges. sous le moyen de 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. Utilisé tant que le mode sandbox est activé.

Production token : le jeton de production PagBank (Bearer). Utilisé lorsque le mode sandbox est désactivé. Gardez-le secret.

Les jetons enregistrés ne sont jamais réaffichés. Le champ reste vide et affiche Saved — leave empty to keep it. Ne saisissez une nouvelle valeur que pour 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 paiement indique à PagBank où signaler les changements de statut, il n'y a donc rien à configurer dans PagBank. La section affiche l'URL. Avec les URL personnalisées, elle ressemble à ceci : https://your-shop/module/wcp_pagseguro_gateway/webhook. L'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 dans lequel le paiement a été créé ; une signature invalide est rejetée. Le corps de la notification n'est jamais considéré comme fiable : le module lit toujours le paiement et la commande PagBank depuis l'API PagBank (statut, montant, devise) avant de créer ou de modifier une commande. Sans notifications, la commande est créée lorsque le client revient dans la boutique après avoir payé.

Avancé

Debug log : Log API requests and notifications écrit les détails dans logs/wc_psg_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les journaux ne contiennent ni jeton ni donnée client. Les erreurs sont toujours journalisées. 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 les réglages de la passerelle et le journal. Les commandes, leurs références PagBank (nécessaires aux remboursements) et les statuts de commande sont toujours conservés. Par défaut : désactivé.

Processus de paiement

À l'étape de paiement, le client choisit le moyen de paiement (par défaut PagSeguro / PagBank) et confirme. Le module crée un paiement PagBank pour le total du panier en BRL, sous la forme d'un seul article, Order # suivi du numéro du panier 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 le CNPJ saisi dans le champ Identification number ou VAT number de l'adresse, 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 au bout de 120 minutes. À ce stade, aucune commande n'existe encore.

Après le paiement, le client revient dans votre boutique. La commande n'est marquée comme payée qu'après confirmation de PagBank : le module lit le paiement depuis l'API PagBank lorsque la notification arrive ou lorsque le client revient, et un simple retour ne marque jamais une commande comme payée. La commande est alors créée et le client voit la page de confirmation de commande avec Your payment with PagBank has been received. Pour un boleto ou un PIX généré, ou un paiement en cours d'analyse, la page affiche Your PagBank payment is awaiting confirmation (boleto / PIX / analysis). The order will be confirmed as soon as PagBank reports the payment. Si ce paiement est refusé ou annulé plus tard, la page affiche Your PagBank payment was not completed. Please contact us about this order. Si PagBank n'a pas encore confirmé le paiement lorsque le client revient, une page Payment confirmation affiche We are confirming your payment with PagBank. The order will be updated automatically — please do not pay again. avec un bouton Check again.

Si le paiement n'a pas abouti, le client revient au checkout 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. Le panier est conservé. Si une commande en attente d'un boleto ou d'un PIX a été annulée, le client voit 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 payé. Un paiement effectué auparavant sur la page précédente compte toujours pour le panier, et la commande est créée au lieu d'un nouveau paiement.

Si PagBank ne peut pas démarrer le paiement, le client reste au checkout avec un bref 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 technique est inscrite dans le journal.

Les notifications fonctionnent pendant que la boutique est en mode maintenance et ne sont pas bloquées par la restriction géographique de votre boutique.

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

Commandes et remboursements

Statuts de commande

Pas encore de commande : le client a été envoyé vers PagBank et n'a pas payé, la carte a été refusée ou la page de paiement a expiré. Seul le panier existe, et le client peut payer à nouveau.

Payment accepted : le paiement a été confirmé avec le montant et la devise attendus. Le paiement est enregistré avec le charge ID PagBank comme ID de transaction, et une note indique le montant, le moyen de paiement et le charge ID.

Awaiting PagBank payment : un boleto ou un PIX a été généré et attend d'être payé, ou le paiement est en cours d'analyse. La commande passe en Payment accepted lorsque PagBank indique que le paiement est effectué.

PagBank payment on hold : PagBank a signalé un montant ou une devise différent de ceux du panier (par exemple, le panier a été modifié après la création de la page de paiement), un paiement est arrivé après l'annulation de la commande (vérifiez le stock, puis finalisez la commande ou remboursez le paiement dans PagBank), ou un paiement par carte a été autorisé mais non capturé (capturez-le dans PagBank). La note l'explique. L'argent réellement reçu est enregistré sur la commande.

Payment error : un paiement en attente ou en cours d'analyse a été refusé.

Canceled : un paiement en attente, par exemple un boleto ou un PIX expiré, a été annulé.

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

Chaque statut PagBank est appliqué une seule fois, de sorte que les notifications ou les retours répétés n'ajoutent ni notes ni changements de statut. Si un second paiement arrive pour une commande déjà payée, la commande n'est pas modifiée et une note vous invite à rembourser le doublon dans PagBank.

Bloc « PagBank payment »

La page de commande affiche un bloc PagBank payment avec le checkout PagBank, les identifiants PagBank de la commande et du charge ID, le moyen de paiement, le statut, le montant payé et remboursé, un badge Sandbox pour les paiements sandbox, l'historique des remboursements et les PagBank notes de la commande.

Remboursements

Dans le bloc PagBank payment, saisissez le montant (le montant non encore remboursé est pré-rempli), éventuellement un motif, puis cliquez sur Refund via PagBank. Confirmez la question Refund this amount through PagBank? This cannot be undone. Les remboursements totaux et partiels sont pris en charge. Vous avez besoin du droit de modifier les commandes ; l'accès aux pages Modules n'est pas nécessaire. La limite est le montant débité par PagBank : après un écart de montant, vous pouvez donc rembourser jusqu'à ce que le client a réellement payé, et non le total de la commande. Le remboursement est envoyé dans l'environnement et avec le jeton avec lesquels le paiement a été effectué. Un remboursement n'est enregistré que lorsque PagBank le confirme ; sinon le bloc affiche l'erreur, par exemple PagBank refund failed: ... ou PagBank did not confirm the refund, et rien n'est enregistré. Les remboursements des paiements boleto et les remboursements partiels des PIX suivent les règles de PagBank. Un remboursement réussi est ajouté à l'historique des remboursements et aux notes, avec le charge ID. Un remboursement total place la commande en Refunded ; un remboursement partiel ne modifie pas le statut. Les remboursements sont disponibles une fois que PagBank a indiqué que le paiement est effectué.

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

Les remboursements effectués depuis le tableau de bord PagBank sont pris en compte à la notification suivante : un remboursement total place la commande en Refunded, un remboursement partiel ajoute une note avec le montant remboursé, et vous pouvez ajouter le remboursement à la commande manuellement.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox PagSeguro Gateway est le premier bloc de Modules > Module Manager > VibeFox PagSeguro 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) 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-pagseguro 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, PagBank n'est pas proposé aux clients au checkout. Si un paiement est lancé malgré tout, 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 vous est donc masqué également. Vous pouvez configurer le module avant d'acheter une clé, mais pas le tester au checkout. Un rappel apparaît dans Modules > Module Manager, sous 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. Aucun cron job n'est nécessaire. La désinstallation ou la réinitialisation du module supprime toujours la clé de licence et le statut de la licence.

Dépannage

PagBank n'apparaît pas au checkout : 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 du panier est BRL. La page de réglages affiche un avertissement lorsque le jeton est manquant ou que la devise de la boutique n'est pas BRL. Dans Payment > Preferences, vérifiez que le module est autorisé pour BRL, le pays du client et le groupe de clients.

Le paiement a abouti, mais aucune commande n'a été créée : PagBank n'a pas encore signalé le paiement et le client n'est pas revenu dans la boutique. La commande est créée dès que la notification arrive. Vérifiez que votre boutique est accessible depuis Internet en HTTPS à l'adresse de la Notification URL, et activez le Debug log pour voir les notifications.

La notification répond Invalid signature : le x-authenticity-token ne correspond pas au jeton de l'environnement dans lequel le paiement a été effectué, ou ce jeton n'est pas enregistré. Vérifiez que le bon jeton figure 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 du paiement est manquant, ou le panier était en cours de traitement par une autre requête au même moment. PagBank renouvelle la notification.

La notification répond Order not found : la notification concerne un panier qui n'a pas été payé avec ce module dans cette boutique. Rien n'est modifié.

Le client voit PagBank payments are temporarily unavailable. Please choose another payment method.: le jeton du mode actuel est manquant ou PagBank l'a rejeté.

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

La commande est en PagBank payment on hold : lisez les notes du bloc PagBank payment (voir Statuts de commande), comparez les montants dans PagBank, puis traitez la commande ou remboursez le paiement.

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 manquant ou rejeté. Saisissez le bon jeton et réessayez.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox PagSeguro 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 future réinstallation. Les paiements et remboursements PagBank des commandes ainsi que les statuts de commande Awaiting PagBank payment et PagBank payment on hold sont toujours conservés, de sorte que les commandes payées auparavant peuvent encore être remboursées après une réinstallation. Les commandes existantes conservent leurs notes de paiement et leurs ID de transaction.

PagSeguro et PagBank sont des marques déposées de leurs titulaires respectifs. Ce module n'est pas affilié à PagSeguro ni à PagBank et n'est pas approuvé par eux.