Webhooks - PIX-IN - Novus Pagamentos

🔄 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#