Gateway di pagamento Mercado Pago Terminal
Mercado Pago Terminal invia una vendita dalla cassa a un terminale Mercado Pago Point. Il cliente paga sul terminale e la cassa registra il pagamento quando Mercado Pago lo conferma.
Questa pagina parte dalla cassa. Amministratori del negozio: Configurare Mercado Pago Terminal spiega come impostare il token di accesso, il webhook e i terminali e come verificare che tutto funzioni.
Mercado Pago Terminal richiede WCPOS Pro 2.0 o successivo e la versione 1.0 o successiva dell'estensione.
La versione 1.0 non è ancora stata provata su un terminale Point reale né con un account Mercado Pago. Prima di accettare la carta di un cliente, effettua un piccolo pagamento con la tua carta e rimborsalo. La versione 1.0 è stata testata con un sostituto di Mercado Pago realizzato sulla base della documentazione di Mercado Pago. La versione 0.1, con un account reale e un Point Smart, ha elencato i terminali, ne ha passato uno alla modalità PDV e ha creato e annullato un pagamento. Nessuna delle due versioni è stata ancora provata per: un pagamento con carta completato, un rifiuto, l'annullamento dal terminale, le notifiche di Mercado Pago, i rimborsi e la sandbox di Mercado Pago.Cosa è stato e non è stato testato
Accettare un pagamento con carta
Con Apri e chiudi la cassa attivato, la cassa non registra pagamenti quando è chiusa e un pagamento già accettato con carta dovrebbe essere rimborsato. Consulta Casse per l'impostazione.
- Premi Cassa nel carrello e tocca il riquadro Mercado Pago Terminal nella scheda Pagamenti. Il tuo negozio potrebbe avergli assegnato un altro nome.
- Guarda sopra il tastierino. Se vedi Scegli un terminale, tocca il terminale alla tua cassa. Se vedi Terminale: seguito da un nome, quello è il terminale usato da questa cassa; premi Cambia per sceglierne un altro. La cassa ricorda la scelta.
- Per addebitare sulla carta una parte del saldo, inserisci l'importo. Il resto rimane da pagare con un altro pagamento. Saldo completo ripristina l'importo intero.
- Premi Invia … a Mercado Pago Terminal. La cassa mostra In attesa del cliente sul terminale.
- Il cliente paga sul terminale. Quando l'importo viene addebitato e non resta nulla da pagare, si apre la ricevuta. Se resta una parte, riscuotila con un altro riquadro.
Cosa indicano le fasi sulla cassa
Durante il pagamento, la cassa evidenzia in sequenza Inviato, Sul terminale e Incassato. Incassato significa che il denaro è stato prelevato. Approvato resta inattivo per Mercado Pago, che preleva il denaro in un'unica fase.
Il terminale non stampa uno scontrino. Stampa o invia per email la ricevuta del POS come al solito; consulta Ricevute alla cassa. Il terminale non gestisce le mance.
Annullare un pagamento
Sulla cassa, premi Annulla sul terminale. Funziona solo finché il pagamento non compare sullo schermo del terminale. Quando il cliente può vederlo, la cassa non può più annullarlo:
- Se il cliente può già vedere l'importo, annullalo direttamente sul terminale Mercado Pago oppure chiedi al cliente di non pagare.
- Attendi la cassa. Durante il controllo potrebbe restare su Annullamento — in attesa di conferma dal terminale. Il cliente può ancora pagare finché il terminale non annulla, quindi per ora non accettare il pagamento con un altro metodo.
- Quando il terminale annulla, la cassa mostra Pagamento annullato. Se nessuno annulla, Mercado Pago elimina il pagamento dopo 5 minuti e la cassa mostra Pagamento non riuscito: tempo scaduto sul terminale.
Se invece la cassa propone Rilascia questo pagamento, non premere il pulsante finché un responsabile non ha controllato Mercado Pago: consulta La cassa propone Rilascia questo pagamento in Altri messaggi.
Se qualcosa va storto
Quando il cliente potrebbe aver pagato
In questi casi la carta potrebbe essere già stata addebitata. Un responsabile deve prima controllare l'account Mercado Pago: il pagamento compare come Ordine n. seguito dal numero dell'ordine.
La carta è stata addebitata, ma l'ordine non è stato completato. Mercado Pago ha prelevato il denaro, ma la cassa non è riuscita a completare l'ordine. Non addebitare di nuovo. Ricarica l'app: la cassa proverà a completare la vendita; se l'ordine è ancora aperto, un responsabile lo completa. Consulta Carta addebitata, ordine non completato.
Pagamento non riuscito: il terminale ha confermato un importo diverso. Il terminale ha prelevato un importo diverso da quello inviato dalla cassa, che quindi non l'ha registrato; la carta potrebbe però essere stata addebitata. Chiedi a un responsabile di trovare il pagamento in Mercado Pago e confrontarlo con l'ordine.
La cassa si è chiusa o ha perso la connessione durante un pagamento. Non inviare di nuovo il pagamento da un'altra cassa. Se l'amministratore ha configurato il webhook, il negozio registra il pagamento anche con la cassa chiusa. Apri l'ordine: se risulta ancora non pagato, un responsabile deve controllare Mercado Pago prima che tu accetti di nuovo il pagamento.
Altri messaggi
Pagamento non riuscito: carta rifiutata
Premi Riprova per inviare di nuovo il pagamento al terminale oppure Scegli un altro metodo per pagare con un altro riquadro.
Pagamento non riuscito: seguito da un codice
Mercado Pago ha rifiutato il pagamento e ha indicato un motivo che la cassa non traduce, quindi mostra il codice originale di Mercado Pago. Premi Riprova oppure Scegli un altro metodo. Se il codice continua a comparire, invia il pacchetto per l'assistenza insieme al numero dell'ordine.
Il terminale è ancora occupato da un ordine precedente
Il terminale sta gestendo un altro pagamento. Completalo o annullalo sul terminale, quindi premi Riprova.
Pagamento non riuscito: tempo scaduto sul terminale
Nessuno ha pagato entro 5 minuti. Controlla il terminale, quindi premi Riprova.
La cassa propone Rilascia questo pagamento
Mercado Pago ha accettato l'annullamento, ma non lo ha ancora confermato. Rilasciato non significa annullato: premi il pulsante solo dopo che un responsabile ha controllato l'account Mercado Pago e verificato che non ci sia un pagamento approvato per l'ordine. A quel punto l'ordine può essere pagato in un altro modo.
Il riquadro Mercado Pago Terminal è disattivato o non compare
Sotto i riquadri, la cassa spiega il motivo. Consulta Quando un riquadro non è disponibile per l'elenco completo.
- In uso per l'ordine n. … — il terminale è occupato dal pagamento di un altro ordine. Completa o annulla quell'operazione, oppure premi Cambia e scegli un altro terminale.
- Richiede una connessione — la cassa è offline. Il pagamento con terminale passa dal negozio, quindi accetta un altro tipo di pagamento oppure attendi che la connessione torni disponibile.
- Nessun terminale configurato per Mercado Pago Terminal — nessuno dei tuoi terminali è in modalità PDV. Un responsabile li passa alla modalità PDV.
- Nessun riquadro — al gateway manca il token di accesso oppure non è attivato in WCPOS. Un responsabile controlla la configurazione.
Rimborsare un pagamento Mercado Pago
Il rimborso viene riaccreditato sulla carta del cliente tramite Mercado Pago, per l'intero importo o solo per una parte.
- Nel POS, apri il rimborso dell'ordine. Consulta Rimborsi.
- Scegli Rimborsa su Mercado Pago Terminal e premi Elabora rimborso.
- Il negozio chiede a Mercado Pago di effettuare il rimborso e aggiunge il risultato alle note dell'ordine.
Anche un rimborso in WP Admin con il pulsante di WooCommerce Rimborsa … tramite Mercado Pago Terminal funziona allo stesso modo. Anche le vendite effettuate con la versione 0.1 si rimborsano così.
Un rimborso rimane in sospeso
Quando ha risposto, Mercado Pago non aveva ancora completato il rimborso e il negozio potrebbe non aggiornarlo automaticamente. Prima di rimborsare di nuovo, trova il rimborso nel tuo account Mercado Pago: se è stato elaborato, il cliente ha già ricevuto il denaro.
Mercado Pago rifiuta il rimborso
Alcuni acquirer di carte consentono i rimborsi solo dal terminale. Effettua il rimborso sul terminale Point o nell'account Mercado Pago, quindi registralo in WooCommerce con Rimborsa … manualmente.
Ho effettuato il rimborso sul terminale o in Mercado Pago
Il negozio non riceve notifiche dei rimborsi effettuati lì, quindi l'ordine continua a mostrare il pagamento intero. Registra il rimborso in WooCommerce con Rimborsa … manualmente, per evitare che il denaro venga restituito due volte.
Configurare Mercado Pago Terminal
Un amministratore esegue questa operazione una volta per negozio in WP Admin, poi sceglie un terminale su ogni cassa. Il negozio raggiunge i terminali tramite Mercado Pago via Internet, quindi non occorre associarli e ogni cassa può usare qualsiasi dei tuoi terminali.
Requisiti
Se la valuta non ha centesimi, come il peso cileno, imposta Numero di decimali su 0 in WooCommerce > Impostazioni > General. Per questi account Mercado Pago rifiuta gli importi con decimali.
Installare l'estensione
Apri WP Admin > POS > Impostazioni > Estensioni, trova Mercado Pago Terminal for WooCommerce, installala e attivala. Serve la versione 1.0 o successiva; la versione 0.1 è destinata a WCPOS precedente alla 2.0. Consulta Estensioni.
Puoi anche caricare lo zip del plugin (non lo zip del codice sorgente) dalla pagina delle release di GitHub, scegliendo Plugin > Add Plugin > Carica plugin.
Senza WCPOS Pro 2.0, WP Admin mostra Mercado Pago Terminal requires WooCommerce POS Pro 2.0 or newer. e il gateway non viene aggiunto.
Inserire il token di accesso
Accedi a Mercado Pago Developers con l'account venditore e apri Le tue integrazioni. Se non hai un'applicazione, creane una e aprila. In Credenziali di produzione, copia il Token di accesso: inizia con APP_USR-. È il token per i pagamenti reali. Quello in Credenziali di test accede solo alla sandbox di Mercado Pago, non ancora provata con questa estensione.
Poi vai a WP Admin > WooCommerce > Impostazioni > Pagamenti e apri Mercado Pago Terminal.

