VibeFox Pagar.me for OpenCart — Aide

Prérequis

OpenCart: 3.0.x (testé avec la version 3.0.5.0) ou 4.0.2 et ultérieur (testé avec la version 4.1.0.3).

PHP: 8.0 ou ultérieur.

Currency: réal brésilien (BRL). La boutique doit disposer de la devise BRL (System > Localisation > Currencies), et le mode de paiement n'est affiché que lorsque le client paie en BRL et que le total de la commande est supérieur à zéro.

Pagar.me account: 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 modes de paiement activés dans votre compte Pagar.me peuvent être proposés.

VibeFox license key: achetée sur vibefox.net. Une clé fonctionne sur un seul domaine.

Installation

Le téléchargement est un seul fichier zip contenant les paquets pour les deux versions d'OpenCart. Décompressez-le sur votre ordinateur. Il contient README.txt, le paquet OpenCart 3 wcp_pagarme_gateway-oc3-(version).ocmod.zip et le paquet OpenCart 4 wcp_pagarme_gateway.ocmod.zip. N'installez que le paquet correspondant à votre version d'OpenCart. La clé de licence est la même pour les deux versions.

OpenCart 3

1. Dans l'administration, allez dans Extensions > Installer, cliquez sur Upload et choisissez le fichier wcp_pagarme_gateway-oc3-(version).ocmod.zip. L'extension ne comporte aucune modification OCMOD, il n'est donc pas nécessaire de rafraîchir Extensions > Modifications. Au lieu de l'installateur, vous pouvez aussi copier le contenu du dossier upload de ce paquet dans le dossier racine de votre boutique.

2. Allez dans Extensions > Extensions et choisissez le type Payments. Repérez VibeFox Pagar.me Gateway et cliquez sur Install (le bouton vert +). Votre utilisateur administrateur doit avoir le droit de modifier la liste des extensions de paiement.

3. Cliquez sur Edit (le bouton en forme de crayon) pour ouvrir la page des paramètres. Collez votre clé de licence VibeFox dans License key, dans le bloc de licence en haut de la page, 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 de production.

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

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

OpenCart 4

1. Dans l'administration, allez dans Extensions > Installer, cliquez sur Upload et choisissez le fichier wcp_pagarme_gateway.ocmod.zip. Ne renommez pas le fichier : OpenCart 4 tire le code de l'extension du nom du fichier, et un paquet renommé ne fonctionne pas.

2. Le paquet apparaît dans la liste des extensions installées, sur la même page. Cliquez sur Install (le bouton vert +) à côté de lui.

3. Allez dans Extensions > Extensions et choisissez le type Payments. Repérez VibeFox Pagar.me Gateway, cliquez sur Install (le bouton vert +), puis sur Edit (le bouton en forme de crayon).

4. Saisissez la clé de licence, les clés secrètes et le webhook comme aux étapes 3 à 6 pour OpenCart 3. La page des paramètres et ses champs sont identiques dans les deux versions. Seule l'URL du webhook diffère (voir Notifications de paiement (webhook)).

Une nouvelle installation démarre avec le mode de paiement désactivé et le mode test activé.

Configuration

Tous les paramètres se trouvent sur la page de l'extension : Extensions > Extensions > Payments > VibeFox Pagar.me Gateway > Edit. Les sections sont listées à gauche ; le bouton Save situé sous la liste enregistre la page entière. Au-dessus des paramètres, la page indique le mode en cours : 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 en cours est absente (le mode de paiement est alors masqué à la commande), 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 par défaut de la boutique n'est pas BRL. Sans le droit de modifier l'extension, la page affiche les paramètres mais ne peut pas les enregistrer.

Lors de l'enregistrement, Title ne doit pas être vide (128 caractères maximum), Boleto due in (days) doit être un nombre entier de 1 à 30, Sort Order doit être un nombre entier (les nombres négatifs sont autorisés), Total doit être un nombre égal ou supérieur à 0, et la zone géographique et les statuts de commande doivent exister. Si une valeur est incorrecte, un message la signale et rien n'est enregistré.

Pagar.me

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 les clients voient à la commande. C'est aussi le nom enregistré dans la commande. Par défaut : Pagar.me. Obligatoire, 128 caractères maximum.

