Como integrar o Mercado Pago ao sistema de PDV via API em 2026

Para integrar o Mercado Pago ao seu PDV ou ERP via API, o processo segue quatro etapas: criar uma aplicação no painel do Mercado Pago Developers para obter credenciais, escolher o modelo de integração presencial (QR Code, API Point ou TEF), autenticar as chamadas via Access Token e configurar webhooks para receber o status de cada transação diretamente no seu sistema.

Neste artigo, você vai encontrar os requisitos técnicos para começar, as diferenças entre cada modelo de integração e o passo a passo para criar ordens de pagamento e manter o ERP atualizado em tempo real.

O que você precisa antes de começar a integração?

Antes de escrever a primeira linha de código, é necessário ter uma conta no Mercado Pago e acesso ao painel do Mercado Pago Developers, onde você gerencia suas aplicações e credenciais de integração.

Como obter suas credenciais de integração do Mercado Pago?

As credenciais de integração do Mercado Pago são o ponto de partida de qualquer conexão via API de pagamentos. No painel de desenvolvedores, acesse "Suas integrações" e crie uma nova aplicação. O sistema gera duas chaves: a Public Key do Mercado Pago, usada no front-end para tokenizar dados de pagamento, e o Access Token, que autoriza as chamadas à API feitas pelo servidor.

Essas chaves existem em dois ambientes distintos. As credenciais de teste, identificadas pelo prefixo "TEST-", permitem simular transações sem movimentar dinheiro real. As credenciais de produção são ativadas após a homologação da integração e liberam o acesso ao ambiente real de pagamentos.

Ambiente de teste: trabalhando com o sandbox

O sandbox do Mercado Pago permite testar toda a jornada de pagamento com dados fictícios antes de ir para produção. Você cria contas de teste separadas para vendedor e comprador, usa cartões de crédito simulados e valida o comportamento dos webhooks sem risco de cobranças indevidas.

O uso do sandbox é obrigatório no processo de homologação. A documentação oficial recomenda cobrir os três cenários principais: pagamento aprovado, pagamento recusado e pagamento pendente. Isso garante que o sistema responda corretamente a cada status antes de operar em produção.

Passo a passo de integração por modelo

O processo varia conforme o tipo de integração escolhido. A seguir, o fluxo de cada modelo a partir do momento em que as credenciais estão configuradas e o sandbox, ativo.

Integrar via QR Code dinâmico

O QR Code dinâmico gera um código único por transação, aceita Pix e carteiras digitais e não exige maquininha. Para configurar:

1. Crie um caixa no painel de desenvolvedores, associando um external_id ao ponto de venda.
2. Faça uma chamada POST para o endpoint de ordens com o external_id, o valor, os itens do pedido e a notification_url.
3. O retorno inclui o código QR em Base64 — exiba no terminal ou gere para impressão.
4. O cliente escaneia o código e conclui o pagamento pelo celular.
5. O Mercado Pago envia uma notificação via webhook com o status da transação (approved, rejected ou pending).

O modelo de QR Code  estático segue o mesmo fluxo, mas sem os passos 2 e 3: o QR fica fixo no caixa e o valor é inserido pelo comprador no momento do pagamento.

Integrar via API Point

A API Point do Mercado Pago  envia a cobrança diretamente para a maquininha, sem que o operador precise digitar o valor. O pré-requisito é ter um terminal Point do Mercado Pago vinculado à conta. Para configurar:

1. No painel de desenvolvedores, localize o device_id do terminal que receberá os pagamentos.
2. Faça uma chamada POST para o endpoint de payment intents informando o device_id e o valor da transação.
3. O terminal recebe a solicitação e exibe o valor ao cliente.
4. O cliente realiza o pagamento com cartão de crédito, débito ou aproximação.
5. O resultado chega ao sistema via webhook com o status final da transação.

Integrar via TEF

