Passerelle de paiement Mercado Pago Terminal
Mercado Pago Terminal envoie une vente de la caisse à un terminal Mercado Pago Point. Le client paie sur le terminal et la caisse enregistre le paiement dès que Mercado Pago le confirme.
Cette page commence à la caisse. Administrateurs de boutique : Configurer Mercado Pago Terminal explique comment obtenir le jeton d’accès, configurer le webhook et les terminaux, puis vérifier que tout fonctionne.
Mercado Pago Terminal nécessite WCPOS Pro 2.0 ou une version ultérieure, ainsi que la version 1.0 ou ultérieure de l’extension.
La version 1.0 n’a pas encore été utilisée avec un vrai terminal Point ni un compte Mercado Pago. Avant d’encaisser la carte d’un client, effectuez un petit paiement avec votre propre carte, puis remboursez-le. La version 1.0 a été testée avec un substitut de Mercado Pago, créé à partir de sa documentation. Avec la version 0.1, un compte actif et un véritable Point Smart, la liste des terminaux s’affichait, l’un d’eux a été basculé en mode PDV et un paiement a été créé puis annulé. Aucune des deux versions n’a encore été testée pour : un paiement par carte accepté, un refus, une annulation sur le terminal, les notifications de Mercado Pago, les remboursements et l’environnement de test de Mercado Pago.Ce qui a été testé et ce qui ne l’a pas été
Encaisser un paiement par carte
Lorsque l’option Ouvrir et fermer la caisse est activée, la caisse n’enregistre aucun paiement tant qu’elle est fermée. Un paiement par carte déjà encaissé devrait alors être remboursé. Consultez le réglage dans Caisses.
- Appuyez sur Paiement dans le panier, puis sur la tuile Mercado Pago Terminal dans l’onglet Paiements. Votre boutique lui a peut-être donné un autre nom.
- Regardez au-dessus du clavier. Si Choisir un terminal s’affiche, appuyez sur le terminal à votre comptoir. Si Terminal : suivi d’un nom s’affiche, c’est celui utilisé par cette caisse ; appuyez sur Modifier pour en choisir un autre. La caisse mémorise votre choix.
- Pour encaisser une partie du solde sur la carte, saisissez le montant. Le reste demeure dû et devra être réglé par un autre paiement. Solde total rétablit le montant complet.
- Appuyez sur Envoyer … à Mercado Pago Terminal. La caisse affiche En attente du client sur le terminal.
- Le client paie sur le terminal. Lorsque le montant est encaissé et qu’il ne reste rien à payer, le reçu s’ouvre. S’il reste un solde, encaissez-le avec une autre tuile.
Signification des étapes affichées sur la caisse
Pendant le traitement du paiement, la caisse allume successivement Envoyé, Sur le terminal et Encaissé. Encaissé signifie que le montant a été prélevé. Approuvé reste éteint avec Mercado Pago, qui prélève le montant en une seule étape.
Le terminal n’imprime pas de ticket. Imprimez ou envoyez par e-mail le reçu du PDV comme d’habitude ; consultez Reçus à l’encaissement. Le terminal ne permet pas d’ajouter de pourboire.
Annuler un paiement
Sur la caisse, appuyez sur Annuler sur le terminal. Cette action n’est possible que jusqu’à ce que le paiement apparaisse à l’écran du terminal. Dès que le client peut le voir, la caisse ne peut plus l’annuler :
- Si le client voit déjà le montant, annulez-le directement sur le terminal Mercado Pago, ou demandez au client de ne pas payer.
- Attendez que la caisse réagisse. Elle peut afficher Annulation en cours — en attente de confirmation du terminal pendant la vérification. Le client peut encore payer tant que le terminal n’a pas annulé le paiement : n’encaissez donc pas autrement pour le moment.
- La caisse affiche Paiement annulé une fois l’annulation effectuée par le terminal. Si personne n’annule, Mercado Pago abandonne le paiement après 5 minutes et la caisse affiche Échec du paiement : délai dépassé sur le terminal.
Si la caisse propose plutôt Libérer ce paiement, ne cliquez pas avant qu’un responsable ait vérifié le compte Mercado Pago : consultez La caisse propose Libérer ce paiement dans la section Autres messages.
En cas de problème
Lorsque le client a peut-être payé
Dans ces situations, la carte a peut-être déjà été débitée. Un responsable doit d’abord vérifier le compte Mercado Pago, où le paiement figure sous Commande n° suivi du numéro de commande.
La carte a été débitée, mais la commande n’a pas été finalisée. Mercado Pago a prélevé le montant, mais la caisse n’a pas pu finaliser la commande. Ne débitez pas à nouveau. Rechargez l’application : la caisse réessaiera de finaliser la vente. Si la commande est toujours ouverte, un responsable la finalisera. Consultez Carte débitée, commande non finalisée.
Échec du paiement : le terminal a confirmé un montant différent. Le terminal a prélevé un montant différent de celui envoyé par la caisse. Celle-ci ne l’a donc pas enregistré, mais la carte a peut-être été débitée. Demandez à un responsable de retrouver le paiement dans Mercado Pago et de le comparer à la commande.
La caisse s’est fermée ou a perdu sa connexion pendant un paiement. Ne relancez pas le paiement depuis une autre caisse. Si votre administrateur a configuré le webhook, votre boutique enregistre le paiement même si la caisse est fermée. Ouvrez la commande : si elle apparaît toujours comme impayée, un responsable doit vérifier Mercado Pago avant tout nouvel encaissement.
Autres messages
Échec du paiement : carte refusée
Appuyez sur Réessayer pour renvoyer le paiement au terminal, ou sur Choisir un autre moyen pour payer avec une autre tuile.
Échec du paiement : suivi d’un code
Mercado Pago a refusé le paiement et indiqué une raison que la caisse ne peut pas traduire ; elle affiche donc le code de Mercado Pago. Appuyez sur Réessayer ou Choisir un autre moyen. Si le même code revient, envoyez le dossier de diagnostic pour l’assistance avec le numéro de commande.
Le terminal est toujours occupé par une commande précédente
Le terminal traite un autre paiement. Terminez-le ou annulez-le sur le terminal, puis appuyez sur Réessayer.
Échec du paiement : délai dépassé sur le terminal
Personne n’a payé dans les 5 minutes. Vérifiez le terminal, puis appuyez sur Réessayer.
La caisse propose Libérer ce paiement
Mercado Pago a accepté l’annulation, mais ne l’a pas encore confirmée. « Libéré » ne signifie pas « annulé » : cliquez uniquement après qu’un responsable a vérifié votre compte Mercado Pago et confirmé qu’aucun paiement approuvé n’est associé à la commande. Celle-ci peut alors être réglée par un autre moyen.
La tuile Mercado Pago Terminal est grisée ou absente
Sous les tuiles, la caisse indique la raison. Consultez Lorsqu’une tuile ne peut pas être utilisée pour voir toutes les raisons possibles.
- Utilisé par la commande n°… — le terminal traite le paiement d’une autre commande. Terminez ou annulez ce paiement, ou appuyez sur Modifier pour choisir un autre terminal.
- Connexion requise — la caisse est hors ligne. Le paiement par terminal passe par votre boutique : choisissez un autre moyen de paiement ou attendez le rétablissement de la connexion.
- Aucun terminal configuré pour Mercado Pago Terminal — aucun de vos terminaux n’est en mode PDV. Un responsable doit les passer en mode PDV.
- Aucune tuile — la passerelle n’a pas de jeton d’accès ou n’est pas activée dans WCPOS. Un responsable doit vérifier la configuration.
Rembourser un paiement Mercado Pago
Le remboursement est effectué par Mercado Pago sur la carte du client, pour la totalité du montant ou une partie de celui-ci.
- Dans le PDV, ouvrez le remboursement de la commande. Consultez Remboursements.
- Choisissez Rembourser via Mercado Pago Terminal et appuyez sur Traiter le remboursement.
- Votre boutique demande le remboursement à Mercado Pago et ajoute le résultat aux notes de la commande.
Un remboursement dans WP Admin avec le bouton WooCommerce Rembourser … via Mercado Pago Terminal fonctionne de la même manière. Les ventes effectuées avec la version 0.1 se remboursent également ainsi.
Un remboursement reste en attente
Mercado Pago n’avait pas terminé le remboursement au moment de sa réponse, et votre boutique ne le mettra peut-être pas à jour automatiquement. Retrouvez le remboursement dans votre compte Mercado Pago avant d’en effectuer un autre : s’il a été traité, le client a reçu son argent.
Mercado Pago refuse le remboursement
Certains acquéreurs de cartes n’autorisent les remboursements que sur le terminal. Effectuez le remboursement sur le terminal Point ou dans votre compte Mercado Pago, puis enregistrez-le dans WooCommerce avec Rembourser … manuellement.
J’ai effectué le remboursement sur le terminal ou dans Mercado Pago
Votre boutique n’est pas informée des remboursements effectués à ces endroits ; la commande affiche donc toujours le paiement complet. Enregistrez le remboursement dans WooCommerce avec Rembourser … manuellement, afin que le montant ne soit pas remboursé deux fois.
Configurer Mercado Pago Terminal
Un administrateur effectue cette configuration une fois par boutique dans WP Admin, puis choisit un terminal pour chaque caisse. Votre boutique communique avec chaque terminal via Mercado Pago sur Internet : aucun jumelage n’est nécessaire et chaque caisse peut utiliser n’importe lequel de vos terminaux.
Prérequis
Si votre devise n’a pas de centimes, comme le peso chilien, définissez Nombre de décimales sur 0 dans WooCommerce > Réglages > General. Mercado Pago refuse les montants décimaux pour ces comptes.
Installer l’extension
Ouvrez WP Admin > POS > Réglages > Extensions, recherchez Mercado Pago Terminal for WooCommerce, puis installez et activez l’extension. Vous avez besoin de la version 1.0 ou ultérieure ; la version 0.1 est destinée à WCPOS avant la version 2.0. Consultez Extensions.
Vous pouvez également téléverser le fichier zip de l’extension (et non le zip du code source) depuis la page des versions GitHub, dans Extensions > Add Plugin > Téléverser une extension.
Sans WCPOS Pro 2.0, WP Admin affiche Mercado Pago Terminal nécessite WooCommerce POS Pro 2.0 ou une version ultérieure. et la passerelle n’est pas ajoutée.
Saisir votre jeton d’accès
Connectez-vous à Mercado Pago Developers avec votre compte vendeur et ouvrez Vos intégrations. Créez une application si vous n’en avez pas, puis ouvrez-la. Dans Identifiants de production, copiez le Jeton d’accès : il commence par APP_USR-. Ce jeton permet les paiements réels. Celui de Identifiants de test donne uniquement accès à l’environnement de test de Mercado Pago, qui n’a pas été essayé avec cette extension.
Accédez ensuite à WP Admin > WooCommerce > Réglages > Paiements et ouvrez Mercado Pago Terminal.

