Integrar o Mercado Pago no Magento é feito por meio de um módulo oficial disponível no Adobe Commerce Marketplace e instalável via Composer. O processo envolve três etapas centrais: instalação do pacote no servidor, configuração das credenciais de API no painel administrativo e ativação dos meios de pagamento desejados. Não é necessário editar código manualmente, a maior parte das configurações acontece dentro do próprio admin do Magento.
Ao longo deste artigo, você vai encontrar os requisitos técnicos que precisam estar em ordem antes de começar, o passo a passo de instalação via Composer, como configurar o Checkout Pro e o Checkout Transparente, os erros mais comuns que aparecem após a integração e como resolvê-los, além de um checklist de validação para usar antes de colocar a loja em produção.
Requisitos técnicos antes de integrar Mercado Pago no Magento
Verificar os pré-requisitos antes de iniciar a instalação evita interrupções no meio do processo e poupa tempo de diagnóstico depois. Um ambiente que não atende às versões mínimas pode gerar erros difíceis de rastrear.
Estes são os itens que precisam estar presentes:
- Versão do Magento: o módulo oficial é compatível com Magento 2 (Adobe Commerce). Versões 1.x não têm mais suporte pelo módulo atual
- PHP: verificar a versão compatível com a release do Magento 2 em uso (em geral, PHP 8.1 ou superior para versões recentes)
- Composer: precisa estar instalado no servidor, pois é a ferramenta usada para baixar e gerenciar o pacote
- Acesso SSH: necessário para executar os comandos de instalação e compilação no terminal
- Conta no Mercado Pago: com credenciais de sandbox (para testes) e de produção já disponíveis no painel de desenvolvedores
Com esses itens confirmados, o próximo passo é configurar um ambiente de staging para testar a integração antes de aplicar qualquer mudança na loja em produção. Esse cuidado reduz o risco de interrupção nas vendas durante o processo.
Passo a passo para instalar o módulo do Mercado Pago no Magento
O processo de instalação do módulo segue uma sequência de comandos no terminal do servidor. Cada etapa precisa ser executada na ordem correta para que o Magento reconheça o novo módulo de pagamento.
Instalação via Composer
O Composer é o gerenciador de dependências do PHP e a forma recomendada para instalar o módulo do Mercado Pago. Os passos abaixo devem ser executados com acesso SSH ao servidor onde o Magento está instalado.
- Acesse o diretório raiz da instalação do Magento via terminal
- Execute o comando para baixar o pacote:
composer require mercadopago/adb-payment
Esse comando busca o módulo no repositório oficial e o adiciona ao projeto - Após a conclusão do download, registre o módulo no Magento com:
bin/magento setup:upgrade
Esse comando atualiza o banco de dados e ativa os novos módulos instalados
Se o Composer solicitar autenticação do Adobe Commerce Marketplace, é necessário ter as chaves de acesso configuradas no arquivo auth.json antes de prosseguir.
Compilação e limpeza de cache
Após o setup:upgrade, dois comandos adicionais garantem que o Magento processe e aplique o módulo de forma adequada.
- Execute a compilação de injeção de dependência:
bin/magento setup:di:compile
Esse passo faz com que o Magento registre as classes do módulo e as conecte ao restante do sistema. Sem ele, erros de classe não encontrada podem aparecer no checkout - Limpe o cache para que as mudanças fiquem visíveis:
bin/magento cache:clean
Com o cache limpo, o módulo do Mercado Pago já deve aparecer na seção de métodos de pagamento dentro do painel administrativo do Magento.
Como configurar as credenciais e os checkouts do Mercado Pago
Com o módulo já instalado, a próxima etapa acontece no painel administrativo do Magento, onde as credenciais de API conectam a loja ao Mercado Pago e os tipos de checkout são ativados.
Credenciais de acesso (Access Token e Public Key)
As credenciais de API são o que autoriza a comunicação entre a loja e o Mercado Pago. Elas ficam disponíveis no painel de desenvolvedores em developers.mercadopago.com.br, dentro da seção de aplicações.
Existem dois conjuntos de credenciais:
- Sandbox: usadas durante os testes. As transações não são reais e não movimentam dinheiro
- Produção: usadas quando a loja está no ar para o público. Ativam cobranças reais
Para inserir as credenciais no Magento, o caminho no painel administrativo é: Stores > Configuration > Sales > Payment Methods. Ali, o módulo do Mercado Pago exibe os campos para o Access Token e a Public Key. Manter as credenciais de sandbox ativas em produção é um dos erros mais comuns e faz com que os pagamentos não sejam processados.
Checkout Pro e Checkout Transparente no Magento
O módulo oferece duas modalidades de checkout, e cada uma tem um comportamento diferente durante o processo de compra.
O Checkout Pro redireciona o comprador para o ambiente seguro do Mercado Pago para concluir o pagamento. Esse modelo pode ser adequado para lojas que preferem não lidar com o processamento de dados de cartão diretamente, já que toda a experiência de pagamento acontece fora do site.
O Checkout Transparente mantém o comprador dentro da loja durante todo o processo. Os dados do cartão são capturados por meio da tecnologia SecurityField®, que os envia de forma segura ao Mercado Pago sem que o servidor da loja processe essas informações. Esse modelo oferece mais controle sobre a experiência visual do checkout.
Em ambas as modalidades, os meios de pagamento disponíveis para o público brasileiro incluem: Pix, boleto bancário, cartão de crédito e cartão de débito. A ativação de cada um pode ser configurada de forma individual dentro das opções do módulo.
Erros comuns ao integrar Mercado Pago no Magento e como resolver
Mesmo com a instalação feita de forma correta, alguns problemas aparecem com frequência após a integração. Conhecer os sintomas de cada um agiliza o diagnóstico.
Os erros mais recorrentes são:
- Credenciais trocadas entre sandbox e produção: o sintoma é que os pagamentos não são processados ou aparecem como recusados sem motivo aparente. A ação corretiva é verificar no painel do Magento se as credenciais inseridas correspondem ao ambiente correto (sandbox para testes, produção para o ar)
- Conflito com módulos de terceiros: outros módulos de checkout instalados na loja podem interferir no fluxo de pagamento do Mercado Pago. O sintoma costuma ser um erro no carregamento da página de pagamento ou um loop de redirecionamento. Desativar temporariamente outros módulos de pagamento ajuda a isolar a causa
- Webhooks bloqueados pelo servidor: as notificações IPN (Instant Payment Notification) são enviadas pelo Mercado Pago para informar o status de cada transação. Se o firewall do servidor bloquear as requisições de entrada, os pedidos ficam com status pendente no Magento mesmo após o pagamento confirmado. A correção envolve liberar os IPs do Mercado Pago nas regras do firewall e verificar se a URL de webhook está configurada no painel de desenvolvedores
- Erro de compilação por versão incompatível de PHP: o comando setup:di:compile pode falhar se a versão do PHP instalada no servidor não for compatível com o módulo. O sintoma é uma mensagem de erro no terminal durante a compilação. Atualizar o PHP para a versão recomendada para aquela release do Magento resolve o problema
Consultar os arquivos de log em var/log/ dentro do diretório do Magento é uma prática recomendada para qualquer diagnóstico. Os arquivos system.log e exception.log costumam registrar a origem exata do erro, o que reduz o tempo de investigação.
Checklist de validação antes de ativar os pagamentos em produção
Antes de trocar as credenciais de sandbox pelas de produção, uma série de verificações pode evitar problemas que cheguem até os compradores. Este checklist cobre os pontos mais importantes:
- Testar cada meio de pagamento no sandbox: realizar ao menos uma transação de teste com Pix, boleto e cartão de crédito para confirmar que todos funcionam sem erros
- Confirmar que os webhooks estão recebendo notificações: verificar no painel de desenvolvedores do Mercado Pago se as notificações estão sendo enviadas e se o servidor da loja as está recebendo
- Verificar a mudança de status dos pedidos no Magento: após um pagamento aprovado no sandbox, o pedido deve mudar de status no painel administrativo. Se isso não acontecer, o webhook pode não estar configurado de forma adequada
- Validar reembolso parcial e total: testar o fluxo de devolução dentro do admin do Magento para garantir que os reembolsos são processados sem erros
- Conferir o redirecionamento da página de sucesso: após o pagamento, o comprador deve ser levado para uma página de confirmação. Verificar se esse redirecionamento está funcionando em todos os meios de pagamento testados
- Trocar para as credenciais de produção e realizar um teste real: após ativar as credenciais de produção, fazer uma compra real com valor baixo para confirmar que o fluxo completo funciona no ambiente ao vivo
Manter o módulo atualizado também faz parte da manutenção contínua da integração. Novas versões do módulo costumam trazer correções de segurança e compatibilidade com releases mais recentes do Magento.
Perguntas frequentes sobre a integração do Mercado Pago no Magento
O módulo do Mercado Pago funciona com o Magento 1?
O módulo oficial atual é compatível com Magento 2 (Adobe Commerce). As versões desenvolvidas para o Magento 1 foram descontinuadas, e a recomendação é migrar para o Magento 2 para ter acesso a atualizações e suporte técnico contínuo.
É possível usar o Mercado Pago junto com outros meios de pagamento no Magento?
Sim. O Magento permite ativar múltiplos módulos de pagamento ao mesmo tempo, e o módulo do Mercado Pago coexiste com outros métodos. O ponto de atenção é testar o checkout após ativar todos os módulos, já que conflitos entre eles podem afetar a experiência de compra.
Como saber se os webhooks estão funcionando após a integração?
O painel de desenvolvedores do Mercado Pago exibe o histórico de notificações enviadas, incluindo o status de cada requisição. Além disso, os logs do Magento em var/log/ registram se as notificações estão sendo recebidas e processadas pelo sistema, o que facilita a identificação de falhas.
Com a integração configurada e validada, a loja estará pronta para receber pagamentos com os métodos mais usados pelo público brasileiro. O app do Mercado Pago concentra a gestão de cobranças, estornos e acompanhamento de transações em um só lugar. Para quem precisa de configurações avançadas, como personalização do webhook, múltiplas lojas ou integrações com outros sistemas, a documentação oficial de desenvolvedores em developers.mercadopago.com.br oferece referências técnicas detalhadas e suporte para cada cenário.
Aplicam-se restrições. Consulte mais informações sobre produtos, serviços e termos de uso em: https://www.mercadopago.com.br/ajuda/termos-e-condicoes_299
