Passerelle Mercado Pago Terminal
La passerelle Mercado Pago Terminal vous permet d’accepter des paiements en personne sur les terminaux Mercado Pago Point Smart depuis WCPOS. Le paiement est lancé depuis WooCommerce et finalisé sur le terminal ; la confirmation de Mercado Pago est ensuite enregistrée dans la commande.
Mercado Pago Terminal for WooCommerce est une nouvelle extension, et la version 0.1.0 est sa première version. Considérez-la comme une version bêta : commencez en mode Test avec le terminal virtuel de test Mercado Pago et effectuez un paiement de test avant d’accepter des paiements réels.
Fonctionnalités
Matériel Point Smart
Acceptez les paiements en personne sur les terminaux Mercado Pago Point Smart 1 et 2
Liste des terminaux en temps réel
Les terminaux sont récupérés en temps réel depuis votre compte ; les réglages proposent une action en un clic pour passer en mode PDV
Finalisation fiable
L’interrogation toutes les 2 secondes, le webhook Mercado Pago et une vérification en arrière-plan après 5 minutes confirment les paiements, même si le navigateur a été fermé
Remboursements depuis WooCommerce
Effectuez des remboursements complets ou partiels depuis l’écran de commande WooCommerce
Diagnostics intégrés
Vérifiez la connexion et l’état du webhook dans les réglages, et téléchargez un dossier d’assistance pour le dépannage
Fonctionnement
La passerelle utilise l’API Orders for Point dans le cloud de Mercado Pago. Le lancement d’un paiement crée une commande Mercado Pago correspondant au montant total de la commande WooCommerce et l’envoie au terminal sélectionné. La commande Mercado Pago expire après 5 minutes.
La page de paiement interroge Mercado Pago toutes les 2 secondes. Le webhook et une vérification en arrière-plan après 5 minutes peuvent également finaliser une commande payée, même si le navigateur a été fermé. Le webhook est facultatif, mais recommandé ; sans Webhook secret, les notifications sont tout de même traitées, mais leur signature n’est pas vérifiée.
Le terminal doit être en mode PDV (intégré). Les terminaux sont livrés en mode STANDALONE ; passez donc en mode PDV dans les réglages de la passerelle et redémarrez le terminal avant d’accepter des paiements.
Configuration
Installer Mercado Pago Terminal for WooCommerce
Téléchargez l’archive zip de l’extension (et non l’archive zip du code source GitHub) depuis la page des versions GitHub. Téléversez-la via Extensions > Ajouter > Téléverser une extension et activez-la avec WooCommerce installé et activé.
Ajouter vos identifiants Mercado Pago
- Accédez à
WP Admin > WooCommerce > Réglages > Paiementset ouvrez Mercado Pago Terminal - Choisissez Mode :
Testutilise le terminal virtuel de test ;Liveutilise les terminaux réels - Collez le jeton Access token (
APP_USR-…) de votre application, disponible dans Mercado Pago → Your integrations → Credentials
Un jeton TEST- en mode Live envoie les paiements vers l’environnement de test. L’écran des réglages signale cette combinaison ; collez votre jeton de production avant d’accepter des paiements réels.
Enregistrer le webhook
- Dans Mercado Pago, accédez à Your integrations → votre application → Webhooks
- Ajoutez l’URL du webhook affichée sur l’écran des réglages de la passerelle
- Sélectionnez l’événement Order (Mercado Pago) et enregistrez
- Copiez la secret signature dans Webhook secret dans WooCommerce
Le webhook est facultatif. Les paiements sont tout de même finalisés par interrogation sans lui, mais la configuration du secret permet à l’extension de vérifier les signatures des webhooks.
Configurer vos terminaux
- Enregistrez puis rechargez l’écran des réglages. La liste déroulante Default terminal et le tableau Terminals affichent les terminaux de votre compte
- Pour un terminal affiché en mode STANDALONE, cliquez sur Switch to PDV, puis redémarrez le terminal
- Choisissez un Default terminal
- (Facultatif) Limitez Enabled terminals aux appareils que les caissiers peuvent sélectionner. Laissez le champ vide pour autoriser tous les terminaux ; le terminal par défaut enregistré reste disponible même s’il n’est pas sélectionné ici
- (Facultatif) Activez Lock terminal selection pour toujours utiliser le terminal par défaut et empêcher les caissiers de le modifier. Un terminal par défaut est requis
- Enregistrez vos réglages
Activer dans WCPOS
- Accédez à
WP Admin > POS > Réglages > Validation de la commande - Repérez la passerelle Mercado Pago Terminal et activez-la pour le PDV
- Enregistrez vos réglages
La case Enable/Disable dans l’écran des réglages WooCommerce contrôle uniquement le paiement de la boutique en ligne. WCPOS utilise cette passerelle dès qu’elle est configurée, que cette case soit cochée ou non.
Référence des réglages
| Réglage | Fonction |
|---|---|
| Enable/Disable | Active la passerelle pour le paiement dans la boutique en ligne. L’activation dans le PDV se règle sous POS > Réglages > Validation de la commande |
| Title | Libellé du paiement ; valeur par défaut : Mercado Pago Terminal |
| Description | Description du paiement ; valeur par défaut : Pay in person on a Mercado Pago Point terminal. |
| Mode | Test (par défaut) utilise le terminal virtuel de test ; Live utilise les terminaux réels avec des identifiants de production |
| Access token | Jeton de votre application depuis Mercado Pago → Your integrations → Credentials. Un jeton enregistré ne s’affiche plus ; laissez le champ vide pour le conserver |
| Webhook secret | Signature secrète des réglages de webhook Mercado Pago, utilisée pour vérifier les notifications |
| Default terminal | Terminal utilisé par défaut au paiement, récupéré en temps réel depuis votre compte. Un champ de texte apparaît si la liste ne peut pas être récupérée |
| Enabled terminals | Limite les terminaux que les caissiers peuvent sélectionner. Une liste vide autorise tous les terminaux ; le terminal par défaut reste toujours disponible. Masqué si la liste ne peut pas être chargée |
| Lock terminal selection | Utilise toujours le terminal par défaut afin que les caissiers ne puissent pas le modifier. Un terminal par défaut est requis |
| Checkout debug logs | Affiche Show logs, Copy et Clear dans le panneau de paiement. Désactivé par défaut ; activez cette option pour recueillir des journaux destinés à l’assistance |
| Log level | Off, Errors only ou Debug. La valeur par défaut est Debug dans cette version ; les requêtes et les réponses sont enregistrées après suppression des secrets |
Sous les champs, le tableau Mercado Pago Terminal diagnostics affiche le contrôle de l’API (notamment le nombre de terminaux et de PDV), la date de dernière vérification du webhook, l’environnement actif, l’état de configuration des identifiants, le terminal par défaut, l’URL du webhook et le lien vers les journaux de paiement.
Utilisation
Traitement des paiements
- Add Items : Ajoutez des produits à votre panier dans le PDV
- Select Gateway : Choisissez Mercado Pago Terminal comme mode de paiement
- Choose Terminal : Sélectionnez un terminal ou utilisez le terminal par défaut si la sélection est verrouillée
- Start Payment : Cliquez sur Start Terminal Payment pour envoyer le montant total de la commande au terminal
- Customer Payment : Suivez les messages d’état —
Sending to terminal…→Waiting for terminal…→Customer is paying on the terminal…— pendant que le client effectue le paiement sur le terminal - Finalisation automatique : Lorsque Mercado Pago confirme le paiement, la commande est finalisée et le PDV affiche le reçu
Commandes de paiement
- Start Terminal Payment : Envoyez une nouvelle demande de paiement au terminal sélectionné
- Cancel Terminal Payment : Annulez uniquement avant que le terminal ne prenne en charge le paiement. Ensuite, annulez-le sur le terminal ou attendez son expiration après 5 minutes
- Rechargement de la page : Reprend un paiement déjà en cours
Reçus
Le terminal n’imprime pas de ticket. Utilisez le reçu du PDV une fois le paiement finalisé.
Remboursements
Ouvrez l’écran de remboursement de la commande WooCommerce et choisissez Refund via Mercado Pago Terminal pour effectuer un remboursement total ou partiel. Mercado Pago autorise les remboursements jusqu’à 90 jours après le paiement.
Certains acquéreurs de cartes n’autorisent les remboursements que sur le terminal. Dans ce cas, effectuez le remboursement sur le terminal et enregistrez un remboursement manuel dans WooCommerce.
Journaux et dossier d’assistance
Retrouvez les journaux dans WooCommerce > Status > Journaux, sous la source mercadopago-terminal. Le niveau de journalisation par défaut est Debug dans cette version. Les requêtes, réponses, webhooks et changements d’état des paiements sont enregistrés après masquage des secrets et des numéros de carte.
Cliquez sur Download support bundle dans l’écran des réglages de la passerelle pour télécharger un fichier .txt et le joindre à votre demande d’assistance. Il contient des informations sur l’environnement, les réglages avec les identifiants masqués, la liste des terminaux et leurs modes de fonctionnement, les tentatives de paiement des 10 commandes les plus récentes et les 500 dernières lignes de journal ; il ne contient rien qui permette d’effectuer des paiements.
Activez Checkout debug logs pour ajouter Show logs, Copy et Clear au panneau de paiement. L’activité de paiement est enregistrée dans les journaux WooCommerce, que cette option soit activée ou non.
Prérequis
Périmètre et limitations
- Le terminal débite le montant total de la commande. Le paiement d’une partie seulement de la commande sur le terminal n’est pas pris en charge
- Les pourboires ne sont pas pris en charge
- Les montants sont envoyés avec deux décimales. Les boutiques qui vendent en pesos chiliens ou colombiens doivent d’abord effectuer un paiement de test
- La validation de commande par blocs de la boutique en ligne n’est pas prise en charge
- L’extension ne déclare pas encore la compatibilité HPOS
Dépannage
Problèmes courants
Jeton d’accès refusé par Mercado Pago (HTTP 401)
- Le jeton d’accès est invalide ou obsolète
- Copiez un nouveau jeton depuis Your integrations → Credentials et enregistrez-le dans Access token
Aucun terminal n’est répertorié
- Si aucun terminal Point n’est associé au compte, connectez-vous au terminal avec ce compte Mercado Pago, passez en mode PDV et redémarrez-le
- Si Default terminal est un champ de texte plutôt qu’une liste déroulante, la liste n’a pas pu être récupérée. Vérifiez le jeton et les diagnostics, puis rechargez l’écran des réglages
Le terminal est en mode STANDALONE
- Les paiements intégrés nécessitent le mode PDV
- Cliquez sur Switch to PDV dans le tableau Terminals de l’écran des réglages, puis redémarrez le terminal
Le paiement est déjà sur le terminal
- Le terminal a pris en charge le paiement ; il n’est donc plus possible de l’annuler depuis WooCommerce
- Annulez le paiement sur le terminal ou attendez son expiration après 5 minutes. La page de paiement continue de vérifier son état
Le webhook n’a jamais été vérifié
- Si les diagnostics affichent Last verified webhook: never, vérifiez l’URL et le secret du webhook dans Mercado Pago
- Si Webhook secret est manquant, collez la secret signature fournie par Mercado Pago. Les paiements sont tout de même finalisés par interrogation, mais les notifications sans le secret ne font pas l’objet d’une vérification de signature
L’acquéreur de la carte a refusé le remboursement
- Certains acquéreurs n’autorisent les remboursements que sur le terminal ; Mercado Pago limite également les remboursements à 90 jours
- Effectuez le remboursement sur le terminal et enregistrez un remboursement manuel dans WooCommerce
Le paiement a expiré sur le terminal
- Les commandes Mercado Pago expirent après 5 minutes
- Relancez le paiement
Obtenir de l’aide
- Joignez le dossier d’assistance de l’écran des réglages de la passerelle à votre demande d’assistance
- Consultez le dépôt GitHub pour signaler les problèmes
- Contactez l’assistance Mercado Pago pour toute question concernant le compte ou le matériel