Como conectar a Pagar.me na PagZero

Clique a clique: ativar o plugin, criar a Secret Key, pegar a Public Key, configurar o webhook com autenticação e criar a conexão na PagZero.

A Pagar.me é o gateway que recebe o dinheiro das suas vendas. A PagZero não guarda o seu saldo: ela cria a cobrança na sua conta da Pagar.me, e o valor cai direto lá.

A integração tem três peças, e todas importam:

A Secret Key, que permite a PagZero criar cobranças e estornos na sua conta.
A Public Key, que protege o cartão do comprador: o número vai do navegador direto para a Pagar.me, sem passar pela PagZero. Sem ela, o checkout não aceita cartão.
O webhook, que permite a Pagar.me avisar a PagZero quando alguém paga.

Sem o webhook, o cartão até 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 para sempre, sem liberar o produto.

São 15 passos. Você começa na PagZero, passa a maior parte do tempo no painel da Pagar.me e volta à PagZero no final.

Passo 1: ativar o plugin da Pagar.me

Tela Plugins da PagZero com o card da Pagar.me destacado e o botão Ativar — Seção Pagamentos da tela de Plugins.

Na PagZero, clique em Plugins no menu lateral. Na seção Pagamentos, encontre o card da Pagar.me e clique em + Ativar.

Janela de ativação da Pagar.me com o botão Ativar Pagar.me destacado — A janela explica o que muda ao ativar.

Confirme em Ativar Pagar.me. Ativar só liga o plugin na sua conta: ainda não conecta nada. A Pagar.me passa a ter um atalho no menu lateral, e você pode criar quantas conexões quiser, cada uma com as credenciais de uma conta.

Passo 2: abrir as Chaves na Pagar.me

Menu lateral do painel da Pagar.me com Configurações aberto e o item Chaves destacado — Configurações, logo abaixo de Conta.

Entre em dash.pagar.me com a conta que vai receber o dinheiro das vendas. No menu lateral, abra CONFIGURAÇÕES e clique em Chaves.

Se você tem mais de uma empresa na Pagar.me, confira o nome no topo do menu antes de seguir. A chave pertence à empresa selecionada, e criar na empresa errada faz o dinheiro cair no lugar errado.

Passo 3: anotar a Public Key

Bloco Dados da API com o campo Chave pública destacado, ao lado do botão de copiar — Ela começa com pk_. O ícone verde copia.

Em Dados da API, o campo Chave pública traz a sua Public Key, que começa com pk_. Copie pelo ícone verde e guarde: ela vai na PagZero no passo 14.

A própria Pagar.me escreve embaixo que essa chave "não permite criar transações reais". É verdade, e é justamente por isso que ela pode ficar no navegador do comprador: ela só transforma o cartão num código descartável, e quem cobra é a Secret Key.

Passo 4: criar a Secret Key

Bloco Chaves da API com o botão Criar chave destacado — Conta nova começa com a lista vazia.

No bloco Chaves da API, clique em Criar chave.

Passo 5: dar nome à chave

Janela Criar chave com o campo Nome da chave preenchido com PagZero — O nome é só para você reconhecer a chave na lista.

Em Nome da chave, escreva PagZero. Uma chave por plataforma permite revogar uma sem derrubar as outras, e o nome é o que te diz qual é qual.

Caixa Utilizo os módulos legados do Magento 2 ou Woocommerce destacada e desmarcada — Essa opção é para lojas antigas, não para a PagZero.

Deixe desmarcada a caixa "Utilizo os módulos legados do Magento 2 ou Woocommerce (Mundipagg)". Ela gera um tipo de chave antigo, que a PagZero não usa.

Passo 6: escolher acesso Total

Opção Total selecionada em Acesso da chave — Personalizado exige escolher permissão por área.

Em Acesso da chave, marque Total. A PagZero usa mais de uma área da API: cria pedidos e assinaturas, faz estornos e consulta o recebível para registrar a taxa de cada venda. Com Personalizado, faltar uma dessas áreas derruba a função correspondente sem aviso claro.

Botão Avançar destacado no rodapé da janela Criar chave — A permissão vem na próxima tela.

Clique em Avançar.

Passo 7: permissão de leitura e escrita

Opção Leitura e escrita selecionada em Selecione uma permissão — Somente leitura não deixa criar cobranças.

Marque Leitura e escrita. Com "Somente leitura" a conexão até salva, mas toda tentativa de cobrança é recusada, e o comprador vê erro no checkout.

Campo Senha destacado no fim da janela Criar chave — É a senha que você usa para entrar no painel.

Em Senha, digite a senha do seu login na Pagar.me e clique em Criar chave. A Pagar.me pede a senha porque essa chave tem poder de movimentar a conta.

Passo 8: copiar a Secret Key

Janela Copiar chave com a chave mascarada e o botão Copiar chave secreta destacado — Esta é a única vez que a chave aparece inteira.

