Webhooks - PIX-IN - NovusBank

🔄 Webhooks de Recebimento PIX (PIX-IN)

Receba atualizações em tempo real sobre o status dos recebimentos PIX por meio de notificações de webhook.

🧭 Visão Geral

Os webhooks permitem que sua aplicação receba notificações automáticas sempre que o status de um recebimento PIX for atualizado em nosso sistema. Em vez de consultar constantemente a API em busca de atualizações, os webhooks enviam os dados do pagamento diretamente para sua aplicação assim que o evento acontece.

🚀 Configurando Webhooks

O webhook é enviado através do campo postback_url fornecido na rota de Criação de Invoice/Cobrança.

Você deve configurar um endpoint (URL) em seu servidor que esteja publicamente acessível para receber as requisições POST.

📬 Estrutura do Payload

Quando o status de um recebimento PIX é alterado, nosso sistema envia uma requisição POST para a URL configurada, contendo um payload em formato JSON.

Os payloads variam de acordo com o status do pagamento:

⏳ Pagamento Pendente

{
  "amount": 1000,
  "end_to_end_id": null,
  "external_id": null,
  "id": "156d9af1-6d30-4b18-8d6c-286b9c7535d6",
  "method": "pix",
  "payee": {
    "bank": {
      "account": "12345678",
      "agency": "1234",
      "digit": "9",
      "name": "Banco do Brasil",
      "type": "Conta Corrente"
    },
    "document": "12.345.678/0001-95",
    "name": "Empresa do Henrique",
    "pix_key": "hrbeiro10@gmail.com"
  },
  "payer": null,
  "status": "pending",
  "total": 1000
}

✅ Pagamento Confirmado/Pago

{
  "id": "156d9af1-6d30-4b18-8d6c-286b9c7535d6",
  "status": "paid",
  "amount": 1000,
  "total": 1000,
  "method": "pix",
  "end_to_end_id": "E31872495202511071424mEbiri30MfF",
  "payer": {
    "cpf": "57546964000157",
    "document": "57546964000157",
    "end_to_end_id": "E31872495202511071424mEbiri30MfF",
    "is_real_payer": true,
    "name": "CARTHERO BRASIL INSTITUICAO DE PAGAMENTO LTDA"
  },
  "payee": {
    "bank": {
      "account": "12345678",
      "agency": "1234",
      "digit": "9",
      "name": "Banco do Brasil",
      "type": "Conta Corrente"
    },
    "document": "12.345.678/0001-95",
    "name": "Empresa do Henrique",
    "pix_key": "hrbeiro10@gmail.com"
  }
}

📋 Descrição dos Campos

Campo	Tipo	Descrição
`id`	string	Identificador único do pagamento (gerado pela API).
`status`	string	Status atual da transação (ex: `"pending"`, `"paid"`).
`amount`	integer	Valor total da transação em centavos (ex: 1000 = R$ 10,00).
`total`	integer	Valor total final da transação (pode coincidir com `amount`).
`method`	string	Método de pagamento utilizado (ex: `"pix"`).
`end_to_end_id`	string	Identificador End-to-End da transação PIX (disponível após pagamento).
`external_id`	string	Identificador único da transação no seu sistema (enviado na requisição).
`payer`	object	Objeto contendo os dados do pagador (disponível após pagamento).
`payer.cpf`	string	CPF do pagador.
`payer.document`	string	Documento (CNPJ/CPF) do pagador.
`payer.end_to_end_id`	string	End-to-End ID da transação.
`payer.is_real_payer`	boolean	Indica se é o pagador real da transação.
`payer.name`	string	Nome do pagador.
`payee`	object	Objeto contendo os dados do recebedor (favorecido).
`payee.bank`	object	Dados bancários do recebedor.
`payee.bank.account`	string	Número da conta bancária do recebedor.
`payee.bank.agency`	string	Número da agência bancária do recebedor.
`payee.bank.digit`	string	Dígito verificador da conta do recebedor.
`payee.bank.name`	string	Nome do banco do recebedor.
`payee.bank.type`	string	Tipo da conta bancária (ex: "Conta Corrente" ou "Conta Poupança").
`payee.document`	string	Documento (CNPJ/CPF) do recebedor.
`payee.name`	string	Nome do recebedor.
`payee.pix_key`	string	Chave PIX do recebedor.

🔁 Respondendo a Webhooks

Seu endpoint de webhook deve retornar um código HTTP 2xx (ex: 200, 202, 204) para confirmar o recebimento da notificação.

Se nosso sistema não receber uma resposta 2xx, ele tentará reenviar o webhook até 10 vezes, com intervalos crescentes entre as tentativas (exponential backoff).

🧪 Testando Webhooks (Em Desenvolvimento)

Você pode testar sua implementação de webhooks usando o simulador de webhooks disponível no painel do desenvolvedor. Ele permite enviar payloads de teste para o seu endpoint sem precisar acionar eventos reais.

⚠️ Recomendações de Segurança

Verifique a autenticidade do webhook utilizando a assinatura (ex: X-Signature) enviada nos cabeçalhos da requisição.

Implemente tratamento de erros adequado para as requisições recebidas.

Use sempre HTTPS no endpoint do webhook.

Configure monitoramento para acompanhar as entregas e falhas dos webhooks.

📅 Eventos e Status de Recebimento PIX

Os webhooks são disparados em cada mudança de status do pagamento PIX. Abaixo estão todos os status possíveis, incluindo os adicionais:

pending: O QR Code PIX foi gerado e está aguardando o pagamento do cliente.

paid: O pagamento foi recebido e confirmado com sucesso. O valor foi creditado na conta.

expired: O pagamento não foi realizado dentro do prazo de validade configurado para a cobrança. O QR Code ou link de pagamento perdeu a validade e não pode mais ser utilizado.

failed: Ocorreu uma falha no processamento do pagamento. Isso pode acontecer por instabilidade bancária, erro no fluxo de pagamento ou problemas temporários na instituição financeira.

cancelled: A cobrança foi cancelada manualmente antes de ser paga. Nenhum pagamento poderá ser feito utilizando essa cobrança.

refunded: O pagamento foi realizado, mas o valor foi devolvido ao pagador. Esse status indica que o recebedor solicitou ou processou um estorno.

chargeback: Indica que houve uma contestação relacionada ao pagamento. O banco do pagador abriu um processo de chargeback para analisar a transação, podendo resultar na devolução do valor.

💡 Informações Importantes

O campo payer (dados do pagador) só estará disponível após a confirmação do pagamento (status paid).

O end_to_end_id é o identificador único da transação PIX fornecido pelo Banco Central e só estará disponível após o pagamento.

O campo is_real_payer indica se o pagador identificado pelo sistema PIX corresponde ao titular da conta que efetuou o pagamento.

Precisa de ajuda? Entre em contato com nossa equipe de suporte para desenvolvedores para obter assistência.

Webhooks - PIX-IN

🔄 Webhooks de Recebimento PIX (PIX-IN)#

🧭 Visão Geral#

🚀 Configurando Webhooks#

📬 Estrutura do Payload#

⏳ Pagamento Pendente#

✅ Pagamento Confirmado/Pago#

📋 Descrição dos Campos#

🔁 Respondendo a Webhooks#

🧪 Testando Webhooks (Em Desenvolvimento)#

⚠️ Recomendações de Segurança#

📅 Eventos e Status de Recebimento PIX#

💡 Informações Importantes#