VibeFox MercadoPago for PrestaShop — Aide

Prérequis

PrestaShop : 8.0 à 9.x.

PHP : 8.0 ou ultérieur. Le module refuse de s'installer sur les versions antérieures de PHP.

Devise de la boutique : la devise du pays de votre compte MercadoPago : ARS (Argentine), BRL (Brésil), CLP (Chili), COP (Colombie), MXN (Mexique), PEN (Pérou) ou UYU (Uruguay). MercadoPago encaisse dans la devise du compte et ne convertit pas ; le moyen de paiement est donc masqué pour un panier dans une autre devise.

Compte MercadoPago : vous avez besoin d'une application dans le panneau développeurs de MercadoPago (Your integrations > your application > Credentials) avec ses identifiants de test (qui commencent par TEST-) et de production (qui commencent par APP_USR-) : une clé publique et un Access Token pour chacun. Pour la vérification facultative de la signature des notifications, vous avez aussi besoin de la clé secrète de signature de your application > Webhooks.

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 MercadoPago 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. Choisissez le Account country, saisissez les identifiants de test et de production et, si vous le souhaitez, configurez les notifications dans votre application MercadoPago (voir Configuration).

5. Activez Enable / Disable et cliquez sur Save. Testez un paiement en mode test avec les cartes de test de MercadoPago, puis désactivez Test mode.

À l'installation, le module crée deux statuts de commande : Awaiting MercadoPago payment et MercadoPago payment on hold. PrestaShop attribue un nouveau module de paiement aux pays actifs au moment de l'installation. Vérifiez les devises, les pays et les groupes de clients du module dans Payment > Preferences.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox MercadoPago Gateway > Configure. Chaque section a son propre bouton Save, qui enregistre toute la page. Au-dessus des champs, la page affiche Test mode is on: the TEST- credentials are used and no real money is charged. tant que le mode test est activé. Elle vous avertit aussi lorsque la clé publique ou l'Access Token du mode actuel manque, lorsque la devise de la boutique n'est pas celle de votre compte MercadoPago (le moyen de paiement est alors masqué au paiement), et lorsque les identifiants appartiennent à un compte d'un autre pays que Account country.

À l'enregistrement, un identifiant qui ne commence pas par le préfixe attendu (TEST- pour les champs de test, APP_USR- pour les champs de production) n'est pas enregistré : l'erreur must start with … — the previous value was kept. s'affiche. Le module demande aussi à MercadoPago à quel pays appartient chaque Access Token. Si le jeton du mode actuel ne peut pas être vérifié, si le compte n'est pas dans un pays pris en charge ou si le pays ne correspond pas à Account country, une erreur s'affiche. Le module utilise alors le pays du compte.

MercadoPago

Enable / Disable: Enable MercadoPago card payments active ou désactive le moyen de paiement. Par défaut : off.

Title: le nom du moyen de paiement affiché au client au paiement. C'est aussi le nom du moyen de paiement enregistré dans la commande. Par défaut : Credit or debit card (MercadoPago). Obligatoire.

Description: le texte affiché au-dessus des champs de carte au paiement. Par défaut : Pay securely with your credit or debit card. Card data is sent directly to MercadoPago.

Compte MercadoPago

Obtenez les identifiants de votre application dans le panneau développeurs de MercadoPago : Your integrations > your application > Credentials. Les identifiants de test commencent par TEST-, ceux de production par APP_USR-.

Account country: le pays de votre compte MercadoPago. Il détermine la devise d'encaissement, la langue des champs de carte et si le document du titulaire est demandé. La devise de la boutique doit être la même, par exemple ARS pour l'Argentine. Lors de l'enregistrement des identifiants, le pays est vérifié par rapport au compte. Par défaut : Argentina (ARS).

Argentina (ARS), Brazil (BRL), Chile (CLP), Colombia (COP), Mexico (MXN), Peru (PEN), Uruguay (UYU): les pays pris en charge. Le champ document s'affiche pour tous sauf le Mexique.

Test mode: en mode test, les identifiants TEST- sont utilisés et vous payez avec les cartes de test de MercadoPago ; un badge TEST MODE s'affiche au paiement. Désactivez-le pour encaisser de vraies cartes avec les identifiants de production. Par défaut : on.

Test Public Key: commence par TEST-. Utilisée dans le navigateur pour tokeniser la carte.

Test Access Token: commence par TEST-. Utilisé uniquement sur le serveur. À garder secret.

Production Public Key: commence par APP_USR-.

