Ferramenta · Dados do Brasil

Validador de webhook do Pix

Recebeu o aviso de um Pix no seu sistema e o fluxo não entendeu o corpo? Cole o JSON abaixo: a ferramenta confere cada campo contra o esquema oficial da API Pix do Banco Central e aponta onde está o problema.

Corpo do webhook (JSON)

Cole o JSON recebido no seu endereço de notificação

Pronto.

Tudo é lido no seu navegador. O JSON não é enviado a nenhum servidor, e a ferramenta não chama o seu banco nem o Banco Central.

Resultado

Como o webhook do Pix funciona

Quem recebe Pix por uma API de banco (ou de um provedor de pagamento) cadastra um endereço de notificação para uma chave, com uma chamada PUT /webhook/{chave}. Depois disso, o banco envia uma requisição POST para {seu endereço}/pix sempre que um Pix chega nessa chave. O corpo é um objeto com uma lista chamada pix.

Quando o aviso é enviado: quando um ou mais Pix associados a um txid são recebidos e quando uma devolução desse Pix chega a um status final (DEVOLVIDO ou NAO_REALIZADO).
Agrupamento: o banco pode juntar vários Pix da mesma chave em um único aviso, por isso pix é uma lista.
Resposta esperada: o seu endereço responde 200 para confirmar o recebimento.
Prazo: a especificação deixa o prazo (SLA) do aviso por conta de cada banco.
Autenticação: a especificação descreve esse serviço como protegido por mTLS (certificado nos dois lados), detalhado no Manual de Padrões para Iniciação do Pix.

O que a ferramenta confere

Campo	Regra do esquema oficial
`pix`	Lista de objetos dentro de um objeto na raiz: `{"pix": [ ... ]}`. Não é uma lista solta.
`endToEndId`	Obrigatório. Exatamente 32 caracteres alfanuméricos.
`txid`	Opcional. De 26 a 35 caracteres alfanuméricos. Sem ele, o Pix não está ligado a uma cobrança.
`valor`	Obrigatório. Texto com ponto e duas casas, até 10 dígitos antes do ponto: `"110.00"`. Número, vírgula e separador de milhar não valem.
`horario`	Obrigatório. Data e hora no padrão RFC 3339, como `2020-09-09T20:15:00.358Z`.
`infoPagador`	Opcional. Texto livre de até 140 caracteres.
`componentesValor`	Opcional. Detalha o valor (`original`, `saque`, `troco`, `juros`, `multa`, `abatimento`, `desconto`). O valor do Pix deve ser igual a original + saque + troco + multa + juros - abatimento - desconto, e não pode haver saque e troco juntos.
`devolucoes`	Opcional. Lista de devoluções, cada uma com `id` (1 a 35 alfanuméricos), `rtrId` (32 alfanuméricos), `valor`, `horario` (objeto com `solicitacao` e/ou `liquidacao`) e `status` (`EM_PROCESSAMENTO`, `DEVOLVIDO` ou `NAO_REALIZADO`).

Campos que não existem no esquema (por exemplo, um endToEnd sem o "Id") aparecem como aviso, não como erro, porque um banco pode acrescentar campos próprios.

Erros que mais derrubam o fluxo

Valor como número: "valor": 110.5 em vez de "110.50". Em fluxos e sistemas que convertem para número, a conta também se perde quando há dois zeros à direita.
Esquecer o envelope: tratar o corpo como se fosse o Pix direto, em vez de ler pix[0].
Assumir um único Pix: ler só o primeiro item e ignorar os demais do mesmo aviso.
Horário local: comparar o horario sem levar em conta que ele pode vir em UTC (Z). A tabela do resultado mostra o horário de Brasília.
Devoluções: tratar devolucoes como um objeto único em vez de uma lista.

Um detalhe na própria especificação

No exemplo pixWebhook1 da especificação oficial, o campo devolucoes aparece como um objeto, mas o esquema define uma lista de objetos. Esta ferramenta segue o esquema, então aponta o exemplo original como erro. Se o seu banco enviar um objeto no lugar de uma lista, vale perguntar a ele, e o seu fluxo pode aceitar as duas formas por segurança.

Boas práticas (não são regra da especificação)

Trate o aviso como repetível: use o endToEndId como chave única para não lançar o mesmo Pix duas vezes. A ferramenta avisa quando o mesmo identificador aparece duas vezes no mesmo corpo.
Responda rápido e processe depois: confirme com 200 e faça o trabalho pesado em outra etapa.
Confirme o Pix na consulta do banco antes de liberar mercadoria de alto valor, em vez de confiar só no aviso.

O que a ferramenta não faz

Não verifica se o aviso veio mesmo do banco: isso depende do mTLS e das regras do seu provedor.
Não consulta o Banco Central nem o seu banco, e não confirma que o Pix foi liquidado.
Não valida o bloco tributo (recente na especificação) em detalhes.
Valida contra a versão 2.11.0-rc1 da especificação (versão candidata). Bancos podem seguir uma versão anterior; por isso o resultado mostra erros como "em relação ao esquema oficial".

Perguntas frequentes

O corpo do webhook é uma lista ou um objeto?

Um objeto com a chave pix, e o valor dessa chave é a lista de Pix. Uma lista solta, sem o envelope, é rejeitada pela ferramenta.

Por que o valor é texto e não número?

Porque o esquema define valor como texto com ponto decimal e duas casas. Isso evita perda de precisão e diferença entre 110.5 e 110.50.

O endToEndId começa sempre com E?

O esquema da API só exige 32 caracteres alfanuméricos. A estrutura interna do identificador é descrita em outro documento do Banco Central, e esta ferramenta não a decodifica.

Meu banco manda campos extras. Isso é erro?

Não é erro de esquema; a ferramenta mostra um aviso. Confira com o banco se o campo é uma extensão documentada.

O JSON que colei vai para algum servidor?

Não. A leitura acontece no seu navegador.

Fontes oficiais

Os exemplos desta página partem dos exemplos da especificação oficial. A ferramenta é independente e não é afiliada ao Banco Central.