A janela mostra a Secret Key, que começa com sk_. Clique em Copiar chave secreta e guarde num lugar seguro antes de fechar. Como o aviso diz, você não poderá consultá-la de novo: se perder, o caminho é criar outra.

Trate a Secret Key como a senha da sua conta. Com ela é possível cobrar e estornar em seu nome. Não mande por e-mail, WhatsApp ou print.

Lista Chaves da API com a chave PagZero criada, acesso Total e o botão Excluir — Na lista, a chave aparece mascarada.

Clique em Concluir. A chave aparece na lista com o nome PagZero e acesso Total. O botão Excluir ao lado é como você revoga a chave se ela vazar.

Passo 9: abrir os Webhooks

Menu lateral da Pagar.me com Configurações aberto e o item Webhooks destacado no fim da lista — É o Webhooks dentro de Configurações, no fim da lista.

Ainda em CONFIGURAÇÕES, clique em Webhooks, o último item da lista.

Cuidado com o item WEBHOOKS que aparece mais acima, em letras maiúsculas: ele só mostra o histórico de avisos enviados, e não tem como criar webhook ali.

Tela Configurações Webhooks vazia com o botão Criar webhook destacado — Conta nova começa sem nenhum webhook.

Clique em + Criar webhook.

Passo 10: colar a URL da PagZero

Em URL, cole:

https://api-webhooks.pagzero.com/webhooks/pagarme

É a mesma URL que a PagZero mostra na tela da conexão, com botão de copiar (passo 14). Se o navegador preencher o campo sozinho com um e-mail, apague antes de colar: a Pagar.me mostra "URL inválida" e não deixa salvar.

Campo Máximo de tentativas destacado, vazio, com o texto Até 3 tentativas — Vazio, a Pagar.me usa 3 tentativas.

Máximo de tentativas pode ficar vazio. É quantas vezes a Pagar.me reenvia um aviso que não foi entregue, e o padrão de 3 basta.

Passo 11: ligar a autenticação

Chave Habilitar autenticação ligada, mostrando Ativo — Ao ligar, aparecem os campos de usuário e senha.

Ligue Habilitar autenticação. É o que prova para a PagZero que o aviso veio mesmo da Pagar.me, e não de alguém tentando forjar um "pagamento aprovado" para liberar o produto sem pagar.

Campos Usuário do Webhook preenchido com pagzero e Senha do Webhook destacados — Você inventa os dois. Anote antes de salvar.

Preencha:

Usuário do Webhook: um nome qualquer, como pagzero.
Senha do Webhook: uma senha forte, criada só para isso. Não use a senha do seu login.

Anote os dois. Eles vão nos campos "Usuário do webhook" e "Senha do webhook" da PagZero, e precisam ser idênticos dos dois lados: se não forem, a PagZero recusa os avisos e as vendas de PIX e boleto ficam pendentes.

Passo 12: marcar os 10 eventos

Os eventos ficam agrupados por assunto. Abra cada grupo clicando no nome dele (o + vira −) e marque só estes:

COBRANÇA:

charge.paid: o pagamento caiu. É o aviso que aprova PIX e boleto.
charge.payment_failed: o pagamento falhou.
charge.refunded: a cobrança foi estornada.
charge.partial_canceled: parte do valor foi estornada.
charge.chargedback: o comprador contestou a compra no cartão.

Grupo Pedido aberto com os eventos order.canceled, order.paid e order.payment_failed marcados — Pedido: 3 eventos.

PEDIDO: order.paid, order.payment_failed e order.canceled.

O order.canceled é o que mais faz falta quando esquecido: um estorno feito pelo painel da Pagar.me sai como pedido cancelado, e não como cobrança estornada. Sem esse evento, a venda continua Aprovada na PagZero e o comprador mantém o acesso ao produto.

Grupo Fatura aberto com os eventos invoice.paid e invoice.payment_failed marcados — Fatura: 2 eventos.

FATURA: invoice.paid e invoice.payment_failed. São os avisos de renovação de assinatura: cada ciclo pago ou recusado chega por aqui. Se você não vende assinatura, marcar não atrapalha, e já deixa pronto para quando vender.

Não use Marcar todos. A Pagar.me passa a disparar dezenas de avisos que a PagZero descarta, e os que importam disputam a fila com eles.

Passo 13: confirmar e salvar o webhook

Campo Senha de Confirmar criação e o botão salvar destacados no fim do formulário — De novo a senha do seu login, não a do webhook.

No fim da página, em Confirmar criação, digite a senha do seu login na Pagar.me e clique em salvar. Se o navegador preencher esse campo sozinho, confira: às vezes ele coloca uma senha salva de outro site.

Webhook criado na lista, com a URL da PagZero, status active e os 10 eventos — Status active e os 10 eventos listados.

O webhook aparece na lista com status active e os 10 eventos. Confira se a URL e os eventos estão certos: o lápis à direita abre a edição.