- Abilita — lascialo deselezionato. Rende disponibile il gateway nel negozio online; il POS ha il proprio interruttore.
- Titolo — il nome del riquadro sulla cassa.
- Descrizione — viene mostrata sotto il titolo nella pagina di pagamento del negozio.
- Modalità — qui è mostrata l'impostazione predefinita, Test. Impostala su Produzione. L'indicazione sotto il campo non è aggiornata: a determinare se i pagamenti sono reali è il token di accesso, non Modalità.
- Token di accesso — incolla qui il token di produzione. Dopo il salvataggio, il campo rimane vuoto: lascialo vuoto per mantenere il token salvato.
- Segreto del webhook — per ora lascialo vuoto. Lo inserirai quando aggiungerai il webhook.
Fai clic su Salva le modifiche.
Aggiungere il webhook
Il webhook permette a Mercado Pago di avvisare subito il negozio quando un pagamento termina. I pagamenti funzionano anche senza, perché la cassa e il negozio continuano a interrogare Mercado Pago; configuralo comunque affinché un ordine pagato venga completato anche se la cassa si è chiusa.
- Copia l'URL del webhook dalla descrizione sotto Segreto del webhook. Termina con
wp-json/wcpos/v2/payments/webhook?provider=mercadopago. - In Mercado Pago Developers, apri Le tue integrazioni, la tua applicazione e poi Webhook. Aggiungi l'URL e seleziona l'evento Ordine (Mercado Pago).
- Copia la firma segreta mostrata da Mercado Pago, incollala in Segreto del webhook e fai clic su Salva le modifiche.
Il negozio rifiuta tutte le notifiche che non sono firmate con quel segreto, quindi un webhook senza segreto non ha effetto.
Passare i terminali alla modalità PDV
I terminali Point vengono forniti in modalità STANDALONE, in cui non possono accettare pagamenti da una cassa. Al pagamento sono disponibili solo i terminali in modalità PDV.
- Se non l'hai già fatto, accedi su ogni terminale con lo stesso account Mercado Pago.
- Ricarica la pagina delle impostazioni di Mercado Pago Terminal. Sotto Diagnostica di Mercado Pago, una tabella elenca ogni terminale con il relativo ID, il nome Terminale e la Modalità.
- Fai clic su Passa a PDV per ogni terminale in modalità STANDALONE, poi riavvia quel terminale. Mercado Pago richiede il riavvio.
La tabella elenca fino a 50 terminali.
Attivarlo in WCPOS
Vai a WP Admin > POS > Impostazioni > Pagamento, trova Mercado Pago Terminal nella tabella Gateway di pagamento e attiva Abilitato. Questa schermata salva automaticamente le modifiche; non c'è un pulsante Salva.

