Gateway Mercado Pago Terminal
Il gateway Mercado Pago Terminal consente di accettare pagamenti di persona sui terminali Mercado Pago Point Smart tramite WCPOS. Il pagamento viene avviato da WooCommerce e completato sul terminale; la conferma di Mercado Pago viene quindi riportata nell'ordine.
Mercado Pago Terminal for WooCommerce è una nuova estensione e la versione 0.1.0 è la sua prima release. Considerala una versione beta: inizia in modalità Test con il terminale virtuale sandbox di Mercado Pago ed esegui un pagamento di prova prima di accettare pagamenti reali.
Funzionalità
Hardware Point Smart
Accetta pagamenti di persona sui terminali Mercado Pago Point Smart 1 e 2
Elenco terminali in tempo reale
I terminali vengono recuperati in tempo reale dal tuo account; nelle impostazioni puoi passare a PDV con un solo clic
Completamento affidabile
Il controllo ogni 2 secondi, il webhook di Mercado Pago e una verifica in background dopo 5 minuti confermano i pagamenti, anche se il browser è stato chiuso
Rimborsi da WooCommerce
Invia rimborsi totali o parziali dalla schermata dell'ordine WooCommerce
Diagnostica integrata
Controlla la connessione e lo stato del webhook nelle impostazioni e scarica un pacchetto di assistenza per la risoluzione dei problemi
Come funziona
Il gateway usa Orders API for Point, l'API cloud di Mercado Pago. Quando avvii un pagamento, viene creato un ordine Mercado Pago per l'importo totale dell'ordine WooCommerce e inviato al terminale selezionato. L'ordine Mercado Pago scade dopo 5 minuti.
La pagina di pagamento controlla Mercado Pago ogni 2 secondi. Anche il webhook e una verifica in background dopo 5 minuti possono completare un ordine pagato, anche se il browser è stato chiuso. Il webhook è facoltativo ma consigliato; senza un Webhook secret, le notifiche vengono comunque elaborate, ma la firma non viene verificata.
Il terminale deve essere in modalità PDV (integrata). I terminali vengono forniti in modalità STANDALONE: passa a PDV nelle impostazioni del gateway e riavvia il terminale prima di accettare pagamenti.
Configurazione
Installa Mercado Pago Terminal for WooCommerce
Scarica l'archivio zip del plugin (non l'archivio zip del codice sorgente GitHub) dalla pagina delle release GitHub. Caricalo tramite Plugin > Aggiungi Nuovo > Carica plugin e attivalo dopo aver installato e attivato WooCommerce.
Aggiungi le credenziali Mercado Pago
- Vai a
WP Admin > WooCommerce > Impostazioni > Pagamentie apri Mercado Pago Terminal - Scegli Mode:
Testusa il terminale virtuale sandbox;Liveusa i terminali reali - Incolla nel campo Access token il token (
APP_USR-…) della tua applicazione, disponibile in Mercado Pago → Your integrations → Credentials
Un token TEST- in modalità Live invia i pagamenti alla sandbox. La schermata delle impostazioni segnala questa combinazione; incolla il token di produzione prima di accettare pagamenti reali.
Registra il webhook
- In Mercado Pago, vai a Your integrations → la tua applicazione → Webhooks
- Aggiungi l'URL del webhook mostrato nella schermata delle impostazioni del gateway
- Seleziona l'evento Order (Mercado Pago) e salva
- Copia la secret signature nel campo Webhook secret di WooCommerce
Il webhook è facoltativo. Senza, i pagamenti vengono comunque completati tramite controllo periodico; configurando il segreto, però, il plugin può verificare le firme dei webhook.
Configura i terminali
- Salva e ricarica la schermata delle impostazioni. Il menu a discesa Default terminal e la tabella Terminals mostrano i terminali del tuo account
- Per un terminale indicato in modalità STANDALONE, fai clic su Switch to PDV, quindi riavvia il terminale
- Scegli un Default terminal
- (Facoltativo) Limita Enabled terminals ai dispositivi selezionabili dai cassieri. Lascia il campo vuoto per consentire tutti i terminali; il terminale predefinito salvato rimane disponibile anche se non è selezionato qui
- (Facoltativo) Attiva Lock terminal selection per usare sempre il terminale predefinito e impedire ai cassieri di cambiarlo. È necessario impostare un terminale predefinito
- Salva le impostazioni
Attiva in WCPOS
- Vai a
WP Admin > POS > Impostazioni > Pagamento - Trova il gateway Mercado Pago Terminal e attivalo per il POS
- Salva le impostazioni
La casella Enable/Disable nella schermata delle impostazioni WooCommerce controlla solo il checkout del negozio online. WCPOS usa questo gateway dopo la configurazione, indipendentemente dal fatto che la casella sia selezionata.
Riferimento delle impostazioni
| Impostazione | Funzione |
|---|---|
| Enable/Disable | Attiva il gateway per il checkout del negozio online. L'attivazione nel POS si gestisce in POS > Impostazioni > Pagamento |
| Title | L'etichetta del checkout; per impostazione predefinita è Mercado Pago Terminal |
| Description | La descrizione del checkout; per impostazione predefinita è Pay in person on a Mercado Pago Point terminal. |
| Mode | Test (predefinita) usa il terminale virtuale sandbox; Live usa terminali reali con credenziali attive |
| Access token | Il token della tua applicazione in Mercado Pago → Your integrations → Credentials. Un token salvato non viene mostrato di nuovo; lascia il campo vuoto per mantenerlo |
| Webhook secret | La secret signature delle impostazioni webhook di Mercado Pago, usata per verificare le notifiche |
| Default terminal | Il terminale usato per impostazione predefinita al checkout, recuperato in tempo reale dal tuo account. Se non è possibile recuperare l'elenco, viene mostrato un campo di testo |
| Enabled terminals | Limita i terminali selezionabili dai cassieri. Se vuoto, sono consentiti tutti; quello predefinito è sempre disponibile. Nascosto se non è possibile caricare l'elenco |
| Lock terminal selection | Usa sempre il terminale predefinito, impedendo ai cassieri di cambiarlo. Richiede un terminale predefinito |
| Checkout debug logs | Mostra Show logs, Copy e Clear nel pannello di pagamento. Disattivato per impostazione predefinita; attivalo quando raccogli i log per l'assistenza |
| Log level | Off, Errors only o Debug. In questa release è impostato per impostazione predefinita su Debug e registra richieste e risposte senza i segreti |
Sotto i campi, la tabella Mercado Pago Terminal diagnostics mostra il controllo API (incluso il numero di terminali e di PDV), l'ultimo webhook verificato, l'ambiente attivo, lo stato della configurazione delle credenziali, il terminale predefinito, l'URL del webhook e il link ai log dei pagamenti.
Utilizzo
Elaborazione dei pagamenti
- Add Items: aggiungi prodotti al carrello nel POS
- Select Gateway: scegli Mercado Pago Terminal come metodo di pagamento
- Choose Terminal: seleziona un terminale oppure usa quello predefinito se la selezione è bloccata
- Start Payment: fai clic su Start Terminal Payment per inviare l'importo totale dell'ordine al terminale
- Customer Payment: segui i messaggi di stato —
Sending to terminal…→Waiting for terminal…→Customer is paying on the terminal…— mentre il cliente completa il pagamento sul terminale - Automatic Completion: quando Mercado Pago conferma il pagamento, l'ordine viene completato e il POS passa alla ricevuta
Controlli di pagamento
- Start Terminal Payment: invia una nuova richiesta di pagamento al terminale selezionato
- Cancel Terminal Payment: annulla solo prima che il terminale riceva il pagamento. In seguito, annulla dal terminale o attendi la scadenza di 5 minuti
- Ricaricamento della pagina: riprende un pagamento già in corso
Ricevute
Il terminale non stampa ricevute. Usa la ricevuta del POS dopo il completamento del pagamento.
Rimborsi
Apri la schermata di rimborso dell'ordine WooCommerce e scegli Refund via Mercado Pago Terminal per inviare un rimborso totale o parziale. Mercado Pago consente i rimborsi fino a 90 giorni dopo il pagamento.
Alcuni acquirer di carte consentono rimborsi solo dal terminale. In tal caso, rimborsa dal terminale e registra un rimborso manuale in WooCommerce.
Log e pacchetto di assistenza
Trovi i log in WooCommerce > Status > Log, con origine mercadopago-terminal. In questa release il livello di log predefinito è Debug. Le richieste, le risposte, i webhook e le modifiche dello stato dei pagamenti vengono registrati oscurando segreti e numeri di carta.
Fai clic su Download support bundle nella schermata delle impostazioni del gateway per scaricare un file .txt da allegare alla richiesta di assistenza. Contiene dettagli sull'ambiente, impostazioni con credenziali mascherate, elenco dei terminali e modalità operative, tentativi di pagamento dei 10 ordini più recenti e le ultime 500 righe di log; non contiene nulla che possa essere usato per effettuare pagamenti.
Attiva Checkout debug logs per aggiungere Show logs, Copy e Clear al pannello di pagamento. L'attività dei pagamenti viene registrata nei log WooCommerce indipendentemente da questa impostazione.
Requisiti
Ambito e limitazioni
- Sul terminale viene addebitato l'importo totale dell'ordine. Non è possibile pagare solo una parte dell'ordine sul terminale
- Le mance non sono supportate
- Gli importi vengono inviati con due decimali. I negozi che vendono in pesos cileni o colombiani dovrebbero prima verificare con un pagamento di prova
- Il checkout Blocks del negozio online non è supportato
- Il plugin non dichiara ancora la compatibilità con HPOS
Risoluzione dei problemi
Problemi comuni
Mercado Pago ha rifiutato il token di accesso (HTTP 401)
- Il token di accesso non è valido o è scaduto
- Copia un nuovo token da Your integrations → Credentials e salvalo in Access token
Non è elencato alcun terminale
- Se all'account non è collegato alcun terminale Point, accedi al terminale con quell'account Mercado Pago, passa a PDV e riavvialo
- Se Default terminal è un campo di testo anziché un menu a discesa, non è stato possibile recuperare l'elenco. Controlla il token e la diagnostica, quindi ricarica la schermata delle impostazioni
Il terminale è in modalità STANDALONE
- I pagamenti integrati richiedono la modalità PDV
- Fai clic su Switch to PDV nella tabella Terminals della schermata delle impostazioni, quindi riavvia il terminale
Il pagamento è già sul terminale
- Il terminale ha ricevuto il pagamento, quindi non è più possibile annullarlo da WooCommerce
- Annulla dal terminale oppure attendi la scadenza di 5 minuti. La pagina di pagamento continua a controllarne lo stato
Il webhook non è mai stato verificato
- Se la diagnostica mostra Last verified webhook: never, controlla l'URL e il segreto del webhook in Mercado Pago
- Se Webhook secret è assente, incolla la secret signature da Mercado Pago. I pagamenti vengono comunque completati tramite controllo periodico, ma le notifiche senza il segreto non vengono verificate tramite firma
L'acquirer della carta ha rifiutato il rimborso
- Alcuni acquirer consentono rimborsi solo dal terminale; Mercado Pago limita inoltre i rimborsi a 90 giorni
- Rimborsa dal terminale e registra un rimborso manuale in WooCommerce
Il pagamento è scaduto sul terminale
- Gli ordini Mercado Pago scadono dopo 5 minuti
- Avvia di nuovo il pagamento
Richiedere assistenza
- Allega il pacchetto di assistenza della schermata delle impostazioni del gateway alla richiesta di assistenza
- Visita il repository GitHub per segnalare problemi
- Contatta l'assistenza Mercado Pago per domande sull'account e sull'hardware