Como conectar o Asaas na PagZero

O Asaas é o gateway que recebe o dinheiro das suas vendas. A PagZero não guarda seu saldo: ela cria a cobrança no Asaas, e o Asaas deposita na sua conta.

A integração tem duas metades, e as duas são obrigatórias:

1. A chave de API, que permite a PagZero criar cobranças no Asaas.
2. O webhook, que permite o Asaas avisar a PagZero quando alguém paga.

Sem a chave, nenhuma cobrança é gerada. Sem o webhook, a cobrança é gerada mas o pagamento nunca é confirmado: o PIX cai na sua conta e a venda fica Pendente para sempre, sem liberar o produto.

São 14 passos. Vá na ordem: você vai alternar entre a PagZero e o Asaas duas vezes.

Passo 1: abrir os Plugins na PagZero

Na PagZero, clique em Plugins no menu lateral. É a tela onde ficam todas as integrações: gateways, pixels, e-mail marketing e nota fiscal.

Passo 2: ativar o plugin

Role até a seção Pagamentos e encontre o card do Asaas. Enquanto ele não estiver ativado, o card traz um botão + Ativar. Clique nele.

Ativar apenas liga o plugin na sua conta: ainda não conecta nada. Depois de ativado, o Asaas passa a aparecer na seção Ativados, no topo da página, e também ganha um atalho no menu lateral.

Passo 3: abrir o perfil no Asaas

Agora vá para o painel do Asaas, em outra aba. Clique no ícone do seu perfil, no canto superior direito.

Esse é o passo que mais confunde: por instinto a gente procura na barra lateral esquerda, mas lá só existem as funções do dia a dia (cobranças, clientes, Pix). As integrações moram no menu do perfil.

Passo 4: entrar em Integrações

No menu que abriu, clique em Integrações.

Passo 5: abrir a aba Chaves de API

A página de Integrações tem seis abas. Comece pela Chaves de API. Você vai voltar aqui no passo 9 para a aba Webhooks.

Passo 6: gerar a chave

Clique em Gerar chave de API. Repare que a lista mostra só nomes e situação: o valor da chave não fica visível depois de criada, nem para você.

Passo 7: nomear a chave

Em Nome da chave, escreva PagZero. Assim você sabe de quem é a chave se um dia precisar revogar.

Deixe Data e Hora de expiração vazias. Uma chave que expira derruba suas vendas sem aviso.

Passo 8: não permitir saque

Deixe desmarcado o checkbox "Permitir que esta chave execute operações de saque via API". A PagZero só precisa criar cobranças, nunca movimentar seu dinheiro.

Marcar essa opção daria à chave um poder que ela não usa, e isso é o que transforma um vazamento em prejuízo.

Clique em Avançar. O Asaas mostra a chave.

Copie a chave agora e cole em algum lugar seguro. A própria tela avisa: este é o único momento em que você a verá.

Passo 9: voltar às Integrações, aba Webhooks

Ainda no Asaas, clique na aba Webhooks.

Passo 10: adicionar o webhook

Clique em + Adicionar Webhook. Se você já usa o Asaas com outra plataforma, não mexa no webhook existente: crie um separado para a PagZero.

Passo 11: preencher nome, URL e e-mail

Antes de preencher a URL, você precisa buscá-la na PagZero. Volte para a aba da PagZero, abra Plugins → Asaas → Nova conexão e role até Webhook (obrigatório):

Clique em Copiar e volte ao Asaas.

• Este Webhook ficará ativo?: deixe ligado.
• Nome do Webhook: PagZero.
• URL do Webhook: cole a URL que você copiou.
• E-mail: o seu. O Asaas avisa por aqui se a sincronização falhar, e esse aviso é o que evita você descobrir o problema pelo cliente reclamando.

Passo 12: versão da API

Escolha v3. É a versão que a PagZero usa; com a v2 o formato do aviso muda e a confirmação não funciona.

O token de autenticação

Clique em Gerar Token e copie o valor. Ele é o que prova que o aviso veio mesmo do Asaas, e não de alguém tentando forjar um pagamento.

Guarde esse token: você vai colá-lo na PagZero no passo 14.

Passo 13: tipo de envio e eventos

