Gateway de pagamento Mercado Pago Terminal
O Mercado Pago Terminal envia uma venda do caixa para um terminal Mercado Pago Point. O cliente paga no terminal, e o caixa registra o pagamento assim que o Mercado Pago o confirma.
Esta página começa no caixa. Administradores da loja: em Configurar o Mercado Pago Terminal, você encontra instruções para obter o token de acesso, configurar o webhook e os terminais e verificar se tudo funcionou.
O Mercado Pago Terminal requer o WCPOS Pro 2.0 ou posterior e a versão 1.0 ou posterior da extensão.
A versão 1.0 ainda não foi usada com um terminal Point real nem com uma conta do Mercado Pago. Antes de receber o cartão de um cliente, faça um pagamento de valor baixo com seu próprio cartão e reembolse-o. A versão 1.0 foi testada com um substituto do Mercado Pago, criado com base na documentação do Mercado Pago. A versão 0.1, em uma conta ativa e em um Point Smart real, listou os terminais, mudou um deles para o modo PDV e criou e cancelou um pagamento. Ainda não foram testados em nenhuma das versões: pagamento de cartão aprovado, recusa, cancelamento no terminal, notificações do Mercado Pago, reembolsos e ambiente de testes do Mercado Pago.O que foi e não foi testado
Receber um pagamento com cartão
Com Abrir e fechar o caixa ativado, o caixa não registra pagamentos enquanto estiver fechado, e seria necessário reembolsar um pagamento com cartão já recebido. Consulte a configuração em Caixas.
- Pressione Finalizar Compra no carrinho e toque no bloco Mercado Pago Terminal na aba Pagamentos. Sua loja pode ter dado outro nome a ele.
- Olhe acima do teclado. Se aparecer Escolher um terminal, toque no terminal do seu balcão. Se aparecer Terminal: com um nome, esse é o terminal usado por este caixa; pressione Alterar para escolher outro. O caixa memoriza sua escolha.
- Para cobrar parte do saldo no cartão, digite o valor. O restante continuará pendente para outro pagamento. Saldo total preenche novamente o valor total.
- Pressione Enviar … para Mercado Pago Terminal. O caixa mostra Aguardando o cliente no terminal.
- O cliente paga no terminal. Quando o valor é cobrado e não resta nada a pagar, o recibo é aberto. Se restar algum valor, receba-o usando outro bloco.
O que significam as etapas no caixa
Enquanto o pagamento é processado, o caixa destaca Enviado, No terminal e Capturado, nessa ordem. Capturado significa que o valor foi cobrado. Aprovado permanece apagado no Mercado Pago, que cobra o valor em uma única etapa.
O terminal não imprime comprovantes. Imprima ou envie por e-mail o recibo do POS como de costume; consulte Recibos na finalização de compra. O terminal não permite gorjeta.
Cancelar um pagamento
No caixa, pressione Cancelar no terminal. Isso só funciona até o pagamento aparecer na tela do terminal. Quando o cliente já consegue vê-lo, o caixa não pode mais cancelá-lo:
- Se o cliente já consegue ver o valor, cancele-o no próprio terminal Mercado Pago ou peça ao cliente que não pague.
- Aguarde o caixa. Ele pode permanecer em Cancelando — aguardando confirmação do terminal enquanto verifica. O cliente ainda pode pagar até que o terminal cancele; portanto, não receba o pagamento de outra forma ainda.
- O caixa mostra Pagamento cancelado quando o terminal cancela. Se ninguém cancelar, o Mercado Pago descarta o pagamento após 5 minutos, e o caixa mostra Falha no pagamento: tempo esgotado no terminal.
Se o caixa oferecer Liberar este pagamento, não pressione essa opção até que um gerente confira o Mercado Pago: consulte O caixa oferece Liberar este pagamento em Outras mensagens.
Se algo der errado
Quando o cliente talvez já tenha pagado
Nesses casos, talvez o cartão já tenha sido cobrado. Primeiro, um gerente verifica a conta do Mercado Pago, onde o pagamento aparece como Pedido # seguido do número do pedido.
O cartão foi cobrado, mas o pedido não foi concluído. O Mercado Pago cobrou o valor, mas o caixa não conseguiu concluir o pedido. Não cobre novamente. Recarregue o aplicativo para que o caixa tente concluir a venda outra vez; se o pedido continuar aberto, um gerente deverá concluí-lo. Consulte Cartão cobrado, pedido não concluído.
Falha no pagamento: o terminal confirmou um valor diferente. O terminal cobrou um valor diferente do enviado pelo caixa. Por isso, o caixa não o registrou, mas talvez o cartão tenha sido cobrado. Peça a um gerente que localize o pagamento no Mercado Pago e compare-o com o pedido.
O caixa fechou ou perdeu a conexão durante um pagamento. Não envie o pagamento novamente de outro caixa. Se o administrador configurou o webhook, sua loja registra o pagamento mesmo com o caixa fechado. Abra o pedido: se ainda aparecer como não pago, um gerente deverá verificar o Mercado Pago antes de você receber o pagamento novamente.
Outras mensagens
Falha no pagamento: cartão recusado
Pressione Tentar novamente para enviar ao terminal outra vez ou Escolher outra forma para pagar com outro bloco.
Falha no pagamento: seguida de um código
O Mercado Pago recusou o pagamento e forneceu um motivo que o caixa não traduz; por isso, ele mostra o código original do Mercado Pago. Pressione Tentar novamente ou Escolher outra forma. Se o mesmo código continuar aparecendo, envie o pacote de suporte com o número do pedido.
O terminal ainda está ocupado com um pedido anterior
O terminal está processando outro pagamento. Conclua-o ou cancele-o no terminal e depois pressione Tentar novamente.
Falha no pagamento: tempo esgotado no terminal
Ninguém pagou em 5 minutos. Confira o terminal e pressione Tentar novamente.
O caixa oferece Liberar este pagamento
O Mercado Pago aceitou o cancelamento, mas ainda não o confirmou. Liberado não significa cancelado: pressione essa opção somente depois que um gerente verificar a conta do Mercado Pago e confirmar que não há nenhum pagamento aprovado para o pedido. Em seguida, o pedido poderá ser pago de outra forma.
O bloco Mercado Pago Terminal está esmaecido ou não aparece
A mensagem abaixo dos blocos explica o motivo. Consulte Quando não é possível usar um bloco para ver todos os motivos.
- Em uso pelo pedido #… — o terminal está ocupado com o pagamento de outro pedido. Conclua ou cancele esse pagamento, ou pressione Alterar e escolha outro terminal.
- Precisa de conexão — o caixa está offline. O pagamento no terminal passa pela sua loja; portanto, receba de outra forma ou aguarde a conexão.
- Nenhum terminal configurado para Mercado Pago Terminal — nenhum dos seus terminais está no modo PDV. Um gerente pode mudá-los para PDV.
- Nenhum bloco — o gateway não tem token de acesso ou não está ativado no WCPOS. Um gerente deve conferir a configuração.
Reembolsar um pagamento do Mercado Pago
O reembolso é feito pelo Mercado Pago e devolvido ao cartão do cliente, pelo valor total ou parcial.
- No POS, abra o reembolso do pedido. Consulte Reembolsos.
- Escolha Reembolsar no Mercado Pago Terminal e pressione Processar reembolso.
- Sua loja solicita o reembolso ao Mercado Pago e adiciona o resultado às notas do pedido.
Um reembolso no WP Admin, usando o botão Reembolsar … via Mercado Pago Terminal do WooCommerce, funciona da mesma forma. As vendas feitas com a versão 0.1 também podem ser reembolsadas assim.
O reembolso continua pendente
Quando respondeu, o Mercado Pago ainda não havia concluído o reembolso, e talvez sua loja não atualize o status automaticamente. Localize o reembolso na sua conta do Mercado Pago antes de reembolsar novamente: se ele foi processado, o cliente já recebeu o dinheiro.
O Mercado Pago recusa o reembolso
Algumas adquirentes de cartão só permitem reembolsos no terminal. Faça o reembolso no terminal Point ou na sua conta do Mercado Pago e depois registre-o no WooCommerce com Reembolsar … manualmente.
Fiz o reembolso no terminal ou no Mercado Pago
Sua loja não recebe informações sobre os reembolsos feitos nesses locais, então o pedido continua mostrando o pagamento integral. Registre o reembolso no WooCommerce com Reembolsar … manualmente para que o dinheiro não seja devolvido duas vezes.
Configurar o Mercado Pago Terminal
Um administrador faz essa configuração uma vez por loja no WP Admin e depois escolhe um terminal em cada caixa. Sua loja se conecta aos terminais pela internet usando o Mercado Pago, portanto não é necessário pareá-los, e qualquer caixa pode usar qualquer terminal.
Requisitos
Se sua moeda não tiver centavos, como o peso chileno, defina Número de casas decimais como 0 em WooCommerce > Configurações > General. O Mercado Pago recusa valores com casas decimais nessas contas.
Instalar a extensão
Abra WP Admin > POS > Configurações > Extensões, localize Mercado Pago Terminal for WooCommerce, instale e ative a extensão. Você precisa da versão 1.0 ou posterior; a versão 0.1 é para WCPOS anterior à versão 2.0. Consulte Extensões.
Você também pode enviar o arquivo zip do plugin (não o zip do código-fonte) pela página de versões do GitHub, em Plugins > Add Plugin > Enviar plugin.
Sem o WCPOS Pro 2.0, o WP Admin mostra Mercado Pago Terminal requer WooCommerce POS Pro 2.0 ou posterior. e o gateway não é adicionado.
Inserir seu token de acesso
Entre em Mercado Pago Developers com sua conta de vendedor e abra Suas integrações. Se ainda não tiver um aplicativo, crie um e abra-o. Em Credenciais de produção, copie o Token de acesso: ele começa com APP_USR-. Esse é o token para pagamentos reais. O token em Credenciais de teste só acessa o ambiente de testes do Mercado Pago, que ainda não foi testado com esta extensão.
Em seguida, acesse WP Admin > WooCommerce > Configurações > Pagamentos e abra Mercado Pago Terminal.

