Para integrar o Mercado Pago no VTEX, o processo acontece em dois ambientes: o portal de desenvolvedores do Mercado Pago, onde são geradas as credenciais de autenticação, e o Admin VTEX, onde o conector MercadoPagoV2 é configurado e os meios de pagamento são ativados. A configuração padrão não exige código personalizado, tudo é feito pelo painel administrativo.
Ao longo deste artigo, você vai encontrar os pré-requisitos da integração, o passo a passo para obter as credenciais corretas, como registrar e configurar o conector na VTEX, como ativar meios de pagamento e o Device Fingerprint, além de um checklist de validação para usar antes de ir para produção.
O que você precisa antes de integrar Mercado Pago no VTEX
Antes de acessar qualquer painel, vale confirmar que todos os itens abaixo estão disponíveis. A ausência de qualquer um deles pode travar a configuração no meio do caminho.
Os pré-requisitos são:
- Conta de vendedor no Mercado Pago: é a conta que vai receber os pagamentos. Deve ser uma conta de pessoa jurídica ou de vendedor habilitado, não uma conta pessoal comum.
- Certificado SSL ativo na loja VTEX: o SSL garante a criptografia dos dados durante o checkout. Sem ele, as transações não são processadas.
- Acesso ao Admin VTEX com permissões de pagamento: quem for configurar precisa ter nível de acesso suficiente para editar provedores e condições de pagamento.
- Acesso ao portal de desenvolvedores do Mercado Pago: é nele que as credenciais são geradas. O acesso é feito com o login da conta de vendedor em developers.mercadopago.com.
Com esses itens confirmados, a configuração pode avançar sem interrupções.
Como obter as credenciais do Mercado Pago para a integração
As credenciais são as chaves que conectam sua loja VTEX ao Mercado Pago. Sem elas, o conector não consegue processar transações.
Para acessá-las, entre no portal de desenvolvedores do Mercado Pago com a conta de vendedor. No menu lateral, acesse Suas integrações e crie uma nova aplicação (ou selecione uma existente). Dentro da aplicação, as credenciais ficam na aba Credenciais de produção e Credenciais de teste, guarde as duas por enquanto, pois serão usadas em momentos diferentes.
Public Key e Access Token: qual a função de cada uma
A Public Key identifica a loja no front-end da aplicação. Ela é usada para carregar o formulário de pagamento no checkout e não deve ser confundida com uma chave secreta, pode aparecer no código do lado do cliente sem risco.
O Access Token opera no back-end e autoriza as transações junto à API do Mercado Pago. Ele tem caráter confidencial e é justamente o campo que vai no Admin VTEX como "Token de aplicação".
Um erro frequente é inverter as duas chaves no momento do preenchimento no Admin VTEX. Quando isso acontece, as transações são rejeitadas sem uma mensagem de erro clara, o que dificulta o diagnóstico. Ao preencher o conector, leia com atenção o rótulo de cada campo antes de colar a credencial.
Outro ponto importante: as credenciais de teste e as de produção são diferentes. Durante a fase de validação, use as de teste. Ao ativar a loja para o público, substitua por credenciais de produção, esse passo é obrigatório e costuma ser esquecido.
Configuração do conector MercadoPagoV2 no Admin VTEX
Com as credenciais em mãos, o próximo passo acontece no painel administrativo da VTEX, onde o conector MercadoPagoV2 é registrado como provedor de pagamentos.
O caminho no Admin VTEX é: Configurações da loja > Pagamentos > Provedores > Novo provedor. Na busca, digite "MercadoPago" e selecione o conector MercadoPagoV2. A partir daí, os campos precisam ser preenchidos na seguinte ordem:
- Chave de aplicação: insira a Public Key de produção (ou de teste, na fase de validação).
- Token de aplicação: insira o Access Token correspondente.
- Nome da loja: o nome que vai aparecer na fatura do cliente.
- Parcelamento máximo: defina o número máximo de parcelas aceitas.
- Modo binário: ative ou desative conforme a necessidade (mais detalhes abaixo).
- Suporte a 3DS 2.0: habilite se quiser reforço de autenticação em transações de risco.
- Prazo de vencimento do boleto: defina o número de dias para pagamento.
Campos que merecem atenção na configuração do conector
O modo binário define como o sistema reage a pagamentos com status pendente. Com ele ativo, pagamentos que não são aprovados de imediato são recusados de forma automática, o que reduz a ambiguidade, mas também pode rejeitar transações que seriam aprovadas após análise. Para lojas com alto volume de vendas parceladas, desativar o modo binário costuma aumentar a taxa de aprovação.
O suporte a 3DS 2.0 adiciona uma camada de autenticação em transações consideradas de risco pelo emissor do cartão. Quando ativo, o comprador pode ser redirecionado para validar a compra com o banco. Isso reduz chargebacks e tende a melhorar as taxas de aprovação em categorias com histórico de fraude mais elevado.
O prazo de vencimento do boleto merece atenção em lojas com produtos de alta demanda ou estoque limitado. Um prazo muito longo pode reservar o estoque por dias sem confirmação de pagamento.
Como ativar meios de pagamento e o Device Fingerprint no VTEX
Depois de registrar o conector, é preciso ativar as condições de pagamento que vão aparecer no checkout da loja e configurar o Device Fingerprint para reforçar a segurança das transações.
Meios de pagamento disponíveis na integração
O conector MercadoPagoV2 permite habilitar os seguintes meios de pagamento:
- Cartão de crédito: com suporte a parcelamento conforme configurado no conector.
- Cartão de débito: processado de forma direta, sem redirecionamento.
- Pix: pagamento instantâneo com geração de QR code no checkout.
- Boleto bancário: com prazo de vencimento definido na configuração do conector.
- Linha de Crédito do Mercado Pago: opção de parcelamento para quem tem limite disponível no app do Mercado Pago.
Cada meio precisa ser ativado de forma individual. O caminho é: Configurações da loja > Pagamentos > Configurações > Condições de pagamento > Adicionar condição de pagamento. Selecione o meio desejado, vincule ao conector MercadoPagoV2 e salve.
Device Fingerprint: por que configurar
O Device Fingerprint é um identificador do dispositivo usado pelo comprador no momento da compra. Ele coleta informações como navegador, resolução de tela e comportamento de navegação para ajudar o sistema antifraude do Mercado Pago a avaliar o risco da transação.
Sem o Device Fingerprint configurado, a taxa de rejeição de pagamentos tende a ser mais alta, sobretudo em compras com cartão de crédito. A configuração na VTEX envolve adicionar um script na página de checkout. O código está disponível na documentação do Mercado Pago para desenvolvedores e precisa ser inserido no template do checkout da loja.
Para confirmar que está ativo, abra o checkout da loja, clique com o botão direito e inspecione o código da página. Procure pela referência ao domínio mercadolibre.com/org-img/, a presença desse script indica que o fingerprint está carregando.
Checklist de testes antes de ativar o Mercado Pago em produção
Pular a etapa de testes é um dos erros mais frequentes em integrações de pagamento. Um problema não detectado em ambiente de teste só aparece quando um cliente real tenta pagar, e aí o impacto vai além do técnico.
Antes de desativar o modo de teste e ir para produção, valide cada item abaixo:
- Compra com cartão de teste: o Mercado Pago disponibiliza números de cartão de teste na documentação de desenvolvedores. Simule uma compra aprovada e uma recusada para verificar o comportamento do checkout.
- Geração de QR code para Pix: finalize um pedido de teste escolhendo Pix e confirme que o QR code aparece corretamente na tela de confirmação.
- Prazo do boleto: gere um boleto de teste e verifique se o vencimento exibido corresponde ao configurado no conector.
- Parcelamento no checkout: adicione um produto ao carrinho e confirme que as opções de parcelamento aparecem conforme o máximo definido.
- Device Fingerprint ativo: inspecione o código da página de checkout e confirme a presença do script do fingerprint.
- Credenciais de produção: antes de ir ao ar, acesse o conector no Admin VTEX e confirme que os campos estão preenchidos com as credenciais de produção, não as de teste.
Com todos os itens validados, acesse o conector MercadoPagoV2 no Admin VTEX, localize a opção de modo de teste e desative. A partir desse momento, as transações são processadas em ambiente real.
Perguntas frequentes sobre a integração do Mercado Pago no VTEX
Quanto tempo leva para o Mercado Pago aparecer como opção de pagamento no checkout?
Após a configuração completa e a ativação das condições de pagamento, o meio de pagamento pode levar até 10 minutos para aparecer no checkout da loja VTEX. Se o tempo se estender além disso, vale verificar se a condição foi salva corretamente e se o conector está ativo.
É possível usar Checkout Pro e Checkout Transparente ao mesmo tempo no VTEX?
Sim, as duas modalidades podem coexistir na mesma loja. O Checkout Pro redireciona o comprador para o ambiente do Mercado Pago para concluir o pagamento, enquanto o Checkout Transparente mantém toda a experiência dentro da loja. A escolha depende da experiência que se quer oferecer para quem compra.
O que fazer se os pagamentos estão sendo rejeitados após a integração?
O primeiro passo é verificar se as credenciais inseridas no conector são de produção, não de teste. Em seguida, confirme que o Device Fingerprint está configurado e ativo na página de checkout. Também vale checar se o modo binário está adequado ao tipo de operação da loja. Os logs de transação no Admin VTEX ajudam a identificar o motivo exato da rejeição.
A integração do Mercado Pago no VTEX tem custo adicional?
A configuração do conector MercadoPagoV2 não gera custo extra na plataforma VTEX. As taxas que se aplicam são as do Mercado Pago sobre cada transação processada, conforme o plano comercial vigente na conta de vendedor.
Com a integração funcionando, a loja passa a oferecer Pix, boleto, cartão de crédito, débito e parcelamento no checkout, o que amplia as opções para quem compra e pode impactar de forma direta a taxa de conversão. Para quem quiser explorar configurações avançadas, testar webhooks ou acessar o ambiente de sandbox, o portal de desenvolvedores do Mercado Pago em mercadopago.com.br/developers reúne toda a documentação técnica com exemplos práticos.
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
