Como conectar o Mercado Pago na PagZero

O Mercado Pago recebe o dinheiro das suas vendas: a PagZero cria a cobrança na sua conta do Mercado Pago, e o valor cai direto no seu saldo de lá.

A conexão tem uma particularidade que pega todo mundo de surpresa: o Mercado Pago só libera as credenciais de produção depois de uma compra de teste. Por isso o caminho tem três fases:

1. Criar a aplicação no painel de desenvolvedores do Mercado Pago.
2. Testar: conectar a PagZero com as credenciais de teste e fazer uma compra de mentira.
3. Ir para produção: ativar as credenciais reais, configurar o webhook e trocar as chaves na PagZero.

Você não precisa programar nada. As "etapas de integração" que o Mercado Pago mostra são para quem constrói um checkout do zero; a PagZero já fez essa parte. São 16 passos, e vale ir na ordem.

Passo 1: abrir o painel de desenvolvedores

Entre em mercadopago.com.br/developers/panel/app com a mesma conta do Mercado Pago que vai receber o dinheiro das vendas. Clique em Criar aplicação.

Parece detalhe, mas não é: a aplicação pertence à conta logada. Se você criar numa conta e quiser receber em outra, vai precisar refazer tudo.

Passo 2: criar no painel de integração

Escolha Criar no painel de integração. A opção "Criar com IA" é um assistente para programadores e não acrescenta nada aqui.

Passo 3: escolher Checkout Transparente

Marque Checkout Transparente. É o modelo em que o comprador paga dentro do checkout da PagZero, sem ser levado para o site do Mercado Pago.

• Checkout Pro redireciona o comprador para fora, e cada saída do checkout é uma venda que pode se perder.
• Assinaturas é o produto de recorrência do próprio Mercado Pago. A PagZero cuida das assinaturas por conta própria, então não marque.
• E-commerce, QR Code e Point são para loja virtual pronta, cobrança presencial e maquininha.

Passo 4: tipo de API e nome

Abra Outros dados e preencha:

• Tipo de API: API de Orders. É a API atual do Mercado Pago, e a PagZero funciona com ela.
• Nome da aplicação: um nome que você reconheça, como "PagZero".

Marque a caixa de autorização e clique em Criar aplicação.

Passo 5: a aplicação foi criada

Você cai na tela Dados da integração. O bloco "Etapas de integração" vai mostrar 0%: não se preocupe com ele, porque ele avança sozinho conforme você segue este tutorial.

No menu lateral, em TESTES, clique em Credenciais de teste.

Passo 6: ativar as credenciais de teste

Marque a autorização, resolva o "Não sou um robô" e clique em Ativar credenciais. Leva alguns segundos.

Por que começar pelo teste: o Mercado Pago não entrega as chaves reais antes de ver uma compra funcionando. A de teste movimenta dinheiro de mentira, então você pode errar à vontade.

Passo 7: copiar a Public Key e o Access Token de teste

Copie a Public Key e o Access Token. Os dois começam com APP_USR-, mesmo sendo de teste: isso é normal nas aplicações novas e não indica erro.

Mais abaixo aparecem um usuário, uma senha e um código de verificação. É uma conta de teste que o Mercado Pago criou para você, e ela não é necessária neste tutorial.

Passo 8: conectar na PagZero com as credenciais de teste

Na PagZero, vá em Plugins, ative o Mercado Pago se ainda não estiver ativo, e clique em + Nova conexão. Preencha:

• Nome da conexão: um apelido, como "Mercado Pago teste".
• Access Token: o de teste, do passo 7.
• Public Key: a de teste. Ela é quem protege o número do cartão: o cartão vai do navegador do comprador direto para o Mercado Pago, sem passar pela PagZero. Sem ela, o checkout não aceita cartão.

Client ID, Client Secret e Webhook Secret podem ficar vazios por enquanto.

Salve a conexão. Depois, numa oferta de teste com preço baixo (R$ 5,00 serve), escolha essa conexão do Mercado Pago como gateway do cartão.

Passo 9: pegar um cartão de teste

De volta ao Mercado Pago, abra Cartões de teste no menu lateral. Use o Mastercard ou o Visa da tabela, com o código de segurança e a validade que aparecem na mesma linha.

Use só esses cartões. Cartão real ou inventado dá erro no ambiente de teste.

Passo 10: fazer a compra de teste

Abra o checkout da oferta de teste e pague com cartão. O segredo está no campo Nome impresso no cartão: escreva APRO TESTE.

No ambiente de teste, o Mercado Pago decide aprovar ou recusar pelo nome do titular. APRO significa aprovado. Qualquer outro nome volta como recusado pelo banco, e parece que a integração está quebrada quando não está.

• CPF: use 123.456.789-09.
• Não use PIX nesta etapa: no ambiente de teste o PIX gera o QR Code mas nunca é pago, e a venda fica pendente para sempre.

Se aparecer Pagamento confirmado, a compra de teste está feita. Anote o código da transação: ele fica em Vendas, na venda de teste, e começa com ORD. Você vai usar no passo 13.

Passo 11: configurar as notificações

Em Informações gerais, as etapas avançaram: "Integrar meios de pagamento" ficou concluída, e agora o Mercado Pago pede para configurar as notificações. Notificação é o webhook: o aviso que o Mercado Pago manda para a PagZero quando um PIX ou boleto é pago, quando há estorno ou quando uma assinatura renova.