A integração via TEF do Mercado Pago é indicada para operações que já usam automação comercial com software de frente de caixa. A integração usa um protocolo padronizado entre o sistema e o terminal, sem chamadas REST diretas. Para configurar:

1. Solicite ao Mercado Pago o módulo TEF compatível com o seu sistema de automação comercial.
2. Instale e configure o módulo seguindo a documentação técnica fornecida.
3. Na finalização de cada venda, o sistema de caixa aciona o módulo TEF com o valor da transação.
4. O terminal exibe a cobrança para o cliente, que realiza o pagamento.
5. O retorno é enviado ao sistema de caixa pelo protocolo TEF, atualizando o status da venda.

Configurando webhooks para notificações em tempo real

O webhook do Mercado Pago é o mecanismo pelo qual o sistema recebe o resultado de cada pagamento em tempo real. Quando um cliente conclui ou cancela uma transação, o Mercado Pago envia uma requisição HTTP POST para a URL configurada na criação da ordem ou no painel de desenvolvedores.

Como funcionam as notificações de pagamento?

O payload do webhook contém o tipo do evento (payment, order), o identificador da transação e o status atual (approved, rejected, pending). Ao receber a notificação, o sistema deve retornar um status HTTP 200. Se não retornar, o Mercado Pago reenvia a notificação em intervalos crescentes.

A URL de notificação precisa ser acessível publicamente e funcionar sobre HTTPS. Durante o desenvolvimento, ferramentas como webhook.site permitem capturar e inspecionar os payloads sem expor o ambiente local.

Boas práticas na configuração de webhooks

Alguns cuidados na implementação evitam problemas comuns de integridade de dados e instabilidade no recebimento das notificações:

• Valide o identificador da notificação consultando a API antes de atualizar o status no ERP. Isso evita que notificações falsas ou duplicadas alterem registros financeiros.
• Processe as notificações de forma assíncrona para não bloquear a resposta HTTP. Retorne o status 200 imediatamente e trate a lógica de negócio em background.
• Implemente idempotência: se a mesma notificação chegar mais de uma vez, o resultado no banco de dados deve ser o mesmo, independentemente de quantas vezes o evento for processado.
• Monitore falhas de reenvio. Se o Mercado Pago não receber o HTTP 200, ele tentará reenviar em intervalos crescentes — tenha um log dessas tentativas para identificar instabilidades na URL de notificação.

Para quem quer ir além dos pagamentos na automação do negócio, vale ver como automatizar pagamentos e organizar contas do negócio.

Como o Mercado Pago se conecta ao ERP da sua operação?

A integração via API de pagamentos vai além do processamento de pagamentos. Cada transação aprovada chega ao ERP com meio de pagamento, número de parcelas, identificadores do cliente e status em tempo real. Com isso, não é preciso importar extratos manualmente nem cruzar planilhas ao final do dia.

A conciliação financeira automática acontece pelo mesmo mecanismo: o ERP recebe o status de cada pagamento via webhook e atualiza o fluxo de caixa. Para negócios com múltiplos caixas ou filiais, a API permite associar diferentes terminais a uma mesma conta e organizar as transações por loja ou operador.

Com essa visibilidade, os dados de pagamento ficam disponíveis no sistema de gestão sem precisar sair dele. Se preferir apoio técnico na implementação, o programa de parcerias do Mercado Pago conecta o seu negócio a empresas certificadas para integrar a API ao seu ambiente.

Sua integração começa agora

Se você chegou até aqui com credenciais criadas, sandbox testado e webhooks mapeados, a integração ERP do Mercado Pago ao seu sistema de PDV está pronta para ir à produção. O próximo passo é submeter a homologação no painel de desenvolvedores. Acesse agora e conclua o processo.

Se você ainda está escolhendo o terminal físico para o seu PDV, as maquininhas Point do Mercado Pago integram diretamente com a API Point e estão disponíveis para contratação pela plataforma, sem intermediários e sem contrato de fidelidade.