VibeFox Pagar.me for WooCommerce — Aide

Prérequis

WordPress : 6.0 ou ultérieur.

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

PHP : 8.0 ou ultérieur.

Devise : réal brésilien (BRL). Le mode de paiement est masqué lorsque la devise de la boutique (ou, sur la page Pay for order, celle de la commande) n'est pas le BRL.

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é de production (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 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_pagarme_gateway dans /wp-content/plugins/ par FTP.

2. Cliquez sur Activate.

3. Ouvrez les réglages : WooCommerce > Settings > Payments > Pagar.me > Manage, ou cliquez sur Settings sous le nom de l'extension dans 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 la clé secrète de test et, lors du passage en production, la clé secrète de production.

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

7. Activez Enable / Disable et enregistrez. Effectuez des paiements de test avec Test mode activé, puis désactivez-le pour recevoir de vrais paiements.

Configuration

Tous les réglages se trouvent sur une seule page : WooCommerce > Settings > Payments > Pagar.me. Sous le titre, 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 mode de paiement est alors masqué au moment du paiement), lorsque la clé de test ne commence pas par sk_test_, lorsque la clé de production ne commence pas par sk_ ou est une clé de test, et lorsque la devise de la boutique n'est pas le BRL. Dans la liste des modes de paiement, Pagar.me est signalé comme nécessitant une configuration tant que la clé du mode actuel n'est pas saisie, et un badge de mode test est affiché tant que ce mode est activé.

Général

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

Title : le nom du mode de paiement que voient les clients au moment de payer. Par défaut : Pagar.me.

Description : le texte affiché sous le mode de paiement lors du 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 de production ; c'est la clé qui détermine si un paiement est un test ou un paiement réel.

Test mode : Use the test secret key (no real charges). Une mention TEST MODE s'affiche au moment du paiement tant que le mode test est activé. 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 de Pagar.me (sk_test_...). Utilisée tant que le mode test est activé.

Live secret key : la clé secrète de production de Pagar.me (sk_...). Utilisée lorsque le mode test est désactivé. Gardez-la confidentielle.

La clé secrète unique de la version 1.0 est transférée automatiquement : une clé de test est déplacée vers Test secret key et le mode test est activé ; sinon, elle reste la clé de production et le mode test est désactivé.

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. Par défaut : Credit card, PIX et Boleto.

Credit card : autorisée et débitée immédiatement.

PIX : paiement instantané par PIX.

Boleto : titre de paiement bancaire ; la commande reste en attente tant qu'il n'est pas payé.

Debit card : paiement par carte de débit.

Boleto due in (days) : nombre de jours avant l'échéance du boleto, de 1 à 30. La commande reste En attente jusqu'à ce que Pagar.me confirme le paiement. Par défaut : 3.

Notifications de paiement (webhook)

Dans le tableau de bord Pagar.me, ouvrez Settings > Webhooks et créez un webhook avec l'URL affichée dans cette section. Elle ressemble à https://your-site/wc-api/webhook_wc_pagarme/. Copiez-la exactement telle qu'elle apparaît dans les réglages.

Sélectionnez ces événements :

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 en extrait uniquement 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 webhook, les paiements PIX et boleto effectués plus tard ne sont confirmés que lorsque le client revient sur la boutique.

Avancé

Debug log : Log API requests and notifications écrit les détails dans WooCommerce > Status > Logs, source wcp_pagarme_gateway. Les erreurs sont toujours journalisées. Les journaux ne contiennent ni clés 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 mode de paiement (par défaut Pagar.me) et passe commande. Une adresse e-mail de facturation valide est requise. L'extension crée une commande Pagar.me pour le total en BRL, avec les lignes de commande, la livraison et les frais (ou une seule ligne Order # avec le numéro de commande lorsque les lignes ne peuvent pas s'additionner exactement), puis envoie le client vers la page de paiement Pagar.me. Le nom du client, son e-mail et, pour le Brésil, son téléphone et son adresse de facturation sont transmis à Pagar.me. Le CPF ou le CNPJ est repris depuis les champs du plugin Brazilian Market on WooCommerce lorsqu'ils existent ; sinon, le client le saisit sur la page Pagar.me.

Après le paiement, le client revient sur 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 et la devise payés doivent correspondre à la commande. Un paiement par carte, PIX ou boleto effectué marque la commande comme payée. Un PIX ou un boleto émis mais non encore payé place la commande En attente jusqu'à ce que Pagar.me confirme le paiement par webhook.

Si le client revient sans payer, ou si le paiement a été refusé ou annulé, il arrive sur la page Pay for order avec The Pagar.me payment was not completed. You can pay the order below. ou The Pagar.me payment was declined or canceled. You can try again below.

Lorsque le client paie à nouveau, la page de paiement Pagar.me encore ouverte est réutilisée si le montant et le mode sont identiques ; sinon, elle est fermée auprès de 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 boleto est toujours en attente, la commande est mise à jour sans nouveau paiement. Si l'ancienne page ne peut pas être fermée, elle reste rattachée à la commande, de sorte qu'un paiement effectué sur celle-ci est tout de même enregistré.

