Webhook de Pix assinado: receba o aviso na hora e confira que ele é nosso
Consultar o status de cada cobrança a todo instante gasta processamento dos dois lados. O webhook inverte: avisamos você no momento em que o pagamento é confirmado.
Os avisos que você recebe
Pix recebido
O pagamento de uma cobrança foi confirmado.
Pix enviado
Um Pix de saída foi concluído.
Pix que falhou
Um Pix de saída não foi concluído e o valor voltou ao saldo.
Validando e tratando o aviso
Cada aviso vem com uma assinatura calculada sobre a data do envio e o corpo da mensagem. O seu servidor recalcula a assinatura com o segredo do webhook e só aceita se bater. Isso impede que alguém simule um pagamento.
Se o mesmo aviso chegar duas vezes, trate com idempotência: guarde o identificador do evento e ignore repetições. Responda rápido com sucesso para não receber a tentativa de novo.
Como cadastrar a URL
No painel, em Credenciais de API, você cadastra a URL de destino e escolhe o formato dos avisos. Para quem já integra com outro provedor, há também o formato da API v2. Veja o passo a passo da integração.
Como começar
Abra sua conta
Cadastre-se pelo site, envie os dados e os documentos pedidos e acompanhe a análise do cadastro.
Cobre pelo painel ou integre pela API
Gere cobranças Pix pelo painel ou conecte seu sistema pela API, começando pela chave de teste (sandbox), que não mexe em dinheiro de verdade.
Receba e acompanhe
Receba o aviso de pagamento por webhook, libere o pedido e confira tudo no extrato e nos relatórios.
Perguntas frequentes
Preciso mesmo usar webhook?
É a forma recomendada. Consultar a cada instante consome limite de requisições e é mais lento que o aviso.
O que fazer se o meu servidor estiver fora do ar?
Responda ao aviso só quando ele for processado e use a consulta pelo identificador da cobrança para conferir os pagamentos do período em que o servidor ficou fora. Confirme na documentação a política de novas tentativas de entrega.
Como valido a assinatura?
Calcule o HMAC da mensagem com o segredo do webhook, no formato descrito na documentação, e compare com o cabeçalho de assinatura.
Posso testar sem dinheiro real?
Sim, no sandbox.
Webhook de Pix assinado: receba o aviso na hora e confira que ele é nosso
Consultar o status de cada cobrança a todo instante gasta processamento dos dois lados. O webhook inverte: avisamos você no momento em que o…
Veja também
- API Pix de entrada (Pix in)API de recebimento por Pix: cobrança dinâmica com txid, QR Code, consulta, listagem e webhook de pagamento. Documentação pública e chave de teste.
- API Pix de saída (Pix out)API para enviar Pix por chave ou QR Code copia e cola, com chave de idempotência, aviso de sucesso e de falha e devolução automática ao saldo.
- Como integrar a API PixGuia prático para integrar uma API Pix: autenticação, criar cobrança, receber webhook, validar assinatura, tratar duplicidade e testar no sandbox.
- Idempotência em pagamentosIdempotência impede cobrança e pagamento duplicados quando a requisição é repetida. Entenda o conceito e como aplicar em cobranças e Pix de saída.