Production Access Token: commence par APP_USR-. Utilisé uniquement sur le serveur. À garder secret.

Les Access Tokens enregistrés et le secret du webhook ne sont jamais réaffichés. Le champ reste vide et affiche Saved — leave empty to keep it. Ne saisissez une nouvelle valeur que si vous voulez la modifier.

Options de paiement

Maximum installments: le nombre maximal d'échéances que le client peut choisir, de 1 à 24. 1 = paiement unique uniquement, et le champ des échéances n'est pas affiché. La limite est aussi appliquée côté serveur. Par défaut : 1.

Notifications de paiement (webhooks)

Les paiements par carte reçoivent généralement une réponse définitive immédiatement. Les paiements que MercadoPago garde en examen (en cours ou en attente) sont finalisés par les notifications de MercadoPago. Le module envoie l'URL de notification avec chaque paiement lorsque votre boutique dispose d'une adresse publique (pas localhost ni un domaine .local ou .test). Vous pouvez aussi l'ajouter dans your application > Webhooks, événement Payments. L'URL est affichée dans Notification URL dans cette section. Avec des URL conviviales, elle ressemble à https://your-shop/en/module/wcp_mercadopago_gateway/webhook?source_news=webhooks. Copiez l'URL exactement telle qu'elle est affichée dans les réglages.

Une notification n'est jamais considérée comme fiable en soi. Le module relit le paiement depuis l'API MercadoPago avec l'Access Token de l'environnement dans lequel le paiement a été effectué, puis le rattache à une tentative de paiement de votre boutique. Sans notifications, les commandes en examen restent en Awaiting MercadoPago payment jusqu'à ce que vous les mettiez à jour manuellement.

Le module gère ces statuts de paiement MercadoPago :

approved: le paiement a été approuvé. La commande est marquée payée lorsque le montant et la devise correspondent.

in_process, pending, authorized: le paiement est en cours d'examen. La commande attend en Awaiting MercadoPago payment et est finalisée par une notification ultérieure.

rejected, cancelled: le paiement a été refusé ou annulé. Aucune commande n'est créée ; une commande en attente reçoit Payment error.

refunded, charged_back, in_mediation: une note est ajoutée ; le statut de la commande ne change pas.

Webhook secret signature: facultatif. La clé secrète de signature affichée dans your application > Webhooks. Lorsqu'elle est renseignée, les notifications sans x-signature valide sont rejetées (HTTP 401).

Clear saved secrets: cochez Test Access Token, Production Access Token ou Webhook secret signature et cliquez sur Save pour la supprimer. Un champ vide conserve la valeur enregistrée.

Avancé

Debug log: écrit les requêtes et notifications MercadoPago dans logs/wc_mpg_debug.log.php dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les erreurs sont toujours journalisées, même lorsque ce réglage est désactivé. Les Access Tokens, les jetons de carte et les données du payeur ne sont pas journalisés. Par défaut : off.

Log: affiche la taille et les dernières entrées du journal. Cliquez sur Clear log pour le vider.

Delete data on uninstall: lorsque l'option est activée, la désinstallation du module supprime les réglages de la passerelle et les journaux. Les enregistrements de paiement MercadoPago, les remboursements et les statuts de commande du module sont toujours conservés, de sorte que les commandes payées auparavant peuvent être remboursées après une réinstallation. Par défaut : off.

Paiement

À l'étape de paiement, le client choisit le moyen de paiement (par défaut Credit or debit card (MercadoPago)) et remplit les champs de carte : Card number, Expiry (MM/YY), Security code et Cardholder name. Selon le pays et la carte, le client choisit aussi Document type et saisit le Document number, sélectionne le Card issuer et le nombre d'Installments. Les options d'échéances et les intérêts sont fournis par MercadoPago pour le montant du panier. Le formulaire de carte fonctionne avec les thèmes Classic et Hummingbird.

Lorsque le client confirme, MercadoPago transforme la carte en jeton à usage unique et votre boutique crée le paiement sur le serveur pour le montant du panier. L'e-mail et le nom du client, le document et le numéro de panier sont transmis à MercadoPago ; le paiement apparaît comme Cart #, avec le numéro de panier et le nom de votre boutique. Les montants en CLP et COP sont débités sans décimales. Aucune commande n'existe avant la réponse de MercadoPago.

