O SDK do Mercado Pago reúne bibliotecas oficiais para integrar pagamentos em projetos web e mobile sem a complexidade da API REST. Está disponível para PHP, Node.js, Java, Python, Ruby, .NET, Go, iOS e Android. A integração segue um fluxo simples: criar uma aplicação, obter as credenciais, instalar o SDK, configurar o ambiente e realizar os testes iniciais.
Neste artigo, você verá todo o processo, da escolha do checkout ao primeiro pagamento no sandbox, além das principais dificuldades enfrentadas por iniciantes. A proposta é apresentar um fluxo completo e contínuo, complementando as lacunas da documentação oficial e dos tutoriais em vídeo.
Antes de instalar o SDK do Mercado Pago: qual checkout escolher
Antes de rodar qualquer comando de instalação, há uma decisão arquitetural que vai determinar quais partes do SDK você vai usar: o tipo de checkout. O Mercado Pago oferece duas abordagens principais, e confundi-las no início pode gerar retrabalho.
O Checkout Pro redireciona o comprador para um ambiente hospedado pelo Mercado Pago para concluir o pagamento. Quem escolhe essa rota precisa de menos configuração no frontend, e toda a responsabilidade pela conformidade PCI fica com o Mercado Pago. É uma boa opção para quem quer colocar a integração no ar com agilidade e sem precisar construir um formulário de cartão do zero.
O Checkout API (também chamado de Checkout Transparente) mantém o comprador dentro do seu site ou app durante todo o processo. Isso exige mais trabalho de frontend — incluindo o uso do SDK client-side para capturar dados do cartão com segurança — e implica um nível maior de responsabilidade sobre a conformidade PCI.
Em contrapartida, oferece controle total sobre a experiência de pagamento. Nos dois casos, o SDK server-side é necessário para criar preferências, processar transações e consultar status.
Como criar a aplicação e obter credenciais no painel de desenvolvedores
O acesso ao SDK do Mercado Pago depende de credenciais vinculadas a uma aplicação registrada no painel Suas Integrações. Veja como configurar tudo antes de escrever a primeira linha de código.
O processo de criação da aplicação segue estes passos:
- Acesse o painel Suas Integrações no site do Mercado Pago Developers.
- Clique em Criar aplicação.
- Preencha o nome da aplicação e selecione o produto que você vai integrar (pagamentos online, por exemplo).
- Confirme a criação e acesse o painel da aplicação para localizar as credenciais.
Após criar a aplicação, você terá acesso a dois pares de credenciais: um para teste e outro para produção. Cada par inclui uma Public Key e um Access Token. A Public Key é usada no frontend para inicializar o SDK client-side e tokenizar dados de cartão. O Access Token fica no backend e nunca deve ser exposto ao navegador.
Credenciais de teste vs credenciais de produção
Um dos erros mais comuns entre quem está começando é usar o Access Token de produção durante o desenvolvimento. O sintoma é imediato: qualquer transação gerada no ambiente de teste pode movimentar dinheiro real.
As credenciais de teste têm o prefixo TEST- e são as únicas que devem aparecer no código durante a fase de desenvolvimento. As credenciais de produção só entram em cena quando a integração está validada e pronta para receber pagamentos reais.
Instalação do SDK do Mercado Pago por linguagem de programação
O SDK server-side do Mercado Pago está disponível para sete linguagens. A instalação usa o gerenciador de dependências de cada ecossistema.
PHP, Node.js e Python
Essas três linguagens concentram a maior parte das integrações web e têm o processo de instalação mais documentado pela comunidade.
- PHP (requer versão 7.4 ou superior): composer require mercadopago/dx-php
- Node.js (compatível com Node 18+): npm install mercadopago
- Python (via pip): pip install mercadopago
Após a instalação, vale verificar se o gerenciador de dependências está atualizado — versões antigas do Composer ou do pip podem instalar uma versão desatualizada do SDK, o que causa incompatibilidades com a API atual do Mercado Pago.
Java, Ruby, .NET e Go
Essas linguagens seguem o mesmo princípio, cada uma com seu próprio gerenciador.
- Java (via Maven): adicionar a dependência com.mercadopago:sdk-java no pom.xml
- Ruby: gem install mercadopago-sdk
- .NET (via NuGet): nuget install mercadopago-sdk
- Go: go get -u github.com/mercadopago/sdk-go
Para projetos Java, é importante verificar a versão do SDK no repositório oficial antes de adicionar a dependência, já que o Maven pode não buscar a versão mais recente sem uma declaração explícita. Após instalar em qualquer linguagem, o próximo passo é inicializar o SDK com o Access Token de teste.
Configuração inicial e primeiro teste de pagamento no sandbox
Com o SDK instalado, o próximo passo é configurar as credenciais de teste e executar uma transação no ambiente sandbox do Mercado Pago.
Como inicializar o SDK com o Access Token de teste
A inicialização segue um padrão consistente em todas as linguagens: importar o módulo principal do SDK, chamar o método de configuração (que varia por linguagem, mas costuma se chamar MercadoPago.SDK.setAccessToken ou equivalente) e passar o Access Token de teste como argumento. Esse passo deve acontecer uma única vez, preferencialmente no arquivo de configuração central do projeto, antes de qualquer chamada à API.
Um detalhe que a documentação oficial não destaca com clareza: o SDK usa o token informado na inicialização para todas as requisições subsequentes. Se o projeto tiver múltiplos ambientes (desenvolvimento, homologação, produção), o ideal é carregar o token a partir de variáveis de ambiente — nunca hardcoded no código-fonte. Isso evita que credenciais de produção vazem acidentalmente em repositórios públicos.
Criando uma preferência de pagamento para testar
Uma preferência de pagamento é o objeto central da integração com o Mercado Pago. Ela reúne as informações do produto ou serviço que será cobrado — título, quantidade, preço unitário — além de configurações como URLs de retorno após o pagamento e dados do comprador.
Para criar uma preferência básica no sandbox, o fluxo é:
- Instanciar o objeto de preferência com os dados do item.
- Definir as back_urls (URLs de retorno para sucesso, falha e pendente).
- Chamar o método de criação da preferência via SDK.
- Usar o init_point retornado para redirecionar o comprador (no caso do Checkout Pro) ou o id da preferência para inicializar o Checkout API.
Após executar o teste, observe o status da transação retornado pela API: approved indica sucesso, rejected indica recusa simulada. O Mercado Pago fornece cartões de teste com números específicos para simular cada cenário. Além do status, vale configurar um endpoint para receber notificações webhook — elas são a forma mais confiável de acompanhar mudanças de status em transações assíncronas, como boleto e Pix.
Erros comuns ao começar com o SDK do Mercado Pago e como resolver
A maioria dos problemas que travam quem está começando não está na lógica do código — está em configurações que parecem óbvias depois que você as descobre. Os cinco erros abaixo aparecem com frequência em fóruns e comunidades de desenvolvimento.
- Credenciais trocadas (produção no lugar de teste): o sintoma é uma transação que aparece como real no painel. A solução é verificar se o Access Token começa com TEST- antes de qualquer chamada.
- SDK desatualizado: erros como method not found ou respostas inesperadas da API costumam indicar que a versão instalada do SDK não é compatível com os endpoints atuais. Manter o SDK na versão mais recente resolve na maioria dos casos.
- URLs de retorno não configuradas: sem as back_urls, o Mercado Pago não sabe para onde redirecionar o comprador após o pagamento. O resultado é uma tela de erro após a transação. Sempre defina as URLs de sucesso, falha e pendente na preferência.
- Falta de tratamento de erros da API: tokens expirados, limites de requisição e dados inválidos retornam códigos de erro específicos. Ignorar esses retornos faz com que falhas silenciosas sejam difíceis de diagnosticar. Tratar a resposta da API em todos os cenários é parte da integração, não um detalhe opcional.
- Confusão entre SDK server-side e client-side: o SDK server-side (instalado via Composer, npm, pip etc.) roda no backend e nunca deve tocar o navegador. O SDK client-side (MercadoPago.js) roda no frontend e é responsável por tokenizar dados de cartão. Misturar os dois — ou tentar usar o Access Token no frontend — compromete a segurança da integração.
Identificar em qual dessas categorias está o problema costuma ser o caminho mais curto para resolver um travamento na integração.
Perguntas frequentes sobre o SDK do Mercado Pago
O SDK do Mercado Pago é gratuito?
O SDK é gratuito e open source, disponível no GitHub. As taxas do Mercado Pago incidem sobre as transações processadas — não sobre o uso do SDK em si.
Quais linguagens de programação o SDK do Mercado Pago suporta?
No server-side: PHP, Node.js, Java, Python, Ruby, .NET e Go. Para aplicativos mobile, há SDKs nativos para iOS (Swift) e Android.
Preciso de certificação PCI para usar o SDK?
Com o Checkout Pro, a certificação PCI fica por conta do Mercado Pago. Com o Checkout API, o nível de conformidade exigido depende de como os dados do cartão são capturados — o uso dos campos seguros do SDK client-side reduz a complexidade e o escopo de auditoria.
Como testar pagamentos sem usar dinheiro real?
Basta usar as credenciais de teste (Access Token com prefixo TEST-) e o ambiente sandbox. O Mercado Pago disponibiliza cartões de teste com números específicos para simular aprovações, recusas e outros cenários de pagamento.
O próximo passo concreto é acessar o painel Mercado Pago Developers — em especial a seção Suas Integrações — para criar a primeira aplicação, obter as credenciais de teste e colocar em prática o fluxo descrito aqui.
A documentação oficial complementa este guia com referências detalhadas de cada método do SDK, e o repositório no GitHub traz exemplos por linguagem que podem acelerar os primeiros testes.
–
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_29