VibeFox Pagar.me 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 est masqué pour les paniers dans toute autre devise.

Compte Pagar.me : vous avez besoin des clés secrètes de votre compte Pagar.me : la clé de test (sk_test_...) et, pour passer en production, la clé live (sk_...). Elles se trouvent dans le tableau de bord Pagar.me, sous Development > Keys. Seules les clés secrètes sont utilisées ; la clé publique (pk_...) n'est pas nécessaire. Seuls les moyens de paiement activés dans votre compte Pagar.me peuvent être proposés.

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 retrouvez plus tard VibeFox Pagar.me 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 la clé secrète de test et, lorsque vous passerez en production, la clé secrète live.

5. Créez le webhook dans le tableau de bord Pagar.me avec l'URL affichée dans les réglages (voir Configuration).

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

À l'installation, le module crée deux statuts de commande : Awaiting Pagar.me payment et Pagar.me 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.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox Pagar.me 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 : TEST MODE (les paiements sont créés avec la clé secrète de test, sans débit réel) ou LIVE. Elle vous avertit lorsque la clé secrète du mode actuel est absente (le moyen de paiement est alors masqué au paiement), lorsque la clé de test ne commence pas par sk_test_, lorsque la clé live ne commence pas par sk_ ou est une clé de test, et lorsque la devise par défaut de la boutique n'est pas BRL.

Pagar.me

Enable / Disable : Enable Pagar.me payments active ou désactive le moyen de paiement. Par défaut : désactivé.

Title : le nom du moyen de paiement que voit le client au paiement. C'est aussi le nom du moyen de paiement enregistré dans la commande. Par défaut : Pagar.me. Obligatoire.

Description : le texte affiché sous le moyen de paiement au paiement. Par défaut : Pay securely via Pagar.me (credit card, PIX or boleto). You will be redirected to complete your payment.

Clés API

Copiez les clés secrètes depuis le tableau de bord Pagar.me : Development > Keys. Pagar.me utilise une seule adresse d'API pour les paiements de test et les paiements live ; c'est la clé qui détermine si un paiement est un test ou un paiement réel.

Test mode : utilise la clé secrète de test, sans débit réel. Tant qu'il est activé, les clients voient TEST MODE — Use test credentials. No real charges. sous le moyen de paiement. Les vérifications de statut et les remboursements d'une commande utilisent toujours la clé du mode dans lequel son paiement a été créé. Par défaut : activé.

Test secret key : la clé secrète de test Pagar.me (sk_test_...). Elle est utilisée tant que le mode test est activé.

Live secret key : la clé secrète live Pagar.me (sk_...). Elle est utilisée lorsque le mode test est désactivé. Gardez-la secrète.

Les clés enregistrées ne sont plus jamais affichées. Le champ reste vide et affiche Saved — leave empty to keep it. Ne saisissez une nouvelle valeur que pour la modifier.

Clear saved secret keys : cochez une clé et cliquez sur Save pour la supprimer. Un champ vide conserve la valeur enregistrée.

Page de paiement

Payment methods : les moyens proposés sur la page de paiement Pagar.me. Ne choisissez que des moyens activés dans votre compte Pagar.me. Si aucun n'est coché, les moyens par défaut sont utilisés. Par défaut : Credit card, PIX and Boleto.

Credit card : autorisée et capturée immédiatement.

PIX : paiement instantané par PIX.

Boleto : boleto bancaire ; la commande reste en Awaiting Pagar.me payment jusqu'à son paiement.

Debit card : paiement par carte de débit.

Boleto due in (days) : le nombre de jours avant l'échéance du boleto, de 1 à 30. La commande reste en Awaiting Pagar.me payment jusqu'à ce que Pagar.me confirme le paiement. Par défaut : 3. Une autre valeur est refusée à l'enregistrement avec Boleto due in (days): enter a number from 1 to 30.

Notifications de paiement (webhook)