- Mercado Pago Terminal — la riga dell'estensione nella tabella Gateway di pagamento.
- Abilitato — l'interruttore accanto all'ID del gateway; attivalo. Dopo il ricaricamento, la cassa mostra il riquadro Mercado Pago Terminal.
Lascia disattivato Abilita nella pagina delle impostazioni di WooCommerce. Il POS usa il gateway quando Abilitato è attivo qui, indipendentemente dal fatto che quella casella sia selezionata. Consulta Impostazioni della cassa.
Scegliere il terminale per ogni cassa
Su ogni cassa, apri Impostazioni > Lettori di carte. I terminali sono elencati in Lettori smart, con il nome assegnato da Mercado Pago. Un terminale indicato come Offline non è ancora stato convertito: consulta Passare i terminali alla modalità PDV. Premi Usa questo lettore sul terminale presente a quella cassa; la riga mostra Selezionato. Il cassiere può comunque premere Cambia al pagamento.
Se c'è un solo terminale in modalità PDV, non c'è nulla da scegliere: risulta già Selezionato su ogni cassa. Consulta Scegliere un lettore smart.
Verificare che funzioni
-
Nella pagina delle impostazioni di Mercado Pago Terminal, la riga sotto Diagnostica di Mercado Pago mostra un messaggio:
Credenziali accettate. Riavvia il terminale dopo averlo passato alla modalità PDV.
Significa che Mercado Pago ha accettato il token di accesso. Se compare Mercado Pago access token is missing., non è stato salvato alcun token; qualsiasi altro testo è la risposta di Mercado Pago al token.
-
Sotto Modalità, ogni terminale che userai mostra PDV.
-
Su una cassa, ricarica il POS e premi Cassa. Il riquadro Mercado Pago Terminal compare tra i metodi di pagamento, con i terminali sopra il tastierino.
-
Effettua un piccolo acquisto con la tua carta, poi rimborsalo.
Aggiornamento dalla versione 0.1
- Aggiorna prima WCPOS, WCPOS Pro e l'app alla versione 2.0, poi aggiorna l'estensione.
- Aggiungi il nuovo webhook e il relativo segreto: consulta Aggiungere il webhook. L'indirizzo del webhook 0.1 non è più valido e le notifiche senza firma vengono rifiutate.
- Un pagamento in corso durante l'aggiornamento viene mantenuto. Non viene addebitato due volte.
- Queste impostazioni della versione 0.1 non sono più disponibili: Terminale predefinito, Terminali abilitati, Blocca la selezione del terminale, Log di debug della cassa e Livello di log. Ora le casse scelgono il terminale in Impostazioni > Lettori di carte.
- Modalità non seleziona più l'ambiente: verifica che il token di accesso salvato sia quello che vuoi usare.
- Ora il pagamento viene gestito nella scheda Pagamenti. La scheda Legacy continua a funzionare, ma solo per l'intero saldo.
- I rimborsi delle vendite effettuate con la versione 0.1 funzionano come al solito: consulta Rimborsare un pagamento Mercado Pago.
Riferimento delle impostazioni
In WP Admin > WooCommerce > Impostazioni > Pagamenti > Mercado Pago Terminal:
| Impostazione | Funzione |
|---|---|
| Abilita | Rende disponibile il gateway al pagamento nel negozio online. Lascialo disattivato; il POS ha un interruttore dedicato in POS > Impostazioni > Pagamento |
| Titolo | Il nome del riquadro sulla cassa. Il valore predefinito è Mercado Pago Terminal |
| Descrizione | Il valore predefinito è Pay in person on a Mercado Pago Point terminal. |
| Modalità | Test (predefinita) o Produzione. Impostala su Produzione per abbinarla a un token di produzione. È solo un'etichetta: il token di accesso determina se i pagamenti sono reali, a prescindere dalla descrizione del campo |
| Token di accesso | Mercado Pago Developers → Le tue integrazioni → la tua applicazione → Credenziali di produzione. Dopo il salvataggio non viene più mostrato, tranne per gli ultimi caratteri; lascialo vuoto per mantenerlo. Completa i pagamenti in corso prima di sostituirlo |
| Segreto del webhook | La firma segreta del webhook della tua applicazione in Mercado Pago. La descrizione mostra l'URL del webhook del negozio. Viene salvato e mostrato come il token |
Log e pacchetto per l'assistenza
In fondo alla pagina delle impostazioni trovi il pacchetto per l'assistenza, la riga di diagnostica e un link ai log.