- Habilitar — deixe desmarcado. Essa opção oferece o gateway na sua loja online; o POS tem sua própria opção.
- Título — o nome do bloco exibido no caixa.
- Descrição — exibida abaixo do título na página de pagamento da loja.
- Modo — aparece aqui com o valor padrão, Teste. Altere para Produção. A dica abaixo está desatualizada: é o token de acesso, e não Modo, que determina se os pagamentos são reais.
- Token de acesso — cole aqui seu token de produção. Depois de salvo, o campo fica vazio; deixe-o vazio para manter o token salvo.
- Segredo do webhook — deixe em branco por enquanto. Preencha quando adicionar o webhook.
Clique em Salvar alterações.
Adicionar o webhook
O webhook permite que o Mercado Pago avise sua loja assim que um pagamento terminar. Os pagamentos também funcionam sem ele, porque o caixa e sua loja continuam consultando o Mercado Pago; mesmo assim, configure-o para que um pedido pago seja concluído se o caixa fechar.
- Copie a URL do webhook da descrição abaixo de Segredo do webhook. Ela termina em
wp-json/wcpos/v2/payments/webhook?provider=mercadopago. - No Mercado Pago Developers, abra Suas integrações, seu aplicativo e, em seguida, Webhooks. Adicione a URL e selecione o evento Pedido (Mercado Pago).
- Copie a assinatura secreta exibida pelo Mercado Pago, cole-a em Segredo do webhook e clique em Salvar alterações.
Sua loja recusa qualquer notificação que não esteja assinada com esse segredo; por isso, um webhook sem o segredo não faz nada.
Mudar seus terminais para PDV
Os terminais Point vêm no modo STANDALONE, no qual não podem receber pagamentos de um caixa. Só terminais no modo PDV são oferecidos na finalização de compra.
- Se ainda não tiver feito isso, entre em cada terminal usando a mesma conta do Mercado Pago.
- Recarregue a página de configurações do Mercado Pago Terminal. Em Diagnóstico do Mercado Pago, uma tabela lista cada terminal com seu ID, Terminal (nome) e Modo.
- Clique em Mudar para PDV em cada terminal no modo STANDALONE e depois reinicie esse terminal. O Mercado Pago exige a reinicialização.
A tabela lista até 50 terminais.
Ativar no WCPOS
Acesse WP Admin > POS > Configurações > Finalização de compra, localize Mercado Pago Terminal na tabela Gateways e ative Habilitado. Essa tela salva as alterações automaticamente; não há botão Salvar.