Un paiement approuvé crée une commande payée, et le client voit la page de confirmation de commande avec Your card payment has been received. Un paiement en examen crée une commande en Awaiting MercadoPago payment, et la page affiche MercadoPago is reviewing your payment. Your order will be updated automatically as soon as MercadoPago confirms it. Si un paiement en examen est refusé plus tard, la page affiche Your MercadoPago payment was not completed. Please contact us about this order. Une commande retenue affiche Your payment is being reviewed. We will update your order as soon as the review is complete.

Une carte refusée ne crée aucune commande. Le client reste à l'étape de paiement avec un motif court, par exemple Your card has insufficient funds. Please use another card or payment method. ou Please check the security code of your card. Le client peut corriger ses données ou utiliser une autre carte ; un nouveau jeton de carte est créé à chaque tentative.

Si MercadoPago ne répond pas, le client voit We could not confirm your payment with MercadoPago. Please wait a minute before trying again — if the payment went through, your order will be updated automatically. La tentative suivante recherche d'abord le paiement, si bien que la carte n'est pas débitée deux fois. Un second clic pendant le paiement du panier affiche This order is already being paid. Please wait a moment and check your e-mail before trying again. Un panier qui a déjà une commande n'est jamais débité à nouveau ; le client est redirigé vers la page de confirmation de cette commande.

L'URL de notification fonctionne lorsque la boutique est en mode maintenance et n'est pas bloquée par la restriction de pays de votre boutique.

Le module n'accepte que les cartes de crédit et de débit. Il n'a pas de redirection vers Checkout Pro, pas de portefeuille ni de solde MercadoPago, pas de paiement en espèces (Rapipago, OXXO, boleto et autres), pas de Pix, PSE ou Yape, pas de cartes enregistrées ni d'abonnements, pas d'autorisation et de capture séparées, pas de vérification 3-D Secure et pas de conversion de devise.

Commandes et remboursements

Statuts de commande

No order: la carte a été refusée, ou MercadoPago n'a pas encore répondu. Seul le panier existe.

Payment accepted: MercadoPago a approuvé le paiement et le montant et la devise correspondent au panier. Le paiement est enregistré avec l'ID de paiement MercadoPago comme ID de transaction, et une note indique l'ID de paiement, l'environnement et le nombre d'échéances.

Awaiting MercadoPago payment: le paiement est en cours d'examen (en cours ou en attente) et attend la notification de MercadoPago. La commande passe en Payment accepted lorsque MercadoPago l'approuve.

MercadoPago payment on hold: le montant ou la devise approuvé diffère du panier, ou MercadoPago a renvoyé un statut inattendu. La note l'explique. Vérifiez la commande et traitez-la, ou remboursez le paiement.

Payment error: un paiement en examen a été refusé ou annulé. La note indique le statut et son détail.

Refunded: le paiement a été entièrement remboursé par le module.

Si MercadoPago approuve un paiement pour une commande déjà annulée ou remboursée, le statut ne change pas et une note vous demande de finaliser la commande ou de rembourser le paiement. Si un autre paiement arrive pour une commande déjà payée, une note vous demande de rembourser le paiement en trop dans le panneau MercadoPago.

Bloc de paiement MercadoPago

La page de commande affiche un bloc MercadoPago payment avec l'ID de paiement, le statut du paiement, l'environnement (un badge Test pour les paiements de test), les échéances, le montant encaissé par MercadoPago et le total de la commande, le montant remboursé, l'historique des remboursements et les MercadoPago notes de la commande.

Remboursements

Dans le bloc MercadoPago payment, saisissez le montant (le montant non encore remboursé est prérempli), éventuellement un motif, puis cliquez sur Refund via MercadoPago. Confirmez la question Refund this amount through MercadoPago? This cannot be undone. Les remboursements totaux et partiels sont pris en charge. Vous devez avoir le droit de modifier les commandes. Les remboursements sont limités au montant encaissé par MercadoPago : après un écart de montant, vous pouvez donc rembourser jusqu'à ce que le client a réellement payé, et non jusqu'au total de la commande. Le remboursement est envoyé avec les identifiants de l'environnement dans lequel le paiement a été effectué (test ou production), donc l'Access Token de cet environnement doit être renseigné. Si MercadoPago refuse le remboursement, le bloc affiche MercadoPago refused the refund avec le motif, et aucun remboursement n'est enregistré. Un remboursement approuvé ou en cours est ajouté à l'historique des remboursements et aux notes avec l'ID du remboursement. Un remboursement total passe la commande en Refunded. Un remboursement partiel ne change pas le statut.

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

