Webhooks - PIX-OUT - Novus Pagamentos

🔄 Webhooks de Saque (Withdrawal / PIX-OUT)

Receba atualizações em tempo real sobre o status dos saques 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 saque for atualizado em nosso sistema.
Em vez de consultar constantemente a API em busca de atualizações, os webhooks enviam os dados do saque diretamente para sua aplicação assim que o evento acontece.

🚀 Configurando Webhooks

O webhook é enviado através do campo postback_url (ou notify_url) fornecido na rota de Criação de Saque (Withdrawal Request).

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 saque é 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 saque.

⏳ Saque Pendente

{
  "id": 5722,
  "status": "pending",
  "amount": 500,
  "type": "withdrawal",
  "external_id": "MEU-ID-EXTERNO-PAYOUT-789",
  "end_to_end_id": null,
  "rejection_reason": null,
  "created_at": "2025-11-10T23:38:00-03:00",
  "payer": null,
  "payee": null
}

⏳ Saque em Processamento

{
  "id": 5722,
  "status": "processing",
  "amount": 500,
  "type": "withdrawal",
  "external_id": "MEU-ID-EXTERNO-PAYOUT-789",
  "end_to_end_id": null,
  "created_at": "2025-11-10T23:38:00-03:00",
  "rejection_reason": null,
  "payer": null,
  "payee": null
}

⏳ Saque em Processamento (com dados completos 01)

O evento de processamento pode já incluir os dados completos da transação:

{
  "id": 8327,
  "status": "processing",
  "amount": 500,
  "type": "withdrawal",
  "external_id": "8327_394453",
  "end_to_end_id": null,
  "created_at": "2025-11-14T17:24:24-03:00"
  "rejection_reason": null,
  "payer": {
    "bank": {
      "account": "12345678",
      "agency": "1234",
      "digit": "9",
      "name": "Banco do Brasil",
      "type": "Conta Corrente"
    },
    "document": "12.345.678/0001-95",
    "name": "Empresa do Henrique"
  },
  "payee": null,
}

⏳ Saque em Processamento (com dados completos 02)

O evento de processamento pode já incluir os dados completos da transação:

{
  "id": 5723,
  "status": "processing",
  "amount": 500,
  "type": "withdrawal",
  "external_id": "MEU-ID-EXTERNO-PAYOUT-789",
  "end_to_end_id": "E071368472025110714410CSR1MUA0ZT",
  "created_at": "2025-11-10T23:38:00-03:00",
  "rejection_reason": null,
  "payer": {
    "bank": {
      "account": "12345678",
      "agency": "1234",
      "digit": "9",
      "name": "Banco do Brasil",
      "type": "Conta Corrente"
    },
    "document": "12.345.678/0001-95",
    "name": "Empresa do Henrique"
  },
  "payee": {
    "bank_code": "10573521",
    "document": ".434.275-*",
    "name": "Pedro de Alcântara Francisco Antônio"
  }
}

✅ Saque Concluído com Sucesso

{
  "id": 5723,
  "status": "completed",
  "amount": 500,
  "type": "withdrawal",
  "external_id": "MEU-ID-EXTERNO-PAYOUT-789",
  "end_to_end_id": "E071368472025110714410CSR1MUA0ZT",
  "created_at": "2025-11-10T23:38:00-03:00",
  "rejection_reason": null,
  "payer": {
    "bank": {
      "account": "12345678",
      "agency": "1234",
      "digit": "9",
      "name": "Banco do Brasil",
      "type": "Conta Corrente"
    },
    "document": "12.345.678/0001-95",
    "name": "Empresa do Henrique"
  },
  "payee": {
    "bank_code": "10573521",
    "document": ".434.275-*",
    "name": "Pedro de Alcântara Francisco Antônio"
  }
}

❌ Saque Rejeitado