- Mercado Pago Terminal — a linha da extensão na tabela Gateways.
- Habilitado — a opção ao lado do ID do gateway; ative-a. Depois que o caixa recarregar, o bloco Mercado Pago Terminal será exibido.
Deixe Habilitar/Desabilitar desativado na página de configurações do WooCommerce. O POS usa o gateway assim que Habilitado estiver ativado aqui, independentemente de essa caixa estar marcada. Consulte Configurações da finalização de compra.
Escolher o terminal de cada caixa
Em cada caixa, abra Configurações > Leitores de cartão. Seus terminais aparecem em Leitores inteligentes, com os nomes dados pelo Mercado Pago. Um terminal marcado como Offline ainda não foi configurado; consulte Mudar seus terminais para PDV. Pressione Usar este leitor no terminal daquele balcão; a linha dele mostrará Selecionado. O caixa ainda pode pressionar Alterar na finalização da compra.
Se houver apenas um terminal no modo PDV, não será preciso escolher: ele já estará Selecionado em todos os caixas. Consulte Escolher um leitor inteligente.
Verificar se funcionou
-
Na página de configurações do Mercado Pago Terminal, a linha em Diagnóstico do Mercado Pago exibe uma mensagem:
Credenciais aceitas. Reinicie o terminal depois de mudar para PDV.
Isso significa que o Mercado Pago aceitou o token de acesso. Se aparecer O token de acesso do Mercado Pago está ausente., nenhum token foi salvo; qualquer outra mensagem é a resposta do Mercado Pago ao token.
-
Cada terminal que você usar mostra PDV em Modo.
-
Em um caixa, recarregue o POS e pressione Finalizar Compra. O bloco Mercado Pago Terminal estará entre as formas de pagamento, com seus terminais acima do teclado.
-
Faça uma venda de valor baixo com seu próprio cartão e depois reembolse-a.
Atualizar da versão 0.1
- Atualize primeiro o WCPOS, o WCPOS Pro e o aplicativo para a versão 2.0; depois, atualize a extensão.
- Adicione o novo webhook e o respectivo segredo: consulte Adicionar o webhook. O endereço do webhook da versão 0.1 foi removido, e as notificações sem assinatura são recusadas.
- Um pagamento em andamento durante a atualização continua sendo processado. Nenhum valor é cobrado duas vezes.
- Estas configurações da versão 0.1 foram removidas: Terminal padrão, Terminais habilitados, Bloquear seleção de terminal, Logs de debug da finalização de compra e Nível de log. Agora, cada caixa escolhe seu terminal em Configurações > Leitores de cartão.
- Modo não seleciona mais o ambiente: confira se o token de acesso salvo é o que você pretende usar.
- Agora, o pagamento é processado na aba Pagamentos. A aba Legado continua funcionando, mas somente para o saldo total.
- As vendas feitas na versão 0.1 continuam sendo reembolsadas da mesma forma: consulte Reembolsar um pagamento do Mercado Pago.
Referência de configurações
Em WP Admin > WooCommerce > Configurações > Pagamentos > Mercado Pago Terminal:
| Configuração | O que faz |
|---|---|
| Habilitar/Desabilitar | Oferece o gateway na finalização de compra da loja online. Deixe desativado; o POS tem uma opção própria em POS > Configurações > Finalização de compra |
| Título | O nome do bloco exibido no caixa. O padrão é Mercado Pago Terminal |
| Descrição | O padrão é Pay in person on a Mercado Pago Point terminal. |
| Modo | Teste (padrão) ou Produção. Defina como Produção para corresponder a um token de produção. É apenas um rótulo: o token de acesso determina se os pagamentos são reais, independentemente da descrição do campo |
| Token de acesso | Mercado Pago Developers → Suas integrações → seu aplicativo → Credenciais de produção. Depois de salvo, ele não é exibido, exceto pelos últimos caracteres; deixe o campo vazio para mantê-lo. Conclua os pagamentos em aberto antes de substituí-lo |
| Segredo do webhook | A assinatura secreta do webhook do seu aplicativo no Mercado Pago. A descrição mostra a URL do webhook da sua loja. É salvo e exibido como o token |
Logs e pacote de suporte
No fim da página de configurações ficam o pacote de suporte, a linha de diagnóstico e um link para os logs.