- Riga di diagnostica — in questo negozio non configurato compare Mercado Pago access token is missing.. Dovresti vedere Credenziali accettate. e, sotto, l'elenco dei terminali.
- Visualizza log — apre
WooCommerce > Status > Log, sorgentemercadopago-terminal. - Scarica pacchetto per l'assistenza — un file per l'assistenza WCPOS.
I log registrano ogni richiesta a Mercado Pago e la relativa risposta, rimuovendo il token e i numeri delle carte.
Quando un pagamento non va a buon fine, fai clic su Scarica pacchetto per l'assistenza e invia il file all'assistenza WCPOS insieme al numero dell'ordine. Questo pulsante viene aggiunto da WCPOS Pro: il pacchetto include tutti i provider di pagamento POS del sito, con segreti e numeri delle carte rimossi. Indica anche quando il negozio ha ricevuto l'ultimo webhook firmato.
Funzioni non supportate
- Mance o autorizzazione ora e incasso in seguito.
- Stampare uno scontrino sul terminale.
- Accettare pagamenti con terminali in modalità STANDALONE.
- Registrare i rimborsi effettuati sul terminale o in Mercado Pago.
- Convertire valute: il negozio e l'account Mercado Pago devono usare la stessa valuta.
- Più di 50 terminali per account.
- Impostare da WP Admin un terminale predefinito per tutto il negozio o limitare i terminali utilizzabili dalle casse. Ogni cassa sceglie il proprio.
- HPOS (le tabelle degli ordini di WooCommerce): l'estensione non ne dichiara ancora il supporto.
Come funziona, per gli sviluppatori
Il gateway usa l'API Orders di Mercado Pago per Point (POST /v1/orders con type: point), tramite i provider di pagamento di WCPOS Pro. Ogni pagamento crea un ordine Mercado Pago per l'importo indicato sulla cassa, con l'ID del terminale, print_on_terminal: no_ticket, un riferimento esterno per il pagamento e una chiave di idempotenza, così un nuovo tentativo non può addebitare due volte. L'ordine scade dopo 5 minuti (filtro mptfwc_order_expiration_time).
La cassa richiede lo stato ogni 2 secondi. Il webhook wp-json/wcpos/v2/payments/webhook?provider=mercadopago deve includere una x-signature valida (HMAC-SHA256 con il segreto del webhook); il corpo della richiesta non è mai considerato attendibile e il negozio recupera nuovamente l'ordine da Mercado Pago. Come misura di riserva, WooCommerce POS controlla i pagamenti senza risposta ogni 10 minuti.
I terminali provengono da /terminals/v1/list; solo quelli in modalità PDV risultano online. I filtri mptfwc_order_payload e mptfwc_poll_interval_ms della versione 0.1 non sono più disponibili.
Documentazione correlata
- Lettori di carte
- La scheda Legacy
- Rimborsi
- Impostazioni della cassa
- Segnala un problema su GitHub. Per account, credenziali e terminali, contatta Mercado Pago.