Sem o webhook, o cartão até funciona (ele aprova na hora), mas PIX e boleto nunca são confirmados: o comprador paga, o dinheiro cai na sua conta e a venda fica Pendente, sem liberar o produto.

Passo 12: criar o webhook

Na PagZero, na conexão do Mercado Pago, copie a URL do webhook. Depois, no Mercado Pago, abra Webhooks no menu lateral.

Configure as duas abas, Modo de teste e Modo de produção, do mesmo jeito:

• URL: cole a URL copiada da PagZero.
• Order (Mercado Pago): o principal. As aplicações novas avisam pagamentos por ele.
• Pagamentos (legacy).
• Planos e assinaturas, em "Outros eventos": é o aviso de cada renovação de assinatura.

Por que as duas abas: compras de teste avisam pela URL do modo de teste, e vendas reais pela do modo de produção. Configurar só uma faz o Mercado Pago considerar o webhook ausente.

Clique em Salvar configurações. Em cada aba o Mercado Pago gera uma Assinatura secreta: ela prova para a PagZero que o aviso veio mesmo do Mercado Pago, e não de alguém tentando forjar um pagamento. Você vai colar na PagZero no passo 16.

Passo 13: medir a qualidade da integração

O Mercado Pago pede o Order ID de uma compra para medir a qualidade da integração. Cole o código que começa com ORD (passo 10) e clique em Medir.

A nota conta o que a PagZero envia em cada cobrança: endereço do comprador, identificador do dispositivo, descrição na fatura do cartão e outros sinais que o antifraude do Mercado Pago usa. A PagZero já envia todos. Por isso vale fazer a compra de teste depois de configurar o webhook: a nota inclui o aviso de webhook entregue.

Passo 14: ativar as credenciais de produção

No menu lateral, em PRODUÇÃO, clique em Credenciais de produção e preencha:

• Setor: o que melhor descreve o seu negócio. Para curso online, a opção mais próxima costuma ser Educação; para mentoria, Serviços de consultoria.
• Site: o seu site ou a página de vendas do seu produto. O Mercado Pago usa esse endereço para entender o que você vende, e um site coerente com o produto pesa a favor na análise de risco da sua conta.

Marque a autorização e clique em Ativar credenciais de produção.

Passo 15: copiar as credenciais de produção

A tela passa a mostrar a Public Key e o Access Token de produção. Copie os dois.

Trate o Access Token de produção como a senha da sua conta. Com ele é possível cobrar e estornar em seu nome. Não mande por e-mail, WhatsApp ou print, e se ele vazar, gere um novo no próprio painel.

Passo 16: trocar para produção na PagZero

Na PagZero, abra a conexão do Mercado Pago e clique em Editar:

1. Troque o Access Token e a Public Key de teste pelos de produção.
2. Em Webhook Secret, cole a assinatura secreta da aba Modo de produção do webhook.
3. Em Ambiente, escolha Produção.

Salve. Esquecer a troca é o erro mais comum desta integração: com as credenciais de teste, o checkout continua funcionando e aprovando, mas nenhum dinheiro de verdade entra na sua conta.

Como testar

Faça uma compra real de valor baixo, com PIX, e pague você mesmo. Em Vendas, ela deve nascer Pendente e virar Aprovada em segundos, sem você tocar em nada. Se virou sozinha, as credenciais e o webhook estão certos. Depois é só estornar a venda.

Perguntas frequentes

Por que o Mercado Pago exige uma compra de teste?

É a forma que ele tem de confirmar que a integração funciona antes de liberar dinheiro de verdade. As credenciais de produção só aparecem depois dessa compra.

A compra de teste foi recusada. O que fiz de errado?

Quase sempre é o nome do titular. No ambiente de teste ele precisa começar com APRO, como "APRO TESTE". Confira também se você usou um cartão da página Cartões de teste, e não um cartão real.

O checkout não aceita só "APRO" no nome do cartão

O checkout da PagZero exige nome e sobrenome, para evitar erro de digitação nas vendas reais. Use APRO TESTE: para o Mercado Pago, basta o nome começar com APRO.

Paguei o PIX de teste e a venda continua pendente

É esperado. No ambiente de teste o Mercado Pago gera o QR Code, mas o PIX nunca é pago. Use cartão para testar, e deixe o PIX para a compra real do final.

As credenciais de teste começam com APP_USR-. Está certo?

Sim. Nas aplicações novas o Mercado Pago usa o mesmo prefixo para teste e produção. O que diferencia é a tela de onde você copiou.

A nota de qualidade não chegou a 100

A nota não bloqueia as vendas. Dois itens costumam ficar pendentes mesmo com tudo certo: o webhook, quando a compra medida foi feita antes de configurá-lo (faça outra compra e meça de novo), e o "SDK do frontend", que o Mercado Pago às vezes não reconhece em compras de teste. A PagZero usa o SDK oficial do Mercado Pago no checkout.

Preciso preencher Client ID e Client Secret?

Não para vender. Só o Access Token e a Public Key são necessários para cobrar, e o Webhook Secret para confirmar PIX e boleto.

Já tenho uma aplicação antiga no Mercado Pago. Preciso criar outra?

Não. A PagZero funciona tanto com aplicações antigas quanto com as novas (API de Orders): ela descobre sozinha qual API a sua aplicação usa. Basta usar as credenciais de produção da aplicação que você já tem e configurar o webhook como no passo 12.