Dans le tableau de bord Pagar.me, ouvrez Settings > Webhooks et créez un webhook avec l'URL affichée sous Webhook URL dans cette section. Avec les URL conviviales, elle ressemble à https://your-shop/module/wcp_pagarme_gateway/webhook, éventuellement avec un code de langue comme /en/. Copiez-la exactement telle que les réglages l'affichent.

Sélectionnez ces événements (ils sont aussi listés dans cette section) :

order.paid : la commande Pagar.me a été payée.

order.payment_failed : le paiement a échoué.

order.canceled : la commande Pagar.me a été annulée ou a expiré.

charge.paid : un débit a été payé, par exemple un PIX ou un boleto réglé plus tard.

charge.pending : un débit attend le paiement, par exemple un boleto émis.

charge.refunded : un débit a été remboursé.

charge.chargedback : le titulaire de la carte a contesté un paiement.

Le webhook ne nécessite ni mot de passe ni signature. Son contenu n'est jamais considéré comme fiable : la boutique n'en retient que l'ID de la commande Pagar.me et lit cette commande depuis l'API de Pagar.me avec la clé du mode dans lequel elle a été créée. Les notifications concernant les commandes d'autres boutiques du même compte Pagar.me sont ignorées. Sans le webhook, les paiements PIX et boleto effectués plus tard ne sont confirmés que lorsque le client revient dans la boutique.

Avancé

Debug log : enregistre les requêtes API et les notifications dans logs/wc_pgm_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les erreurs et avertissements sont toujours enregistrés. Les clés et les données clients ne sont pas 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 données de paiement Pagar.me (nécessaires aux remboursements) et les statuts de commande sont conservés. Par défaut : désactivé.

Paiement

