VibeFox MercadoPago for WooCommerce — Aide

Prérequis

WordPress : 6.0 ou ultérieur.

WooCommerce : 8.0 ou ultérieur, installé et activé. Sans WooCommerce, l'extension refuse de s'activer.

PHP : 8.0 ou ultérieur.

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 débite dans la devise du compte et ne convertit pas. Le moyen de paiement est donc masqué lorsque les devises ne correspondent pas.

Compte MercadoPago : il vous faut 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, il vous faut aussi 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 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_mercadopago_gateway dans /wp-content/plugins/ par FTP.

2. Cliquez sur Activate.

3. Ouvrez les réglages : WooCommerce > Settings > Payments > MercadoPago > Manage, ou cliquez sur Settings sous le nom de l'extension sur 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. 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).

6. Activez Enable / Disable et enregistrez. Testez avec les cartes de test MercadoPago (nom du titulaire APRO = approuvée, CONT = en attente, OTHE = refusée), puis décochez Test mode.

Configuration

Tous les réglages se trouvent sur une seule page : WooCommerce > Settings > Payments > MercadoPago. 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 lorsque les identifiants du mode actuel manquent ou lorsque la devise de la boutique n'est pas celle de votre compte MercadoPago (le moyen de paiement est alors masqué sur la page de paiement), ainsi que lorsque les identifiants appartiennent à un compte d'un autre pays que Account country. Dans la liste des moyens de paiement, MercadoPago est signalé comme nécessitant une configuration tant que le mode actuel n'a pas ses identifiants.

À l'enregistrement, un identifiant dont le préfixe ne correspond pas à celui attendu (TEST- pour les champs de test, APP_USR- pour les champs de production) n'est pas enregistré : un message d'erreur s'affiche et la valeur précédente est conservée. L'extension demande aussi à MercadoPago à quel pays appartient l'Access Token. Si elle ne peut pas vérifier le jeton, si le compte n'est pas dans un pays pris en charge ou si le pays diffère de Account country, une erreur s'affiche. L'extension utilise alors le pays du compte.

Général

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

Title: le nom du moyen de paiement affiché au client sur la page de paiement. Par défaut : Credit or debit card (MercadoPago).

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

Compte MercadoPago

Récupérez 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ébitée, 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. 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 de document s'affiche pour tous sauf le Mexique.

Test mode: Use the test credentials (no real charges). En mode test, les identifiants TEST- sont utilisés et vous payez avec les cartes de test MercadoPago ; un badge TEST MODE s'affiche sur la page de paiement. Décochez pour débiter de vraies cartes avec les identifiants de production. Par défaut : activé. Pour tester avec un compte utilisateur de test MercadoPago (identifiants APP_USR-), saisissez les identifiants de ce compte dans les champs de production et désactivez le mode test.

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. Gardez-le secret.

Production Public Key: commence par APP_USR-.

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

Options de paiement

Maximum installments: le nombre maximal de paiements en plusieurs fois que le client peut choisir, de 1 à 24. 1 = paiement unique uniquement, et le champ des paiements en plusieurs fois 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 en général 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. L'extension envoie l'URL de notification avec chaque paiement lorsque votre site dispose d'une adresse publique. Vous pouvez aussi l'ajouter dans your application > Webhooks, événement Payments. L'URL est affichée dans cette section des réglages et ressemble à https://your-site/wc-api/wc_mpg_webhook/?source_news=webhooks.

Une notification n'est jamais considérée comme fiable en soi. L'extension relit le paiement depuis l'API MercadoPago avec l'Access Token de l'environnement dans lequel le paiement a été effectué, puis le rattache à la commande par ID de commande et clé de commande. Sans notifications, les commandes en examen restent En attente jusqu'à ce que vous les mettiez à jour manuellement.

L'extension 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 examen. La commande est placée En attente et finalisée par une notification ultérieure.

rejected, cancelled: le paiement a été refusé ou annulé. Une commande non payée est marquée Échoué.

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. Si elle est renseignée, les notifications sans x-signature valide sont rejetées (HTTP 401).

Avancé

Debug log: Log API requests and notifications écrit dans WooCommerce > Status > Logs, source wcp_mercadopago_gateway. Les Access Tokens, les jetons de carte et les données du payeur ne sont pas journalisés. Par défaut : désactivé.

Delete data on uninstall: Remove the gateway settings and logs when the plugin is deleted. Les ID de paiement MercadoPago enregistrés sur les commandes constituent l'historique des paiements et sont toujours conservés. Par défaut : désactivé.

Page 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 Document number, sélectionne le Card issuer et le nombre de Installments. Les options de paiement en plusieurs fois et les intérêts proviennent de MercadoPago pour le total de la commande.

Lorsque la commande est passée, MercadoPago transforme la carte en jeton à usage unique et votre boutique crée le paiement sur le serveur pour le total de la commande. L'e-mail et le nom de facturation, le document et le numéro de commande sont transmis à MercadoPago. Les montants en CLP et en COP sont débités sans décimales, arrondis à l'unité ; réglez donc le nombre de décimales de WooCommerce sur 0 pour ces devises.

