Gateway do Mercado Pago Terminal
O gateway do Mercado Pago Terminal permite receber pagamentos presenciais em terminais Mercado Pago Point Smart pelo WCPOS. O pagamento é iniciado no WooCommerce e concluído no terminal, e a confirmação do Mercado Pago é registrada no pedido.
Mercado Pago Terminal for WooCommerce é uma nova extensão, e a versão 0.1.0 é seu primeiro lançamento. Considere-a uma versão beta: comece no modo Teste com o terminal virtual de sandbox do Mercado Pago e faça um pagamento de teste antes de aceitar pagamentos reais.
Recursos
Hardware Point Smart
Receba pagamentos presenciais nos terminais Mercado Pago Point Smart 1 e 2
Lista de terminais em tempo real
Os terminais são carregados em tempo real da sua conta, com uma ação de um clique para mudar para PDV nas configurações
Conclusão confiável
A consulta a cada 2 segundos, o webhook do Mercado Pago e uma verificação em segundo plano após 5 minutos confirmam os pagamentos, mesmo que o navegador tenha sido fechado
Reembolsos pelo WooCommerce
Envie reembolsos totais ou parciais pela tela do pedido do WooCommerce
Diagnóstico integrado
Verifique a conexão e o status do webhook nas configurações e baixe um pacote de suporte para solucionar problemas
Como funciona
O gateway usa a Orders API for Point na nuvem do Mercado Pago. Ao iniciar um pagamento, é criado um pedido do Mercado Pago com o valor total do pedido no WooCommerce e ele é enviado ao terminal selecionado. O pedido do Mercado Pago expira após 5 minutos.
A página de pagamento consulta o Mercado Pago a cada 2 segundos. O webhook e uma verificação em segundo plano após 5 minutos também podem concluir um pedido pago, mesmo que o navegador tenha sido fechado. O webhook é opcional, mas recomendado; sem configurar Segredo do webhook, as notificações ainda são processadas, mas as assinaturas não são verificadas.
O terminal precisa estar no modo PDV (integrado). Os terminais vêm no modo STANDALONE, então mude para PDV nas configurações do gateway e reinicie o terminal antes de aceitar pagamentos.
Configuração
Instalar Mercado Pago Terminal for WooCommerce
Baixe o arquivo zip do plugin (não o zip do código-fonte do GitHub) na página de lançamentos do GitHub. Envie-o por Plugins > Adicionar novo > Enviar plugin e ative-o com o WooCommerce instalado e ativo.
Adicionar suas credenciais do Mercado Pago
- Acesse
WP Admin > WooCommerce > Configurações > Pagamentose abra Mercado Pago Terminal - Escolha Modo:
Testusa o terminal virtual de sandbox;Liveusa terminais reais - Cole o Token de acesso (
APP_USR-…) da sua aplicação em Mercado Pago → Suas integrações → Credenciais
Um token TEST- no modo Live envia pagamentos para o sandbox. A tela de configurações avisa sobre essa combinação; cole seu token de produção antes de aceitar pagamentos reais.
Registrar o webhook
- No Mercado Pago, acesse Suas integrações → sua aplicação → Webhooks
- Adicione a URL do webhook exibida na tela de configurações do gateway
- Selecione o evento Pedido (Mercado Pago) e salve
- Copie a assinatura secreta para Segredo do webhook no WooCommerce
O webhook é opcional. Os pagamentos ainda são concluídos por consulta sem ele, mas configurar o segredo permite que o plugin verifique as assinaturas do webhook.
Configurar seus terminais
- Salve e recarregue a tela de configurações. O menu suspenso Terminal padrão e a tabela Terminais mostram os terminais da sua conta
- Para um terminal exibido no modo STANDALONE, clique em Mudar para PDV e depois reinicie o terminal
- Escolha um Terminal padrão
- (Opcional) Restrinja Terminais habilitados aos dispositivos que os caixas podem escolher. Deixe em branco para permitir todos os terminais; o padrão salvo continuará disponível mesmo que não seja selecionado aqui
- (Opcional) Ative Bloquear seleção de terminal para sempre usar o terminal padrão e impedir que os caixas o alterem. É necessário definir um terminal padrão
- Salve suas configurações
Ativar no WCPOS
- Acesse
WP Admin > POS > Configurações > Finalização de compra - Localize o gateway Mercado Pago Terminal e ative-o para o PDV
- Salve suas configurações
A caixa Ativar/Desativar na tela de configurações do WooCommerce controla apenas o checkout da loja virtual. O WCPOS usa este gateway depois de configurado, esteja essa caixa marcada ou não.
Referência das configurações
| Configuração | O que faz |
|---|---|
| Ativar/Desativar | Ativa o gateway para o checkout da loja virtual. A ativação no PDV é controlada em POS > Configurações > Finalização de compra |
| Título | O rótulo exibido no checkout; o padrão é Mercado Pago Terminal |
| Descrição | A descrição exibida no checkout; o padrão é Pay in person on a Mercado Pago Point terminal. |
| Modo | Test (padrão) usa o terminal virtual de sandbox; Live usa terminais reais com credenciais de produção |
| Token de acesso | O token da sua aplicação no Mercado Pago → Suas integrações → Credenciais. Um token salvo não é exibido novamente; deixe em branco para mantê-lo |
| Segredo do webhook | A assinatura secreta das configurações de webhook do Mercado Pago, usada para verificar notificações |
| Terminal padrão | O terminal usado por padrão no checkout, carregado em tempo real da sua conta. Um campo de texto é exibido se não for possível carregar a lista |
| Terminais habilitados | Restringe os terminais que os caixas podem escolher. Em branco permite todos os terminais; o padrão está sempre disponível. Oculto se não for possível carregar a lista |
| Bloquear seleção de terminal | Sempre usa o terminal padrão para impedir que os caixas o alterem. É necessário definir um terminal padrão |
| Logs de depuração do checkout | Exibe Mostrar logs, Copiar e Limpar no painel de pagamento. Desativado por padrão; ative ao coletar logs para o suporte |
| Nível de log | Off, Errors only ou Debug. O padrão nesta versão é Debug, que registra requisições e respostas sem os segredos |
A tabela Diagnóstico do Mercado Pago Terminal abaixo dos campos mostra a verificação da API (incluindo a quantidade de terminais e PDVs), o último webhook verificado, o ambiente ativo, se as credenciais estão configuradas, o terminal padrão, a URL do webhook e o link para os logs de pagamento.
Uso
Processamento de pagamentos
- Adicionar itens: adicione produtos ao carrinho no PDV
- Selecionar gateway: escolha Mercado Pago Terminal como método de pagamento
- Escolher terminal: selecione um terminal ou use o padrão quando a seleção estiver bloqueada
- Iniciar pagamento: clique em Iniciar pagamento no terminal para enviar o valor total do pedido ao terminal
- Pagamento do cliente: acompanhe as mensagens de status —
Sending to terminal…→Waiting for terminal…→Customer is paying on the terminal…— enquanto o cliente conclui o pagamento no terminal - Conclusão automática: quando o Mercado Pago confirmar o pagamento, o pedido será concluído e o PDV abrirá o recibo
Controles de pagamento
- Iniciar pagamento no terminal: envia uma nova solicitação de pagamento ao terminal selecionado
- Cancelar pagamento no terminal: cancela somente antes de o terminal receber o pagamento. Depois disso, cancele no terminal ou aguarde a expiração após 5 minutos
- Recarregar a página: retoma um pagamento em andamento
Recibos
O terminal não imprime comprovante. Use o recibo do PDV após a conclusão do pagamento.
Reembolsos
Abra a tela de reembolso do pedido no WooCommerce e escolha Reembolsar pelo Mercado Pago Terminal para enviar um reembolso total ou parcial. O Mercado Pago permite reembolsos até 90 dias após o pagamento.
Algumas adquirentes de cartão só permitem reembolsos no terminal. Nesse caso, faça o reembolso no terminal e registre um reembolso manual no WooCommerce.
Logs e pacote de suporte
Encontre os logs em WooCommerce > Status > Logs, na origem mercadopago-terminal. O nível de log padrão nesta versão é Debug. Requisições, respostas, webhooks e alterações no estado do pagamento são registrados com segredos e números de cartão ocultos.
Clique em Baixar pacote de suporte na tela de configurações do gateway para baixar um arquivo .txt e anexá-lo à sua solicitação de suporte. Ele contém detalhes do ambiente, configurações com credenciais ocultas, a lista de terminais e modos de operação, tentativas de pagamento dos 10 pedidos mais recentes e as últimas 500 linhas do log; não é possível usá-lo para receber pagamentos.
Ative Logs de depuração do checkout para adicionar Mostrar logs, Copiar e Limpar ao painel de pagamento. A atividade de pagamento é registrada nos logs do WooCommerce independentemente dessa configuração.
Requisitos
Escopo e limitações
- O valor cobrado no terminal é o total integral do pedido. Não é possível pagar apenas parte do pedido no terminal
- Não há suporte a gorjetas
- Os valores são enviados com duas casas decimais. Lojas que vendem em pesos chilenos ou colombianos devem primeiro fazer um pagamento de teste
- O checkout em blocos da loja virtual não é compatível
- O plugin ainda não declara compatibilidade com HPOS
Solução de problemas
Problemas comuns
Token de acesso recusado pelo Mercado Pago (HTTP 401)
- O token de acesso é inválido ou está desatualizado
- Copie um token novo em Suas integrações → Credenciais e salve-o em Token de acesso
Nenhum terminal listado
- Se não houver terminais Point vinculados à conta, entre no terminal com essa conta do Mercado Pago, mude para PDV e reinicie-o
- Se Terminal padrão for um campo de texto em vez de um menu suspenso, não foi possível carregar a lista. Verifique o token e os diagnósticos e recarregue a tela de configurações
O terminal está no modo STANDALONE
- Pagamentos integrados exigem o modo PDV
- Clique em Mudar para PDV na tabela Terminais da tela de configurações e reinicie o terminal
O pagamento já está no terminal
- O terminal recebeu o pagamento, portanto não é mais possível cancelá-lo pelo WooCommerce
- Cancele no terminal ou aguarde a expiração após 5 minutos. A página de pagamento continua verificando o status
O webhook nunca foi verificado
- Verifique a URL e o segredo do webhook no Mercado Pago se os diagnósticos mostrarem Último webhook verificado: nunca
- Se Segredo do webhook estiver vazio, cole a assinatura secreta do Mercado Pago. Os pagamentos ainda são concluídos por consulta, mas as notificações sem o segredo não têm a assinatura verificada
A adquirente do cartão recusou o reembolso
- Algumas adquirentes só permitem reembolsos no terminal; o Mercado Pago também limita os reembolsos a 90 dias
- Faça o reembolso no terminal e registre um reembolso manual no WooCommerce
O pagamento expirou no terminal
- Os pedidos do Mercado Pago expiram após 5 minutos
- Inicie o pagamento novamente
Como obter ajuda
- Anexe o pacote de suporte da tela de configurações do gateway à sua solicitação de suporte
- Acesse o repositório do GitHub para relatar problemas
- Entre em contato com o suporte do Mercado Pago para dúvidas sobre conta e hardware