À l'étape de paiement, le client choisit le moyen de paiement (par défaut Pagar.me) et confirme. Une adresse e-mail valide est requise. Le module crée une commande Pagar.me pour le total du panier en BRL, avec les lignes du panier, la livraison et l'emballage cadeau (ou une seule ligne Order # avec le numéro du panier lorsque le panier comporte des remises), puis envoie le client sur la page de paiement Pagar.me. Aucune commande n'existe encore dans votre boutique à ce stade.

Le nom et l'e-mail du client sont transmis à Pagar.me. Le CPF ou le CNPJ est repris dans le champ Identification number de l'adresse, ou dans VAT number ; un numéro de téléphone mobile brésilien est également transmis. L'adresse de facturation n'est transmise que pour une adresse brésilienne avec un CEP à 8 chiffres et un État. PrestaShop ne fournit pas les États brésiliens par défaut : le client saisit donc généralement son adresse sur la page Pagar.me. Sans CPF ou CNPJ, le client le saisit également là-bas.

Après le paiement, le client revient dans votre boutique. La commande n'est marquée comme payée qu'après confirmation de Pagar.me : la boutique lit la commande Pagar.me depuis l'API, et le montant payé et la devise doivent correspondre au panier. Un paiement par carte, PIX ou boleto réglé crée la commande en Payment accepted, et le client voit la page standard de confirmation de commande avec Your payment with Pagar.me has been received. Un PIX ou un boleto émis mais non encore payé crée la commande en Awaiting Pagar.me payment, et la page affiche Your Pagar.me payment is awaiting confirmation (PIX / boleto). The order will be confirmed as soon as Pagar.me reports the payment. Chaque retour ultérieur relit la commande Pagar.me, de sorte qu'un PIX ou un boleto payé entre-temps est pris en compte même si le webhook n'est pas arrivé. Si le paiement d'une telle commande a échoué ou expiré, la page affiche Your Pagar.me payment was not completed. Please contact us about this order.

Si le client revient sans avoir payé, il retrouve le paiement avec le message The Pagar.me payment was not completed. You can pay the order below. Si le paiement a été refusé ou annulé, le message est The Pagar.me payment was declined or canceled. You can try again below. Le panier est conservé. Si la commande existe déjà et que son paiement a échoué ou expiré, le message est The Pagar.me payment of your order was declined, canceled or has expired. Please place a new order or contact us. Si Pagar.me est injoignable, une page Payment confirmation demande au client de ne pas payer à nouveau et propose Check again et Back to checkout.

Lorsque le client paie à nouveau, la page de paiement Pagar.me ouverte est réutilisée si le montant et le mode sont identiques ; sinon elle est fermée chez Pagar.me avant qu'une nouvelle ne soit créée. Si la tentative précédente a été payée entre-temps, ou si son PIX ou son boleto attend encore le paiement, la commande est créée sans nouveau paiement. Si la page précédente ne peut pas être fermée, elle reste rattachée au panier, de sorte qu'un paiement effectué sur cette page est tout de même enregistré.

Si Pagar.me ne peut pas démarrer le paiement, le client reste au paiement avec un bref message, par exemple Could not connect to Pagar.me. Please try again in a moment., ou avec le message de Pagar.me concernant des données de facturation non valides. La raison technique est écrite dans le journal.

Le webhook fonctionne lorsque la boutique est en mode maintenance et n'est pas bloqué par la restriction géographique de votre boutique.

Le module n'inclut ni formulaire de carte dans votre paiement, ni cartes enregistrées, ni abonnements ou paiements récurrents, ni règles de versements, ni paiements fractionnés (marketplace), ni paiements par carte en autorisation seule, ni intégration à Pagar.me Hub.

Commandes et remboursements

Statuts de commande

No order yet : le client a été envoyé chez Pagar.me et n'a encore ni payé ni émis de PIX ou de boleto. Seul le panier existe.

Payment accepted : le paiement a été confirmé. Il est enregistré avec l'ID de commande Pagar.me (or_...) comme ID de transaction, et une note indique la commande Pagar.me et le moyen de paiement.

Awaiting Pagar.me payment : un PIX ou un boleto a été émis (ou un paiement par carte est en cours d'analyse) et attend le paiement. La commande passe en Payment accepted lorsque Pagar.me confirme le paiement.

Pagar.me payment on hold : le boleto n'a été payé que partiellement ; ou le montant payé ou la devise diffère de la commande (par exemple, le panier a été modifié après le début du paiement) ; ou le paiement est arrivé après l'annulation de la commande ; ou une contestation a été ouverte sur une commande payée. La note l'explique. Vérifiez la commande, puis traitez-la ou remboursez le paiement.

Payment error : le paiement d'une commande en attente ou bloquée a échoué, ou sa commande Pagar.me a été annulée ou a expiré (par exemple un boleto non payé). Si Pagar.me signale un paiement plus tard, la commande passe tout de même en Payment accepted.

Refunded : le paiement a été entièrement remboursé par le module, ou remboursé ou annulé dans Pagar.me.

Chaque statut Pagar.me est appliqué une seule fois : les webhooks ou retours répétés n'ajoutent ni notes ni paiements. Si une seconde commande Pagar.me du même panier est payée, une note vous invite à rembourser le doublon depuis le tableau de bord Pagar.me.

Bloc de paiement Pagar.me

La page de la commande affiche un bloc Pagar.me payment avec l'ID de la commande Pagar.me et les ID des débits, le moyen de paiement, le statut, le montant payé et remboursé, un badge Test mode pour les paiements de test, l'historique des remboursements et les Pagar.me notes de la commande.

Remboursements

Dans le bloc Pagar.me payment, saisissez le montant (le montant non encore remboursé est pré-rempli), éventuellement un motif, puis cliquez sur Refund via Pagar.me. Confirmez la question Refund this amount through Pagar.me? This cannot be undone. Les remboursements totaux et partiels des paiements par carte et PIX sont pris en charge. Vous devez disposer du droit de modifier les commandes. Vous pouvez rembourser jusqu'au montant effectivement encaissé par Pagar.me : après un écart de montant, la limite est donc ce que le client a payé, et non le total de la commande. Le remboursement est envoyé avec la clé du mode dans lequel le paiement a été effectué, cette clé secrète doit donc être renseignée. Un remboursement n'est enregistré que lorsque Pagar.me le confirme ; sinon, le bloc affiche l'erreur, par exemple Pagar.me refused the refund: ... ou Pagar.me did not confirm the refund, et aucun remboursement n'est enregistré. Un remboursement réussi est ajouté à l'historique des remboursements et aux notes, avec l'ID du débit. Un remboursement total place la commande en Refunded. Un remboursement partiel ne modifie pas le statut. Les remboursements sont disponibles une fois que Pagar.me a signalé le paiement.

Les paiements par boleto ne peuvent être remboursés que sur le compte bancaire du client. Remboursez-les depuis le tableau de bord Pagar.me, puis enregistrez le remboursement manuellement dans PrestaShop.

Le module ne crée pas d'avoirs (credit slips). Les boutons de remboursement standard de PrestaShop sur la page de la commande ne renvoient pas d'argent via Pagar.me.

Un remboursement total ou une annulation effectué depuis le tableau de bord Pagar.me parvient par webhook, place la commande en Refunded et ajoute une note. Une contestation ajoute une note et place une commande payée en Pagar.me payment on hold.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Pagar.me Gateway est le premier bloc de Modules > Module Manager > VibeFox Pagar.me 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-pagarme 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, Pagar.me n'est pas affiché aux clients au paiement. 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 paiement. Un rappel apparaît dans Modules > Module Manager, sous l'onglet Alerts. 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, 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

Pagar.me n'apparaît pas au paiement : vérifiez que la licence est active, que Enable / Disable est activé, que la clé secrète du mode actuel est renseignée (Test secret key en mode test, Live secret key en mode live) et que la devise du panier est BRL. La page des réglages affiche un avertissement lorsque la clé manque. 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 ou la commande reste en Awaiting Pagar.me payment : le webhook ne fonctionne pas. Dans le tableau de bord Pagar.me, vérifiez que le webhook existe pour le compte et le mode utilisés, que son URL est exactement celle affichée sous Webhook URL et que les événements listés ci-dessus sont sélectionnés. La commande est également vérifiée à chaque retour du client dans la boutique.

Le webhook répond verification failed, retry later : la boutique n'a pas pu lire la commande Pagar.me depuis l'API, par exemple parce que la clé de ce mode est absente ou que l'API n'a pas répondu. Pagar.me renouvelle le webhook.

Le webhook répond busy : le panier était en cours de mise à jour par une autre requête au même moment, ou la commande n'a pas pu être créée (par exemple, le module est désactivé). Pagar.me renouvelle le webhook. Activez Debug log pour voir la raison.

Le webhook répond unknown order : la commande Pagar.me n'a pas été créée par cette boutique, par exemple une commande d'une autre boutique du même compte. Rien n'est modifié.

Le client voit Pagar.me payments are not available right now : la clé secrète est incorrecte ou absente. Vérifiez la clé du mode actuel.

Le client voit Pagar.me could not start the payment : Pagar.me a rejeté les données de facturation, par exemple le CPF saisi dans le champ Identification number de l'adresse. Le message indique le problème ; la raison complète figure dans le journal.

Le client voit Pagar.me only supports payments in Brazilian Real (BRL) : le panier est dans une autre devise.

Le client voit This order already has a Pagar.me payment that the store has to review : un paiement antérieur du panier doit être vérifié par vous. Consultez le tableau de bord Pagar.me et le journal.

La commande est en Pagar.me payment on hold après le paiement : lisez les notes du bloc Pagar.me payment (voir Statuts de commande), puis traitez la commande ou remboursez le paiement.

Le remboursement échoue pour un boleto : les paiements par boleto ne peuvent pas être remboursés via l'API. Remboursez depuis le tableau de bord Pagar.me et enregistrez le remboursement manuellement.

Le remboursement échoue avec un message sur le mode : le paiement a été effectué en mode test ou live, et la clé secrète de ce mode n'est pas renseignée. Saisissez-la et réessayez.

Les développeurs peuvent modifier les données de la commande Pagar.me avant son envoi avec le hook actionWcpPagarmeOrderData.

Désinstallation

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

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