Webhook de Saque

Webhooks são notificações automáticas que a API envia quando um evento do saque acontece. Assim, você não precisa ficar consultando a API: basta receber e processar o evento quando ele chegar.

Se você trabalha com transações, veja Webhook de Transação.

Eventos suportados

Evento	Quando é enviado
WITHDRAWAL_CREATED	Quando o saque é criado
WITHDRAWAL_APPROVED	Quando o saque é aprovado
WITHDRAWAL_PROCESSED	Quando o saque é processado
WITHDRAWAL_APPROVED_AND_PROCESSED	Quando o saque é aprovado e processado
WITHDRAWAL_CANCELED	Quando o saque é cancelado
WITHDRAWAL_REFUNDED	Quando o saque é estornado
WITHDRAWAL_REJECTED	Quando o saque é rejeitado
WITHDRAWAL_FAILED	Quando o saque falha

Formato do payload

Campo	Tipo	Obrigatório	Descrição
type	string (enum) - WITHDRAWAL_CREATED, WITHDRAWAL_APPROVED, WITHDRAWAL_PROCESSED, WITHDRAWAL_APPROVED_AND_PROCESSED, WITHDRAWAL_CANCELED, WITHDRAWAL_REFUNDED, WITHDRAWAL_REJECTED, WITHDRAWAL_FAILED	Sim	Tipo do evento enviado no webhook
data	object	Sim	Dados do saque

Payload base

Esses campos estão presentes em todos os webhooks de saque.

Campo	Tipo	Obrigatório	Descrição
id	string (UUID)	Sim	Identificador único do saque
externalCode	string	Sim	Seu código de referência
amount	number	Sim	Valor do saque, em centavos
method	string (enum) - PIX	Sim	Método do saque
status	string (enum) - PENDING, PROCESSING, PROCESSED, FAILED, CANCELED, REFUNDED, REJECTED, PENDING_COMPLIANCE	Sim	PENDING: saque criado, aguardando processamento PROCESSING: saque em processamento PROCESSED: saque processado com sucesso FAILED: erro no processamento CANCELED: saque cancelado REFUNDED: saque estornado REJECTED: saque rejeitado pela gateway PENDING_COMPLIANCE: saque pendente de análise de compliance
createdAt	string (ISO)	Sim	Data de criação
endToEnd	string	Sim	Identificador end-to-end do saque

Variações por evento

WITHDRAWAL_CREATED, WITHDRAWAL_APPROVED e WITHDRAWAL_REJECTED

Usam apenas o payload base.

WITHDRAWAL_PROCESSED e WITHDRAWAL_APPROVED_AND_PROCESSED

Além do payload base, adicionam:

Campo	Tipo	Obrigatório	Descrição
pixKey	object	Sim	Chave PIX (ver Sub-Objeto PixKeyVo)
trackingKey	string	Não	Clave de rastreo do SPEI. Vem sempre null em saques PIX
receiver	object	Não	Dados do recebedor (ver Sub-Objeto AccountHolder)
payer	object	Não	Dados do pagador (ver Sub-Objeto AccountHolder)
amountWithdrawn	number	Não	Valor efetivamente sacado
processedDate	string (ISO)	Não	Data de processamento
paymentReceipt	string	Não	URL do comprovante

WITHDRAWAL_CANCELED e WITHDRAWAL_FAILED

Além do payload base, adicionam:

Campo	Tipo	Obrigatório	Descrição
reason	string	Não	Motivo do cancelamento ou da falha, quando informado

WITHDRAWAL_REFUNDED

Além do payload base, adiciona:

Campo	Tipo	Obrigatório	Descrição
refundAmount	number	Sim	Valor do estorno
refundDate	string (ISO)	Não	Data do estorno
endToEndRefund	string	Não	Identificador end-to-end do estorno
refundReceipt	string	Não	URL do comprovante de estorno

Sub-Objetos

AccountHolder

Campo	Tipo	Obrigatório	Descrição
type	string (enum) - PF, PJ	Sim	Tipo do titular
name	string	Sim	Nome do titular
document	string	Sim	Documento do titular
bankAccount	object	Sim	Dados bancários (ver Sub-Objeto BankAccount)
pix	object	Sim	Chave PIX do titular (ver Sub-Objeto PixKeyVo)

BankAccount

Campo	Tipo	Obrigatório	Descrição
type	string	Sim	Tipo de conta
digit	string	Sim	Dígito da conta
ispb	string	Sim	ISPB do banco

PixKeyVo

Campo	Tipo	Obrigatório	Descrição
key	string	Sim	Chave PIX
type	string (enum) - CPF, CNPJ, EMAIL, PHONE, EVP	Sim	Tipo da chave PIX

SpeiAccountVo

Campo	Tipo	Obrigatório	Descrição
clabe	object	Sim	CLABE da conta de destino, no campo value
holderName	string	Sim	Nome do titular da conta
institutionId	string	Não	Identificador da instituição de destino

Exemplo de payload

Dados mascarados

Valores sensíveis podem estar mascarados com ***.

{
  "type": "WITHDRAWAL_PROCESSED",
  "data": {
    "id": "553e8400-e29b-41d4-a716-436251480000",
    "externalCode": "SAQUE-123",
    "amount": 10000,
    "method": "PIX",
    "status": "PROCESSED",
    "createdAt": "2026-03-06T12:49:04.681Z",
    "endToEnd": "0123456789",
    "pixKey": {
      "key": "12345678910",
      "type": "CPF"
    },
    "receiver": {
      "type": "PJ",
      "name": "Empresa Exemplo LTDA",
      "document": "12345678000199",
      "bankAccount": {
        "type": "CHECKING",
        "digit": "0",
        "ispb": "12345678"
      },
      "pix": {
        "key": "contato@exemplo.com",
        "type": "EMAIL"
      }
    },
    "payer": {
      "type": "PF",
      "name": "Fulano de Tal",
      "document": "***456789**",
      "bankAccount": {
        "type": "CHECKING",
        "digit": "7",
        "ispb": "12345678"
      },
      "pix": {
        "key": "12345678910",
        "type": "CPF"
      }
    },
    "amountWithdrawn": 10000,
    "processedDate": "2026-03-06T12:49:04.681Z",
    "paymentReceipt": "https://files.exemplo.com.br/receipts/withdrawal-553e8400-e29b-41d4-a716-436251480000.pdf"
  }
}