Les remboursements, rétrofacturations et médiations effectués dans le panneau MercadoPago arrivent par notification et sont ajoutés aux notes. Le statut de la commande et les avoirs ne sont pas modifiés automatiquement. Mettez-les à jour manuellement si nécessaire.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox MercadoPago Gateway est le premier bloc de Modules > Module Manager > VibeFox MercadoPago 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-mercadopago 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, MercadoPago n'est pas affiché aux clients au paiement. Si un paiement est tout de même lancé, le client voit This payment method is not available. Please choose another one. La boutique PrestaShop ne sait pas que vous êtes connecté au back-office : le moyen de paiement est donc masqué pour vous aussi. Vous pouvez configurer le module avant d'acheter une clé, mais ne pas le tester au paiement. Un rappel apparaît dans Modules > Module Manager, sur 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 votre travail 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. Aucune tâche cron n'est nécessaire. La désinstallation ou la réinitialisation du module supprime toujours la clé de licence et le statut de licence.

Dépannage

MercadoPago n'apparaît pas au paiement : vérifiez que la licence est active, que Enable / Disable est activé et que le mode actuel possède les deux identifiants avec le bon préfixe : les clés TEST- en mode test, les clés APP_USR- en production. Vérifiez que la devise du panier est celle de votre compte MercadoPago. La page des réglages indique celui qui 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 la commande reste en Awaiting MercadoPago payment : la notification n'est pas arrivée. Le module n'envoie l'URL de notification que lorsque votre boutique dispose d'une adresse publique (pas localhost ni un domaine .local ou .test). Ajoutez l'URL de Notification URL dans your application > Webhooks avec l'événement Payments. Si Webhook secret signature est renseigné, vérifiez qu'il s'agit du secret de la même application. Le panneau MercadoPago affiche la réponse de votre boutique pour chaque notification.

La notification répond invalid signature : le secret de signature appartient à une autre application, ou la notification n'a pas de x-signature valide. Recopiez le secret ou laissez le champ vide.

La notification répond no credentials for test or no credentials for live : l'Access Token de l'environnement dans lequel le paiement a été effectué n'est pas renseigné. Saisissez-le ; MercadoPago renouvelle la notification.

La notification répond not for this store : le paiement n'appartient à aucune tentative de paiement de cette boutique. Aucune commande n'est modifiée.

La notification répond order busy or payment could not be read : la commande était en cours de mise à jour par une autre requête au même moment, ou MercadoPago était injoignable. MercadoPago renouvelle automatiquement la notification.

Un identifiant n'est pas enregistré : l'erreur must start with indique que la valeur a le mauvais préfixe pour ce champ. Les champs de test acceptent les identifiants TEST-, les champs de production les identifiants APP_USR-.

Le client voit This payment method is not configured correctly. Please choose another payment method or contact the store.: les identifiants du mode actuel sont manquants, ont le mauvais préfixe ou ont été rejetés par MercadoPago. Vérifiez-les sur la page des réglages.

Le client voit MercadoPago cannot process payments in: la devise du panier n'est pas celle de votre compte MercadoPago. MercadoPago ne convertit pas les devises.

Le formulaire de carte sécurisé ne se charge pas : le client voit The secure card form could not be loaded. Please reload the page or choose another payment method. Vérifiez la clé publique du mode actuel.

Le client voit Your payment was received, but the order could not be completed automatically: MercadoPago a encaissé le paiement, mais PrestaShop n'a pas pu créer la commande (par exemple parce que le module était désactivé à ce moment-là). Consultez le champ Log de la page du module : les erreurs sont toujours journalisées. Le client est invité à ne pas payer à nouveau ; la tentative de paiement ou la notification suivante pour le panier crée la commande sans nouveau débit.

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

Le remboursement échoue avec un message sur le mode : le paiement a été effectué en mode test ou production, et l'Access Token de ce mode n'est pas renseigné. Saisissez-le et réessayez.

Le remboursement échoue avec MercadoPago did not answer the refund request : vérifiez le paiement dans le panneau MercadoPago avant de réessayer.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox MercadoPago 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, la vérification de compte enregistrée et les journaux sont supprimés. Désactivé, tous les réglages sont conservés pour une future réinstallation. Les enregistrements de paiement et de remboursement MercadoPago ainsi que les statuts de commande Awaiting MercadoPago payment et MercadoPago payment on hold sont toujours conservés, de sorte que les commandes payées auparavant peuvent être remboursées après une réinstallation. Les commandes existantes conservent leurs notes de paiement et leurs ID de transaction.

MercadoPago est une marque commerciale de son titulaire respectif. Ce module n'est ni affilié à MercadoPago ni approuvé par MercadoPago.