- Linha de diagnóstico — nesta loja ainda não configurada, aparece O token de acesso do Mercado Pago está ausente.. Na sua, deverá aparecer Credenciais aceitas., com os terminais listados abaixo.
- Ver logs — abre
WooCommerce > Status > Logs, origemmercadopago-terminal. - Baixar pacote de suporte — um arquivo para o suporte do WCPOS.
Os logs registram cada solicitação enviada ao Mercado Pago e a resposta recebida, sem o token nem os números dos cartões.
Quando ocorrer um problema com o pagamento, clique em Baixar pacote de suporte e envie o arquivo ao suporte do WCPOS junto com o número do pedido. O WCPOS Pro adiciona esse botão: o pacote inclui todos os provedores de pagamento do POS no seu site, sem segredos nem números de cartão. Ele também informa quando sua loja recebeu o último webhook assinado.
O que a extensão não oferece
- Gorjetas ou autorização agora e captura posterior.
- Impressão de comprovante no terminal.
- Recebimento de pagamentos em terminais no modo STANDALONE.
- Registro de reembolsos feitos no terminal ou no Mercado Pago.
- Conversão de moedas: a loja e a conta do Mercado Pago devem usar a mesma moeda.
- Mais de 50 terminais por conta.
- Definir um terminal padrão para toda a loja ou limitar no WP Admin quais terminais os caixas podem usar. Cada caixa escolhe o seu.
- HPOS (as tabelas de pedidos do WooCommerce): a extensão ainda não declara suporte a ele.
Como funciona, para desenvolvedores
O gateway usa a API Orders do Mercado Pago para Point (POST /v1/orders com type: point), por meio dos provedores de pagamento do WCPOS Pro. Cada pagamento cria um pedido no Mercado Pago com o valor informado no caixa, o ID do terminal, print_on_terminal: no_ticket, uma referência externa para o pagamento e uma chave de idempotência, para que uma nova tentativa não cobre duas vezes. O pedido expira após 5 minutos (filtro mptfwc_order_expiration_time).
O caixa consulta o status a cada 2 segundos. O webhook, wp-json/wcpos/v2/payments/webhook?provider=mercadopago, deve incluir uma x-signature válida (HMAC-SHA256 com o segredo do webhook); o conteúdo não é considerado confiável, e a loja consulta novamente o pedido no Mercado Pago. O WooCommerce POS verifica pagamentos sem resposta a cada 10 minutos como medida de segurança.
Os terminais são obtidos de /terminals/v1/list; somente os que estão no modo PDV são considerados online. Os filtros mptfwc_order_payload e mptfwc_poll_interval_ms da versão 0.1 foram removidos.
Documentação relacionada
- Leitores de cartão
- A aba Legado
- Reembolsos
- Configurações do caixa
- Relate um problema no GitHub. Para questões sobre sua conta, credenciais e terminais, entre em contato com o Mercado Pago.