{
  "id": 8179,
  "status": "rejected",
  "amount": 500,
  "type": "withdrawal",
  "external_id": "MEU-ID-EXTERNO-PAYOUT-789",
  "end_to_end_id": null,
  "created_at": "2025-11-10T23:38:00-03:00",
  "rejection_reason": "Motivo da Rejeição",
  "payer": {
    "bank": {
      "account": "12345678",
      "agency": "1234",
      "digit": "9",
      "name": "Banco do Brasil",
      "type": "Conta Corrente"
    },
    "document": "12.345.678/0001-95",
    "name": "Empresa do Henrique"
  },
  "payee": null
}

❌ Saque Falhou

{
  "id": 8179,
  "status": "failed",
  "amount": 500,
  "type": "withdrawal",
  "external_id": "MEU-ID-EXTERNO-PAYOUT-789",
  "end_to_end_id": null,
  "created_at": "2025-11-10T23:38:00-03:00",
  "rejection_reason": "Motivo da Rejeição",
  "payer": {
    "bank": {
      "account": "12345678",
      "agency": "1234",
      "digit": "9",
      "name": "Banco do Brasil",
      "type": "Conta Corrente"
    },
    "document": "12.345.678/0001-95",
    "name": "Empresa do Henrique"
  },
  "payee": null
}

📋 Descrição dos Campos

Campo	Tipo	Descrição
`id`	integer	Identificador único do saque (gerado pela API).
`status`	string	Status atual da transação (ex: `"processing"`, `"completed"`, `"failed"`, `"rejected"`).
`amount`	integer	Valor total da transação em centavos (ex: 500 = R$ 5,00).
`type`	string	Tipo da operação (sempre `"withdrawal"` para saques).
`external_id`	string	Identificador único da transação no seu sistema (enviado na requisição).
`end_to_end_id`	string	Identificador End-to-End da transação PIX (disponível após processamento).
`rejection_reason`	string	Motivo da falha ou rejeição (disponível apenas em caso de erro).
`payer`	object	Objeto contendo os dados do pagador (origem do saque).
`payer.bank`	object	Dados bancários do pagador.
`payer.bank.account`	string	Número da conta bancária do pagador.
`payer.bank.agency`	string	Número da agência bancária do pagador.
`payer.bank.digit`	string	Dígito verificador da conta do pagador.
`payer.bank.name`	string	Nome do banco do pagador.
`payer.bank.type`	string	Tipo da conta bancária (ex: `"Conta Corrente"` ou `"Conta Poupança"`).
`payer.document`	string	Documento (CNPJ/CPF) do pagador.
`payer.name`	string	Nome do pagador.
`payee`	object	Objeto contendo os dados do recebedor (destino do saque).
`payee.bank_code`	string	Código do banco do recebedor.
`payee.document`	string	Documento (CNPJ/CPF) do recebedor (pode estar mascarado).
`payee.name`	string	Nome 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 Saque

Os webhooks são disparados a cada mudança de status do saque.
Os principais status que você receberá são:

processing
O saque foi solicitado e está em processamento pela instituição financeira.

completed
O saque foi pago com sucesso e o valor foi transferido.

failed
Ocorreu uma falha técnica ou bancária durante a transferência
(ex: chave Pix incorreta, conta bloqueada, saldo insuficiente).

💡 Informações Importantes

Os campos payer e payee podem estar null nos eventos iniciais de processing.

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

O rejection_reason fornece detalhes técnicos sobre a falha e está disponível apenas quando o status é failed.

Alguns dados do payee podem estar mascarados por questões de segurança (ex: documento parcialmente oculto).

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

Webhooks - PIX-OUT

🔄 Webhooks de Saque (Withdrawal / PIX-OUT)#

🧭 Visão Geral#

🚀 Configurando Webhooks#

📦 Estrutura do Payload#

⏳ Saque Pendente#

⏳ Saque em Processamento#

⏳ Saque em Processamento (com dados completos 01)#

⏳ Saque em Processamento (com dados completos 02)#

✅ Saque Concluído com Sucesso#

❌ Saque Rejeitado#

❌ Saque Falhou#

📋 Descrição dos Campos#

🔁 Respondendo a Webhooks#

🧪 Testando Webhooks (Em Desenvolvimento)#

🔐 Recomendações de Segurança#

📡 Eventos e Status de Saque#

💡 Informações Importantes#