Un paiement approuvé est marqué payé immédiatement et le client accède à la page « Commande reçue ». Un paiement en examen place la commande En attente ; le client accède également à la page « Commande reçue », et la notification finalise la commande. Une carte refusée affiche sur la page de paiement 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, de sorte que la carte n'est pas débitée deux fois. Un second clic pendant le paiement de la commande affiche This order is already being paid. Please wait a moment and check your e-mail before trying again.

Le moyen 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 ne prend que les cartes de crédit et de débit. Elle n'a pas de redirection vers Checkout Pro, pas de portefeuille MercadoPago ni d'argent sur compte, pas de paiement en espèces (Rapipago, OXXO, boleto et autres), pas de Pix, PSE ou Yape, pas de cartes enregistrées ou 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

Pending payment: la commande a été créée et aucun résultat de paiement n'est encore arrivé, par exemple après un délai d'attente.

Processing: MercadoPago a approuvé le paiement et le montant et la devise correspondent. Les commandes ne comportant que des produits virtuels téléchargeables passent à Terminée, le comportement par défaut de WooCommerce. La note de commande affiche l'ID de paiement MercadoPago et le nombre de paiements en plusieurs fois. L'ID de transaction est l'ID de paiement MercadoPago.

On hold: le paiement est en examen (en cours ou en attente) et attend la notification de MercadoPago. La commande est aussi placée En attente lorsque le montant ou la devise approuvé ne correspond pas à la commande, ou lorsque MercadoPago renvoie un statut inattendu. La note de commande l'explique.

Failed: le paiement a été refusé ou annulé. La note de commande affiche le statut et son détail. Le client peut payer à nouveau.

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

Remboursements

Ouvrez la commande, cliquez sur Refund, saisissez le montant et cliquez sur Refund via Credit or debit card (MercadoPago) (le bouton affiche votre Title). Les remboursements totaux et partiels sont pris en charge. 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, WooCommerce affiche MercadoPago refused the refund avec le motif et aucun remboursement n'est enregistré. Un remboursement approuvé ou en cours est ajouté aux notes de commande avec l'ID du remboursement.

Les remboursements et rétrofacturations effectués dans le panneau MercadoPago arrivent par notification et sont ajoutés aux notes de commande. Ils ne sont pas enregistrés automatiquement comme remboursements WooCommerce.

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 > MercadoPago. Collez la clé dans License key et cliquez sur Activate. Le bloc affiche le statut, par exemple la date jusqu'à laquelle la licence est active 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 l'emplacement depuis votre compte vibefox.net.

Sans clé active, MercadoPago n'est pas affiché aux clients sur la page de 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 connectés de la boutique voient toujours le moyen de paiement, marqué (unlicensed — visible to admins only), afin que vous puissiez 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 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 en arrière-plan.

Dépannage

MercadoPago does not appear at checkout: 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 de la boutique (ou la devise de la commande sur la page Pay for order) est celle de votre compte MercadoPago. La page des réglages indique celui qui manque.

The payment went through, but the order stays On hold or Pending payment: la notification n'est pas arrivée. L'extension n'envoie l'URL de notification que lorsque votre site dispose d'une adresse publique (pas localhost, ni un domaine .local ou .test). Ajoutez l'URL des réglages 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.

Notification answers invalid signature: le secret de signature appartient à une autre application, ou la notification ne contient pas de x-signature valide. Copiez à nouveau le secret ou laissez le champ vide.

Notification answers not for this store: le paiement n'appartient pas à une commande de cette boutique payée avec MercadoPago. La commande n'est pas modifiée.

A credential is not saved: l'erreur must start with indique que la valeur a un mauvais préfixe pour le champ. Les champs de test acceptent les identifiants TEST-, les champs de production les identifiants APP_USR-.

The customer sees This payment method is not configured correctly. Please choose another payment method or contact the store.: les identifiants du mode actuel manquent, ont un mauvais préfixe ou ont été rejetés par MercadoPago. Vérifiez-les sur la page des réglages.

The customer sees MercadoPago cannot process payments in: la devise de la commande n'est pas celle de votre compte MercadoPago. MercadoPago ne convertit pas les devises.

The secure card form does not load: le client voit The secure card form could not be loaded. Please reload the page or choose another payment method. Vérifiez la Public Key du mode actuel. Pour plus de détails, activez le Debug log et consultez WooCommerce > Status > Logs, source wcp_mercadopago_gateway.

Refund fails with a message about the 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.

Refund fails with MercadoPago did not answer the refund request: vérifiez le paiement dans le panneau MercadoPago avant de réessayer.

The license block shows an error: 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é sur le nouveau domaine. Si le serveur de licences est injoignable, l'extension continue de fonctionner avec le dernier statut connu.

Désinstallation

Désactiver l'extension conserve toutes les données. Pour la supprimer, désactivez-la puis supprimez-la sur 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, la vérification de compte enregistrée et les journaux ne sont supprimés que si Delete data on uninstall était activé. Sinon, ils sont conservés pour une future réinstallation. Les commandes existantes conservent leurs notes de paiement, leurs ID de paiement MercadoPago et leurs ID de transaction.

MercadoPago est une marque de son titulaire respectif. Cette extension n'est pas affiliée à MercadoPago et n'est pas approuvée par MercadoPago.