Si Pagar.me ne peut pas démarrer le paiement, le client voit un court message, par exemple Could not connect to Pagar.me. Please try again in a moment., ou le message de Pagar.me concernant des données de facturation invalides. La raison technique est ajoutée aux notes de commande.

Le mode 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).

L'extension 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

Pending payment : le client a été envoyé vers Pagar.me et n'a pas encore payé ni généré de PIX ou de boleto. Une note indique l'ID de la commande Pagar.me et le mode.

Processing : le paiement a été confirmé. C'est le statut WooCommerce standard après paiement ; les commandes ne contenant que des produits virtuels téléchargeables passent à Completed. La note de commande indique l'ID de la commande Pagar.me et le mode de paiement. L'ID de transaction est l'ID de la commande Pagar.me (or_...).

On hold : un PIX ou un boleto a été émis (ou un paiement par carte est en cours d'analyse) et attend le paiement ; ou le boleto n'a été payé qu'en partie ; ou le montant ou la devise payés diffèrent de la commande ; ou un paiement est arrivé après l'annulation de la commande ; ou la commande a été payée chez Pagar.me après que le client a changé de mode de paiement ; ou une contestation (chargeback) a été ouverte sur une commande payée. La note de commande l'explique. Examinez la commande et passez-la en Processing, ou remboursez le paiement chez Pagar.me.

Failed : le paiement a échoué, ou la commande Pagar.me a été annulée ou a expiré (par exemple un boleto non payé). Seule la dernière tentative d'une commande non payée peut la faire passer en Failed. Le client peut payer à nouveau.

Refunded : le paiement a été remboursé ou annulé dans Pagar.me.

Chaque statut Pagar.me n'est appliqué qu'une seule fois : les webhooks ou retours répétés n'ajoutent donc ni notes, ni e-mails, ni réductions de stock. Une commande payée ne repasse jamais en attente ou en échec, et une commande annulée ou remboursée n'est jamais rouverte. Si une seconde commande Pagar.me de la même commande WooCommerce est payée, une note vous invite à rembourser le doublon dans le tableau de bord Pagar.me.

Remboursements

Ouvrez la commande, cliquez sur Refund, saisissez le montant et cliquez sur Refund via Pagar.me (le bouton reprend le titre de votre mode de paiement). Les remboursements totaux et partiels des paiements par carte et PIX sont pris en charge, dans la limite du montant encore remboursable chez Pagar.me. Le remboursement est envoyé avec la clé du mode dans lequel le paiement a été effectué. Un remboursement n'est enregistré que lorsque Pagar.me le confirme ; sinon, WooCommerce 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é aux notes de commande avec l'ID du débit.

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

Un remboursement total ou une annulation effectué dans le tableau de bord Pagar.me arrive par webhook et fait passer la commande en Refunded. Une contestation ajoute une note et place une commande en Processing ou Completed en attente.

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 > Pagar.me. Collez la clé dans License key et cliquez sur Activate. Le bloc affiche le statut, par exemple la date de fin de validité de la licence 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 sur un seul domaine. Retirer la clé d'un site ne libère pas son emplacement de domaine. Libérez cet emplacement depuis votre compte vibefox.net.

Sans clé active, Pagar.me n'est pas proposé 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 mode de paiement, marqué (unlicensed — visible to admins only), afin de pouvoir 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 toujours.

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

Pagar.me n'apparaît pas au moment du 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 réel) et que la devise de la boutique est le BRL. La page des réglages affiche un avertissement dans chacun de ces cas.

Le paiement a été effectué, mais la commande reste en Pending payment ou On hold : 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 dans les réglages et que les événements listés ci-dessus sont sélectionnés. La commande est aussi vérifiée lorsque le client revient sur 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 réessaie le webhook.

Le webhook répond busy, retry later : la commande était en cours de mise à jour par une autre requête au même moment. Pagar.me réessaie le webhook.

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 This order is already being processed : un webhook ou le retour du client était en train de mettre à jour la commande au même moment. Le client peut réessayer après un moment.

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 refusé les données de facturation. Le message indique le problème ; la raison complète figure dans les notes de commande.

Le client voit Pagar.me only supports payments in Brazilian Real (BRL) : la commande est dans une autre devise, par exemple à cause d'une extension de changement de devise.

Order is On hold after payment : lisez la note de commande. Un PIX ou un boleto attend le paiement, le montant ou la devise payés ne correspondaient pas, ou le paiement est arrivé après l'annulation de la commande.

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

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

La désactivation de l'extension conserve toutes les données. Pour la supprimer, désactivez-la puis supprimez-la depuis 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 et les journaux de l'extension ne sont supprimés que si Delete data on uninstall était activé. Sinon, ils sont conservés pour une réinstallation ultérieure. Les commandes existantes conservent leurs notes de paiement, leurs ID de transaction et leurs données Pagar.me.

Pagar.me est une marque de son propriétaire respectif. Cette extension n'est ni affiliée à Pagar.me ni approuvée par Pagar.me.