Passo 14: criar a conexão na PagZero

Tela da Pagar.me na PagZero sem conexões, com o botão Nova conexão e o atalho Pagar.me no menu destacados — Depois de ativado, a Pagar.me ganha atalho no menu.

De volta à PagZero, clique em Pagar.me no menu lateral e depois em + Nova conexão.

Campo Nome da conexão preenchido com Pagar.me principal — Um apelido para você reconhecer a conexão.

Nome da conexão: um apelido, como "Pagar.me principal". Com mais de uma conta na Pagar.me, é ele que diferencia as conexões na hora de escolher o gateway da oferta.

Campo Secret Key destacado, obrigatório — O único campo obrigatório.

Secret Key: a chave sk_ do passo 8.

Campo Public Key destacado — Opcional no formulário, necessária para vender no cartão.

Public Key: a chave pk_ do passo 3. O formulário salva sem ela, mas o checkout não consegue processar cartão e mostra ao comprador que a configuração está incompleta.

Usuário do webhook e Senha do webhook: exatamente os que você criou no passo 11.

Campo Ambiente destacado com Produção selecionado, ao lado de Status Ativo — Produção é o padrão.

Ambiente: Produção, para vendas reais. Só use Sandbox se as chaves vierem do ambiente de testes da Pagar.me (elas começam com sk_test_ e pk_test_). Status fica Ativo.

Passo 15: conferir o webhook e salvar

Seção Webhook obrigatório com a URL do webhook e o botão Copiar destacados — A mesma URL do passo 10.

A seção Webhook (obrigatório) mostra a URL que vai na Pagar.me, com o botão Copiar. Se você pulou o passo 10, é daqui que se copia.

Lista Eventos que devem estar marcados com os 10 eventos da Pagar.me — Confira com a lista do webhook na Pagar.me.

Logo abaixo ficam os 10 eventos que precisam estar marcados. Compare com o webhook que você salvou no passo 13.

Caixa Já criei o webhook no painel da Pagar.me com a URL e os eventos acima destacada — Sem marcar, o botão Salvar fica bloqueado.

Marque Já criei o webhook no painel da Pagar.me com a URL e os eventos acima. A PagZero pede essa confirmação porque, sem o webhook, a conexão parece funcionar e só falha no primeiro PIX.

Caixa de confirmação marcada e o botão Salvar destacado — Pronto para salvar.

Clique em Salvar. A conexão aparece na lista da Pagar.me, pronta para ser escolhida como gateway nas suas ofertas.

Como testar

Não confie na configuração até ver uma venda mudar de status sozinha:

Crie uma oferta barata, de R$ 5,00, com PIX, usando a conexão da Pagar.me.
Abra o checkout e pague o PIX você mesmo.
Acompanhe a venda em Vendas.

Ela deve nascer Pendente e virar Aprovada em segundos, sem você tocar em nada. Se virou sozinha, a chave e o webhook estão certos. Depois é só estornar a venda.

Perguntas frequentes

A venda fica Pendente mesmo depois de eu pagar o PIX

É o sintoma clássico de webhook com problema. Confira, nesta ordem: a URL na Pagar.me é igual à da PagZero; o usuário e a senha do webhook são idênticos dos dois lados; a autenticação está ligada; e os 10 eventos estão marcados. O menu WEBHOOKS da Pagar.me (o de cima) mostra cada aviso enviado e se a PagZero aceitou.

O checkout diz que a configuração de pagamento está incompleta

Falta a Public Key na conexão. Edite a conexão na PagZero e cole a chave pk_ de Configurações → Chaves.

Perdi a Secret Key. Como recupero?

Não recupera. A Pagar.me mostra a chave uma única vez. Crie uma nova, troque na conexão da PagZero e exclua a antiga na lista de chaves.

Estornei pelo painel da Pagar.me e a venda continua Aprovada

Falta o evento order.canceled no webhook. Estorno feito pelo painel chega como pedido cancelado. Edite o webhook pelo lápis, marque o evento e salve. Para as vendas já estornadas, o caminho mais seguro é estornar pela própria PagZero, que atualiza a venda na hora.

Posso usar a mesma Secret Key em outra plataforma?

Funciona, mas não faça. Uma chave por plataforma permite excluir uma sem derrubar as outras, e mostra no painel quem usa o quê.

Já tenho um webhook de outra plataforma na Pagar.me. Preciso criar outro?

Sim. Crie um webhook separado para a PagZero, com a URL e o usuário e senha dela. A Pagar.me aceita vários, e cada um recebe os seus avisos.

Por que acesso Total, e não Personalizado?

Porque a PagZero usa mais de uma área da API (cobranças, assinaturas, estornos e o recebível de cada venda, de onde sai a taxa). Uma área esquecida no Personalizado quebra a função correspondente sem um erro claro.

Este artigo resolveu sua dúvida?

Falar com o suporte