Description: le texte affiché au client à l'étape Confirm Order, au-dessus du bouton de confirmation. Par défaut : Payez en toute sécurité via Pagar.me (carte de crédit, PIX ou boleto). Vous serez redirigé pour finaliser votre paiement.

Sort Order: la position de Pagar.me parmi les modes de paiement de la commande. Laissez le champ vide ou saisissez un nombre entier.

Geo Zone: proposer Pagar.me uniquement pour les adresses de facturation situées dans la zone géographique sélectionnée. Par défaut : All zones. Les zones géographiques se configurent dans System > Localisation > Geo Zones. Sur OpenCart 4, lorsque la boutique ne demande aucune adresse de facturation, c'est l'adresse de livraison qui est utilisée.

Total: le total de la commande, dans la devise par défaut de la boutique, que doit atteindre une commande avant que Pagar.me soit proposé. Laissez le champ vide pour proposer Pagar.me quel que soit le montant.

Clés API

Copiez les clés secrètes depuis le tableau de bord Pagar.me (la section contient un lien vers celui-ci) : 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 s'il s'agit d'un paiement de test ou d'un paiement réel.

Test mode: utilise la clé secrète de test, sans débit réel. Lorsqu'il est activé, les clients voient TEST MODE — Use test credentials. No real charges. à l'étape Confirm Order. 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.

Les clés enregistrées ne sont jamais réaffichées. Le champ reste vide et affiche Saved — leave empty to keep it. Ne saisissez une nouvelle valeur que pour la modifier. Pour supprimer une clé enregistrée, cochez Clear the saved key on save sous le champ, puis cliquez sur Save.

Page de paiement

Les modes proposés sur la page de paiement de Pagar.me, chacun avec son propre interrupteur. Ne sélectionnez que les modes activés dans votre compte Pagar.me. Si aucun n'est sélectionné, la carte de crédit, PIX et boleto sont proposés. Par défaut : carte de crédit, PIX et boleto.

Boleto due in (days): le nombre de jours avant l'échéance du boleto, de 1 à 30. 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. Sur OpenCart 3, elle a la forme https://your-store/index.php?route=extension/payment/wcp_pagarme_gateway/webhook ; sur OpenCart 4, la forme https://your-store/index.php?route=extension/wcp_pagarme_gateway/payment/wcp_pagarme_gateway.webhook. Elle est construite à partir de l'adresse de la vitrine de votre installation OpenCart. Copiez-la exactement telle qu'elle apparaît dans les paramètres. L'URL doit être accessible depuis Internet.

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

Le webhook n'exige ni mot de passe ni signature. Son contenu n'est jamais considéré comme fiable : la boutique n'en retient que l'identifiant de commande Pagar.me et relit cette commande depuis l'API Pagar.me avec la clé du mode dans lequel elle a été créée. Les notifications concernant des commandes Pagar.me qui n'ont pas été créées par cette boutique sont ignorées. Sans webhook, les paiements PIX et boleto effectués plus tard ne sont confirmés que lorsque le client revient dans la boutique.

Commandes

OpenCart crée la commande à l'étape Confirm Order sans statut (une commande manquante, missing order). La commande ne reçoit un statut qu'après que Pagar.me a signalé le paiement par le webhook ou au retour du client ; la commande Pagar.me est toujours relue depuis l'API. Chaque champ ci-dessous indique vos statuts de commande OpenCart.

Order Status After Payment: le statut attribué après un paiement Pagar.me vérifié. Par défaut : En cours de traitement.

Awaiting Pagar.me Payment Status: un code PIX ou un boleto a été émis, ou un paiement par carte est en cours d'analyse ; Pagar.me confirme ensuite l'encaissement. Par défaut : En attente.

Pagar.me Payment On Hold Status: le paiement nécessite votre vérification (voir Statuts de commande). Par défaut : En attente, car OpenCart n'a pas de statut En suspens. Vous pouvez créer votre propre statut dans System > Localisation > Order Statuses et le sélectionner ici.

Payment Failed Status: le paiement d'une commande en attente a échoué, a été annulé ou a expiré. Si Pagar.me signale ensuite un paiement, la commande reçoit le statut après paiement. Par défaut : Échoué.