- Activer — laissez cette case décochée. Elle propose la passerelle dans votre boutique en ligne ; le PDV possède son propre interrupteur.
- Titre — nom de la tuile à la caisse.
- Description — affichée sous le titre sur la page de paiement de la boutique.
- Mode — affiché ici sur sa valeur par défaut, Test. Sélectionnez Production. L’indication en dessous n’est plus à jour : c’est le jeton d’accès, et non le Mode, qui détermine si les paiements sont réels.
- Jeton d’accès — collez ici votre jeton de production. Une fois enregistré, le champ reste vide : laissez-le vide pour conserver le jeton enregistré.
- Secret du webhook — laissez ce champ vide pour le moment. Vous le renseignerez lorsque vous ajouterez le webhook.
Cliquez sur Enregistrer les modifications.
Ajouter le webhook
Le webhook permet à Mercado Pago d’informer votre boutique dès qu’un paiement est terminé. Les paiements fonctionnent aussi sans lui, car la caisse et votre boutique interrogent Mercado Pago, mais configurez-le afin qu’une commande payée soit finalisée même si la caisse est fermée.
- Copiez l’URL du webhook dans la description sous Secret du webhook. Elle se termine par
wp-json/wcpos/v2/payments/webhook?provider=mercadopago. - Dans Mercado Pago Developers, ouvrez Vos intégrations, votre application, puis Webhooks. Ajoutez l’URL et sélectionnez l’événement Commande (Mercado Pago).
- Copiez la signature secrète affichée par Mercado Pago, collez-la dans Secret du webhook, puis cliquez sur Enregistrer les modifications.
Votre boutique refuse toute notification qui n’est pas signée avec ce secret. Sans secret, le webhook ne fait donc rien.
Passer vos terminaux en mode PDV
Les terminaux Point sont livrés en mode STANDALONE, qui ne permet pas de recevoir des paiements depuis une caisse. Seuls les terminaux en mode PDV sont proposés à l’encaissement.
- Si ce n’est pas déjà fait, connectez chaque terminal au même compte Mercado Pago.
- Rechargez la page des réglages de Mercado Pago Terminal. Dans Diagnostics Mercado Pago, un tableau répertorie chaque terminal avec son ID, son nom Terminal et son Mode.
- Cliquez sur Passer en mode PDV pour chaque terminal en mode STANDALONE, puis redémarrez ce terminal. Mercado Pago exige ce redémarrage.
Le tableau répertorie jusqu’à 50 terminaux.
Activer l’option dans WCPOS
Accédez à WP Admin > POS > Réglages > Validation de la commande, recherchez Mercado Pago Terminal dans le tableau Passerelles de paiement et activez Activé. Cet écran enregistre les modifications au fur et à mesure ; il n’y a pas de bouton Enregistrer.