Tipo de envio: escolha Não sequencial. A PagZero trata cada aviso de forma independente e ignora repetidos, então não precisa de fila ordenada. No modo sequencial, um único aviso travado segura todos os seguintes.

Fila de sincronização: deixe ligada.

Role até Adicionar Eventos e abra o grupo Cobranças. Ignore os demais grupos: notas fiscais, transferências e afins não têm relação com suas vendas.

Marque estes sete:

• PAYMENT_CREATED: cobrança gerada.
• PAYMENT_CONFIRMED: pagamento efetuado, saldo ainda não liberado.
• PAYMENT_RECEIVED: valor recebido.
• PAYMENT_OVERDUE: PIX ou boleto venceu sem pagamento.
• PAYMENT_REFUNDED: cobrança estornada.
• PAYMENT_CHARGEBACK_REQUESTED: o comprador contestou.
• PAYMENT_DELETED: cobrança removida.

Resista à tentação de clicar em Selecionar Todos. Como a própria tela avisa, quanto menos eventos, mais eficiente o envio: marcar tudo faz o Asaas disparar avisos que a PagZero descarta, e isso só atrasa os que importam.

Clique em Salvar. O webhook aparece na lista com a situação Ativado.

Passo 14: criar a conexão na PagZero

De volta à PagZero, em Plugins → Asaas, clique em + Nova conexão. Você pode ter mais de uma: é assim que se separa a conta de teste da que recebe de verdade.

Preencha:

• Nome da conexão: um apelido seu, como "Conta principal".
• API Key: a chave do passo 8.
• Wallet ID: só é necessário para split de pagamentos. Pode deixar vazio.
• Webhook Token: o token do passo 12. Se os dois não forem idênticos, a PagZero recusa os avisos.

Ambiente: produção ou sandbox

O campo Ambiente precisa combinar com a chave que você colou. Chave da conta real vai em Produção; chave gerada no ambiente Sandbox do Asaas vai em Sandbox.

Trocar isso é o erro que gera a cobrança "no lugar errado": em sandbox nenhum dinheiro é movimentado de verdade.

Clique em Salvar. Pronto: a chave permite criar cobranças, e o webhook permite confirmá-las.

Como testar

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

1. Crie uma oferta barata, de R$ 5,00, com PIX.
2. Abra o checkout e pague o PIX você mesmo.
3. Acompanhe a venda em Vendas.

Ela deve nascer Pendente e virar Aprovada em segundos, sem você tocar em nada. Se virou sozinha, o webhook está funcionando.

Perguntas frequentes

Não acho Integrações no menu do Asaas

Não procure na barra lateral esquerda. É no ícone do seu perfil, canto superior direito, quase no fim do menu, logo acima de Sair.

A venda fica Pendente mesmo depois de eu pagar

É o sintoma clássico de webhook mal configurado. Confira, nesta ordem: a URL colada no Asaas está igual à da PagZero; o Webhook Token é idêntico dos dois lados; a versão é v3; e os sete eventos estão marcados.

Perdi minha chave de API. Como recupero?

Não recupera. O Asaas mostra a chave uma única vez. Gere uma nova, cole na PagZero e revogue a antiga.

Posso usar a mesma chave em duas plataformas?

Tecnicamente sim, mas não faça. Uma chave por plataforma permite revogar uma sem derrubar as outras, e deixa claro nos logs do Asaas quem fez o quê.

Preciso preencher o Wallet ID?

Só para split de pagamentos. Para receber normalmente, deixe vazio.

Já tinha um webhook configurado. Preciso criar outro?

Se o webhook existente aponta para outra plataforma, sim: crie um separado para a PagZero. O Asaas aceita vários, cada um com sua URL e seu token.

O que são "eventos penalizados" na lista do Asaas?

São avisos que o Asaas tentou entregar e não conseguiu. Um número diferente de zero indica que a sua URL esteve fora do ar ou recusou os avisos, o que costuma apontar token errado.

Marquei o checkbox de saque na chave. Tem problema?

A PagZero não usa essa permissão, mas uma chave com poder de saque é um risco maior caso vaze. Se puder, gere uma nova chave sem essa opção e revogue a anterior.