Cancelled Order Status: le statut utilisé par votre boutique pour les commandes annulées. L'extension ne le définit pas : un paiement Pagar.me reçu après cela place la commande dans le statut de vérification. Par défaut : Annulée.

Refunded Status: défini après le remboursement intégral du paiement depuis la page de la commande ou dans le tableau de bord Pagar.me. Par défaut : Remboursée.

Avancé

Debug log: écrit les requêtes API et les notifications dans wc_pgm_debug.log.php, dans le dossier des journaux d'OpenCart (storage/logs). Le fichier ne peut pas être ouvert depuis le web. Les erreurs et les avertissements sont toujours journalisés. Les clés et les données clients (e-mail, téléphone, CPF) 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'il est activé, la désinstallation de l'extension supprime les paramètres de la passerelle et le journal. Les commandes et leurs données de paiement Pagar.me (nécessaires aux remboursements) sont toujours conservées. Par défaut : désactivé.

Import / Export

Export: Download JSON enregistre les paramètres dans un fichier JSON. Les clés secrètes ne sont pas exportées.

Import: collez un JSON exporté précédemment et cliquez sur Import pour restaurer les paramètres. Les clés secrètes enregistrées sont conservées.

Commande

À l'étape Payment Method, le client choisit le mode de paiement (par défaut, Pagar.me). À l'étape Confirm Order, le client voit votre description et la note You will be redirected to the Pagar.me payment page to pay by credit card, PIX, boleto or debit card. OpenCart crée la commande à cette étape, toujours sans statut. Sur OpenCart 4, le client choisit le mode de paiement avec le bouton Choose du bloc du mode de paiement, dans la fenêtre Payment method options, puis clique sur Confirm Order en bas du tunnel de commande. Lorsque le client clique sur Confirm Order, l'extension crée une commande Pagar.me pour le total de la commande en BRL et envoie le client sur la page de paiement de Pagar.me. Les lignes de commande avec les taxes, la livraison et les autres suppléments sont transmises comme articles ; lorsque la commande comporte une remise (coupon, bon, points de fidélité) ou que les lignes ne correspondent pas au total, une ligne Order # avec le numéro de commande est transmise pour le total. Une adresse e-mail valide est requise.

Le nom et l'adresse e-mail du client sont transmis à Pagar.me. Le CPF ou le CNPJ (11 ou 14 chiffres) est repris d'un champ personnalisé du client ou de l'adresse de facturation dont le nom contient CPF ou CNPJ ; OpenCart n'a pas de champ de ce type par défaut, ajoutez-le dans Customers > Custom Fields si vous souhaitez le transmettre. Sur OpenCart 4, lorsque la boutique ne demande aucune adresse de facturation, ce sont l'adresse de livraison et ses champs personnalisés qui sont utilisés. 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. Sans CPF ni CNPJ, le client le saisit sur la page de Pagar.me.

Après le paiement, le client revient dans votre boutique. La commande n'est marquée comme payée qu'après confirmation par Pagar.me : la boutique relit la commande Pagar.me depuis l'API, et le montant payé ainsi que la devise doivent correspondre à la commande. La commande reçoit alors son statut de la manière habituelle d'OpenCart, avec les e-mails de commande habituels et la mise à jour du stock, et le client voit la page de confirmation de commande d'OpenCart. Un PIX ou un boleto émis mais non encore payé place la commande en statut d'attente, et la page affiche également Your Pagar.me payment is awaiting confirmation (PIX / boleto). The order will be confirmed as soon as Pagar.me reports the payment. Pour une commande en statut de vérification, elle affiche We are confirming your payment with Pagar.me. The order will be updated automatically — please do not pay again. Chaque retour ultérieur relit la commande Pagar.me ; un PIX ou un boleto réglé entre-temps est donc pris en compte, même si le webhook n'est pas arrivé.

Si le client revient sans avoir payé, il revient à la commande avec le message The Pagar.me payment was not completed. You can try again or choose another payment method. Si le paiement a été refusé ou annulé, le message est The Pagar.me payment was declined or canceled. You can try again or choose another payment method. Le panier est conservé. Sur OpenCart 4, ces messages s'affichent au-dessus du tunnel de commande. Si la commande a déjà un statut 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 le panier est déjà vide (par exemple, la commande avait atteint la page de confirmation avant l'expiration de son PIX ou de son boleto), il n'y a rien à payer à la commande : une page Payment confirmation indique The Pagar.me payment of order #N was not completed (declined, canceled or expired), so the order will not be shipped. To buy these items, please place a new order. avec un bouton Continue. Si Pagar.me n'a pas pu être joint, une page Payment confirmation demande au client de ne pas payer à nouveau et propose Check again et Back to checkout.