- Mercado Pago Terminal — ligne de l’extension dans le tableau Passerelles de paiement.
- Activé — interrupteur à côté de l’ID de la passerelle ; activez-le. Après rechargement, la caisse affiche la tuile Mercado Pago Terminal.
Laissez Activer désactivé dans la page des réglages WooCommerce. Le PDV utilise la passerelle dès que Activé est activé ici, que cette case soit cochée ou non. Consultez Réglages de paiement.
Choisir le terminal de chaque caisse
Sur chaque caisse, ouvrez Réglages > Lecteurs de cartes. Vos terminaux figurent sous Lecteurs intelligents, sous le nom que Mercado Pago leur attribue. Un terminal marqué Hors ligne n’a pas encore été basculé : consultez Passer vos terminaux en mode PDV. Appuyez sur Utiliser ce lecteur pour le terminal de ce comptoir ; sa ligne affiche alors Sélectionné. Le caissier peut toujours appuyer sur Modifier au moment du paiement.
S’il n’y a qu’un seul terminal en mode PDV, vous n’avez rien à choisir : il est déjà Sélectionné sur chaque caisse. Consultez Choisir un lecteur intelligent.
Vérifier le fonctionnement
-
Sur la page des réglages de Mercado Pago Terminal, la ligne sous Diagnostics Mercado Pago affiche un message :
Identifiants acceptés. Redémarrez le terminal après le passage en mode PDV.
Cela signifie que Mercado Pago a accepté le jeton d’accès. Si le message indique Le jeton d’accès Mercado Pago est manquant., aucun jeton n’est enregistré ; tout autre texte correspond à la réponse de Mercado Pago concernant le jeton.
-
Chaque terminal que vous utiliserez affiche PDV sous Mode.
-
Sur une caisse, rechargez le PDV et appuyez sur Paiement. La tuile Mercado Pago Terminal figure parmi les moyens de paiement, et vos terminaux sont affichés au-dessus du clavier.
-
Effectuez une petite vente avec votre propre carte, puis remboursez-la.
Mettre à niveau depuis la version 0.1
- Mettez d’abord WCPOS, WCPOS Pro et l’application à jour vers la version 2.0, puis mettez à jour l’extension.
- Ajoutez le nouveau webhook et son secret : consultez Ajouter le webhook. L’ancienne adresse du webhook 0.1 n’existe plus et les notifications non signées sont refusées.
- Un paiement en cours pendant la mise à niveau est conservé. Aucun montant n’est débité deux fois.
- Ces réglages de la version 0.1 ont été supprimés : Terminal par défaut, Terminaux activés, Verrouiller la sélection du terminal, Journaux de débogage du paiement et Niveau de journalisation. Les caisses choisissent désormais leur terminal dans Réglages > Lecteurs de cartes.
- Le Mode ne sélectionne plus l’environnement : vérifiez que le jeton d’accès enregistré est bien celui que vous souhaitez utiliser.
- Le paiement s’effectue désormais dans l’onglet Paiements. L’onglet Ancien fonctionne toujours, mais uniquement pour le solde complet.
- Les ventes effectuées avec la version 0.1 se remboursent comme d’habitude : consultez Rembourser un paiement Mercado Pago.
Référence des réglages
Dans WP Admin > WooCommerce > Réglages > Paiements > Mercado Pago Terminal :
| Réglage | Fonction |
|---|---|
| Activer | Propose la passerelle lors du paiement dans votre boutique en ligne. Laissez-la désactivée ; le PDV possède son propre interrupteur dans POS > Réglages > Validation de la commande |
| Titre | Nom de la tuile à la caisse. Valeur par défaut : Mercado Pago Terminal |
| Description | Valeur par défaut : Pay in person on a Mercado Pago Point terminal. |
| Mode | Test (par défaut) ou Production. Sélectionnez Production pour utiliser un jeton de production. Il s’agit uniquement d’une indication : le jeton d’accès détermine si les paiements sont réels, quelle que soit la description du champ |
| Jeton d’accès | Mercado Pago Developers → Vos intégrations → votre application → Identifiants de production. Le jeton n’est plus affiché après son enregistrement, à l’exception de ses derniers caractères ; laissez le champ vide pour le conserver. Terminez les paiements en cours avant de le remplacer |
| Secret du webhook | Signature secrète du webhook de votre application dans Mercado Pago. Sa description affiche l’URL du webhook de votre boutique. Enregistré et affiché comme le jeton |
Journaux et dossier de diagnostic pour l’assistance
Au bas de la page des réglages se trouvent le dossier de diagnostic pour l’assistance, la ligne de diagnostic et un lien vers les journaux.

- Ligne de diagnostic — Le jeton d’accès Mercado Pago est manquant. sur cette boutique qui n’est pas configurée. La vôtre devrait afficher Identifiants acceptés., avec vos terminaux répertoriés en dessous.
- Voir les journaux — ouvre
WooCommerce > Status > Journaux, sourcemercadopago-terminal. - Télécharger le dossier de diagnostic — fichier destiné à l’assistance WCPOS.
Les journaux consignent chaque requête envoyée à Mercado Pago et sa réponse, après suppression du jeton et des numéros de carte.
En cas de problème de paiement, cliquez sur Télécharger le dossier de diagnostic et envoyez le fichier à l’assistance WCPOS avec le numéro de commande. Ce bouton est ajouté par WCPOS Pro : le dossier couvre tous les fournisseurs de paiement PDV de votre site, après suppression des secrets et des numéros de carte. Il indique également la date de réception du dernier webhook signé par votre boutique.
Fonctionnalités non prises en charge
- Les pourboires, ou l’autorisation maintenant suivie de l’encaissement plus tard.
- Imprimer un ticket sur le terminal.
- Encaisser des paiements sur des terminaux en mode STANDALONE.
- Enregistrer les remboursements effectués sur le terminal ou dans Mercado Pago.
- Convertir des devises : la boutique et le compte Mercado Pago doivent utiliser la même devise.
- Plus de 50 terminaux par compte.
- Définir dans WP Admin un terminal par défaut pour toute la boutique ou limiter les terminaux utilisables par les caisses. Chaque caisse choisit le sien.
- HPOS (les tables de commandes de WooCommerce) : l’extension ne déclare pas encore sa prise en charge.
Fonctionnement pour les développeurs
La passerelle utilise l’API Orders de Mercado Pago pour Point (POST /v1/orders avec type: point), par l’intermédiaire des fournisseurs de paiement de WCPOS Pro. Chaque paiement crée une commande Mercado Pago correspondant au montant sur la caisse, avec l’ID du terminal, print_on_terminal: no_ticket, une référence externe pour le paiement et une clé d’idempotence afin qu’une nouvelle tentative ne puisse pas débiter deux fois. La commande expire au bout de 5 minutes (filtre mptfwc_order_expiration_time).
La caisse interroge l’état toutes les 2 secondes. Le webhook, wp-json/wcpos/v2/payments/webhook?provider=mercadopago, doit contenir un x-signature valide (HMAC-SHA256 avec le secret du webhook) ; son corps n’est jamais considéré comme fiable et la boutique récupère à nouveau la commande auprès de Mercado Pago. WooCommerce POS vérifie les paiements sans réponse toutes les 10 minutes par mesure de précaution.
Les terminaux proviennent de /terminals/v1/list ; seuls ceux en mode PDV sont considérés comme en ligne. Les filtres mptfwc_order_payload et mptfwc_poll_interval_ms de la version 0.1 ont été supprimés.
Documentation connexe
- Lecteurs de cartes
- L’onglet Ancien
- Remboursements
- Réglages de la caisse
- Signaler un problème sur GitHub. Pour votre compte, vos identifiants et vos terminaux, contactez Mercado Pago.