OpenCart 3 crée une nouvelle commande chaque fois que l'étape Confirm Order s'affiche. OpenCart 4 conserve une seule commande pour le tunnel de commande et la met à jour, si bien qu'après un paiement inachevé ou refusé, le client paie à nouveau la même commande. Avant un nouveau paiement, l'extension vérifie les tentatives précédentes du même panier : si l'une d'elles est payée, ou si son PIX ou son boleto est en attente, le client est dirigé vers la page de confirmation sans nouveau paiement. Une page de paiement Pagar.me encore ouverte pour la même commande est réutilisée si le montant et le mode sont identiques ; les autres pages ouvertes sont d'abord fermées chez Pagar.me. Si une deuxième commande Pagar.me du panier est tout de même payée, elle n'est pas prise en compte, et une note sur la commande payée vous invite à rembourser le doublon.

Sur OpenCart 4, la commande du tunnel de commande reste active jusqu'à l'affichage de la page de confirmation. Si cette commande a été fermée entre-temps (par exemple si son PIX ou son boleto a expiré, si son paiement a échoué, ou si vous l'avez annulée ou remboursée), Confirm Order renvoie le client au tunnel de commande avec Your previous order was cancelled or its payment failed. Please confirm the order again., ou, lorsque la commande avait été payée avant sa fermeture, avec This order was closed by the store, so it will not be shipped. Your cart is kept: confirm the order again to pay. Le Confirm Order suivant paie une nouvelle commande. Lorsque le client revient de Pagar.me vers une commande payée puis fermée par vous, il voit le même message dans le tunnel de commande ou, si le panier est déjà vide, une page avec Order #(numéro) was closed by the store, so it will not be shipped. To buy these items, please place a new order. Si la commande du tunnel de commande a déjà un statut et que le panier contient désormais d'autres produits ou quantités, le client est renvoyé au tunnel de commande et le nouveau panier reçoit une nouvelle commande.

Si Pagar.me ne peut pas lancer le paiement, le client reste à l'étape Confirm Order avec un bref message, par exemple Could not connect to Pagar.me. Please try again in a moment., ou le message de Pagar.me concernant des coordonnées de facturation invalides. La raison technique est écrite dans le journal.

Le webhook fonctionne également lorsque la boutique est en mode maintenance : OpenCart 3 laisse passer les requêtes des extensions de paiement, et sur OpenCart 4 l'extension ajoute une action de démarrage (startup) qui laisse passer le webhook et le retour du client depuis Pagar.me.

L'extension ne comporte pas de formulaire de carte dans votre commande, ni de cartes enregistrées, d'abonnements ou de paiements récurrents, ni de règles de paiement échelonné, ni de paiements fractionnés (marketplace), ni de paiements par carte en autorisation seule.

Commandes et remboursements

Statuts de commande

No status (missing order): le client a été envoyé vers Pagar.me et n'a pas encore payé ni émis de PIX ou de boleto, ou le paiement a été refusé. Dans Sales > Orders, ces commandes ne s'affichent qu'avec le filtre Order Status réglé sur Missing Orders.

Sur OpenCart 4, une commande non payée du tunnel de commande peut recevoir le statut Voided, que OpenCart 4 applique lorsque le client revient à l'étape Confirm Order. L'extension traite une telle commande comme une commande sans statut, et un paiement ultérieur la confirme tout de même.

Order Status After Payment (default Processing): le paiement a été confirmé. Une note indique l'identifiant de commande Pagar.me (or_...) et le mode de paiement.

Awaiting Pagar.me Payment Status (default Pending): 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 à Order Status After Payment lorsque Pagar.me confirme le paiement.

Pagar.me Payment On Hold Status (default Pending): le boleto n'a été payé qu'en partie ; ou le montant ou la devise payés diffèrent de la commande ; ou le paiement est arrivé après l'annulation ou le remboursement de la commande ; ou un litige (chargeback) a été ouvert sur une commande payée. La note l'explique. Vérifiez la commande, puis exécutez-la ou remboursez le paiement.

Payment Failed Status (default Failed): le paiement d'une commande en attente ou suspendue 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 à Order Status After Payment.

Refunded Status (default Refunded): le paiement a été intégralement remboursé par l'extension, ou remboursé ou annulé dans Pagar.me.

Chaque statut Pagar.me n'est appliqué qu'une seule fois, si bien que les webhooks répétés ou les retours n'ajoutent ni notes ni paiements. Les notes sont des entrées de l'History de la commande que le client ne voit pas.

Onglet VibeFox Pagar.me Gateway

Dans Sales > Orders, ouvrez une commande payée avec Pagar.me. En bas de la page de commande, à côté de History et Additional, l'onglet VibeFox Pagar.me Gateway affiche l'identifiant Pagar.me order avec une étiquette Test mode pour les paiements de test, le Payment method, le Status, les montants Paid / refunded, le formulaire de remboursement, l'historique des remboursements et les Pagar.me notes de la commande. L'onglet est affiché aux utilisateurs qui ont accès à l'extension.

Remboursements

Dans l'onglet VibeFox Pagar.me Gateway, saisissez le Amount (le montant non encore remboursé est prérempli), éventuellement un Reason (optional), 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 l'extension (défini dans System > Users > User Groups). Vous pouvez rembourser jusqu'au montant effectivement prélevé par Pagar.me ; ainsi, après un écart de montant, la limite correspond à ce que le client a payé et non au total de la commande. Le remboursement est envoyé avec la clé du mode dans lequel le paiement a été effectué ; la clé secrète de ce mode doit donc être configurée. Un remboursement n'est enregistré que lorsque Pagar.me le confirme ; sinon, l'onglet 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'identifiant du débit. Un remboursement total place la commande en Refunded Status sans notifier le client et sans remettre les produits en stock, comme un changement de statut manuel. Un remboursement partiel ne modifie pas le statut. Les remboursements sont disponibles dès que Pagar.me a signalé le paiement.

Les paiements boleto ne peuvent être remboursés que sur le compte bancaire du client. Effectuez-les dans le tableau de bord Pagar.me, puis enregistrez manuellement le remboursement dans OpenCart. Les retours de produits dans Sales > Returns ne renvoient pas d'argent via Pagar.me.

Un remboursement total ou une annulation effectué dans le tableau de bord Pagar.me arrive par webhook, place la commande en Refunded Status et ajoute une note. Un litige ajoute une note et place une commande payée en statut de vérification.

Clé de licence

L'extension 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 Extensions > Extensions > Payments > VibeFox Pagar.me Gateway > Edit, au-dessus des paramètres. Collez 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: opencart-payment-pagarme et le lien Manage licenses and domains in your account, qui ouvre votre compte vibefox.net. Seuls les utilisateurs administrateurs disposant du droit de modification de l'extension peuvent changer la clé. Les textes du bloc suivent la langue de l'administration (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, l'extension continue de fonctionner avec le dernier statut connu.

Une clé fonctionne sur un seul domaine : l'adresse de la boutique issue de la configuration d'OpenCart. Retirer la clé de la boutique ne libère pas son emplacement de domaine. Libérez-le dans votre compte vibefox.net.

Sans clé active, Pagar.me n'est pas affiché aux clients à la commande. Si un paiement est tout de même lancé, le client voit This payment method is not available. Please choose another one. Un utilisateur administrateur connecté à l'administration dans le même navigateur voit toujours le mode de paiement dans la boutique, marqué (unlicensed — visible to admins only), afin que vous puissiez configurer et tester l'extension avant d'acheter une clé. Sur OpenCart 4, cet aperçu n'est pas disponible : la boutique ne voit pas la session de l'administrateur, donc sans clé active, le mode de paiement est masqué pour tout le monde. Après avoir ouvert une fois la page Edit, un rappel apparaît sur le Dashboard de l'administration. Fermez-le avec × pour le masquer pendant 7 jours. 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, l'extension continue de fonctionner, mais les mises à jour et le support nécessitent un renouvellement. Le statut est vérifié à nouveau automatiquement lorsque vous ouvrez le Dashboard ou la page Edit de l'administration : une fois par jour pendant les 14 premiers jours après la saisie de la clé, puis une fois par semaine. Aucune tâche cron n'est nécessaire. La désinstallation de l'extension supprime toujours la clé de licence et le statut de la licence.

Dépannage

Pagar.me does not appear at checkout: vérifiez que la licence est active, que Enable / Disable est activé, que la clé secrète du mode en cours est définie (Test secret key en mode test, Live secret key en mode production) et que le client paie en BRL. La page des paramètres affiche un avertissement lorsque la clé est absente. Vérifiez également que l'adresse de facturation se trouve dans la Geo Zone sélectionnée et que la commande atteint le Total défini dans les paramètres.

The payment went through, but the order stays without a status or in the awaiting status: 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 aussi vérifiée à chaque retour du client dans la boutique.

The webhook answers verification failed, retry later: la boutique n'a pas pu relire 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.

The webhook answers busy: le panier était en cours de traitement par une autre requête au même moment, ou le statut de la commande n'a pas pu être défini. Pagar.me renouvelle le webhook. Activez Debug log pour voir la raison.

The webhook answers unknown order: la commande Pagar.me n'a pas été créée par cette boutique, par exemple une commande d'une autre boutique sur le même compte. Rien n'est modifié.

The webhook answers invalid payload or invalid order id: la requête n'est pas une notification Pagar.me. Rien n'est modifié.

The customer sees Pagar.me payments are not available right now: la clé secrète est incorrecte ou absente. Vérifiez la clé du mode en cours.

The customer sees Pagar.me could not start the payment: Pagar.me a rejeté les coordonnées de facturation, par exemple le CPF du champ personnalisé. Le message indique le problème ; la raison complète figure dans le journal.

The customer sees A valid billing email is required for Pagar.me.: l'adresse e-mail de la commande n'est pas valide.

The customer sees Pagar.me only supports payments in Brazilian Real (BRL).: la commande est dans une autre devise.

The customer sees 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 vos soins. Consultez le tableau de bord Pagar.me et le journal.

Order is in the review status after payment: lisez les notes dans l'onglet VibeFox Pagar.me Gateway (voir Statuts de commande), puis exécutez la commande ou remboursez le paiement.

No refund form in the tab: l'onglet indique la raison : le paiement n'est pas encore signalé, il est entièrement remboursé, votre groupe d'utilisateurs n'a pas le droit de modifier l'extension, ou la clé secrète du mode du paiement n'est pas définie.

Refund fails for a boleto: les paiements boleto ne peuvent pas être remboursés via l'API. Remboursez dans le tableau de bord Pagar.me et enregistrez le remboursement manuellement.

Pour les développeurs : avant l'envoi de la commande Pagar.me, l'extension déclenche l'événement OpenCart wc_pgm_order_data avec le corps de la requête et la commande. Le montant du paiement doit rester égal au total de la commande.

Désinstallation

Allez dans Extensions > Extensions, choisissez le type Payments et cliquez sur Uninstall (le bouton rouge −) à côté de VibeFox Pagar.me Gateway. La clé de licence et le statut de licence de cette extension sont toujours supprimés. OpenCart supprime toujours ses propres paramètres de l'extension : Enable / Disable, Sort Order, Geo Zone, Total et les statuts de commande de la section Orders, qui reviennent à leurs valeurs par défaut lors d'une réinstallation. L'événement OpenCart de l'extension est également supprimé (sur OpenCart 4, ses événements et son action de démarrage, qui laisse passer le webhook et le retour du client en mode maintenance). Si Delete data on uninstall est activé, les autres paramètres de la passerelle (titre, description, mode test, clés secrètes, modes de paiement, nombre de jours du boleto, journalisation) et le journal sont supprimés. S'il est désactivé, ils sont conservés pour une réinstallation ultérieure. Les enregistrements de paiement et de remboursement Pagar.me 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.

Sur OpenCart 4, pour supprimer aussi les fichiers de l'extension, allez dans Extensions > Installer après la désinstallation et cliquez sur Uninstall (le bouton orange −) à côté de VibeFox Pagar.me Gateway dans la liste des extensions installées, puis sur Delete (le bouton rouge en forme de corbeille) pour supprimer le paquet téléversé.

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