Webhook de Retiro

Los webhooks son notificaciones automáticas que la API envía cuando ocurre un evento del retiro. Así no necesita estar consultando la API: basta con recibir y procesar el evento cuando llegue.

Si trabaja con transacciones, vea Webhook de Transacción.

Eventos soportados

Evento	Cuándo se envía
WITHDRAWAL_CREATED	Cuando se crea el retiro
WITHDRAWAL_APPROVED	Cuando el retiro es aprobado
WITHDRAWAL_PROCESSED	Cuando el retiro es procesado
WITHDRAWAL_APPROVED_AND_PROCESSED	Cuando el retiro es aprobado y procesado
WITHDRAWAL_CANCELED	Cuando el retiro es cancelado
WITHDRAWAL_REFUNDED	Cuando el retiro es reembolsado
WITHDRAWAL_REJECTED	Cuando el retiro es rechazado
WITHDRAWAL_FAILED	Cuando el retiro falla

Formato del payload

Campo	Tipo	Obligatorio	Descripción
type	string (enum) - WITHDRAWAL_CREATED, WITHDRAWAL_APPROVED, WITHDRAWAL_PROCESSED, WITHDRAWAL_APPROVED_AND_PROCESSED, WITHDRAWAL_CANCELED, WITHDRAWAL_REFUNDED, WITHDRAWAL_REJECTED, WITHDRAWAL_FAILED	Sí	Tipo del evento enviado en el webhook
data	object	Sí	Datos del retiro

Payload base

Estos campos están presentes en todos los webhooks de retiro.

Campo	Tipo	Obligatorio	Descripción
id	string (UUID)	Sí	Identificador único del retiro
externalCode	string	Sí	Su código de referencia
amount	number	Sí	Monto del retiro, en centavos
method	string (enum) - PIX	Sí	Método del retiro
status	string (enum) - PENDING, PROCESSING, PROCESSED, FAILED, CANCELED, REFUNDED, REJECTED, PENDING_COMPLIANCE	Sí	PENDING: retiro creado, en espera de procesamiento PROCESSING: retiro en procesamiento PROCESSED: retiro procesado con éxito FAILED: error en el procesamiento CANCELED: retiro cancelado REFUNDED: retiro reembolsado REJECTED: retiro rechazado por el gateway PENDING_COMPLIANCE: retiro pendiente de revisión de compliance
createdAt	string (ISO)	Sí	Fecha de creación
endToEnd	string	Sí	Identificador end-to-end del retiro

Variaciones por evento

WITHDRAWAL_CREATED, WITHDRAWAL_APPROVED y WITHDRAWAL_REJECTED

Usan solamente el payload base.

WITHDRAWAL_PROCESSED y WITHDRAWAL_APPROVED_AND_PROCESSED

Además del payload base, agregan:

Campo	Tipo	Obligatorio	Descripción
pixKey	object	Sí	Clave PIX (ver Sub-Objeto PixKeyVo)
trackingKey	string	No	Clave de rastreo del SPEI. En retiros PIX siempre viene null
receiver	object	No	Datos del receptor (ver Sub-Objeto AccountHolder)
payer	object	No	Datos del pagador (ver Sub-Objeto AccountHolder)
amountWithdrawn	number	No	Monto efectivamente retirado
processedDate	string (ISO)	No	Fecha de procesamiento
paymentReceipt	string	No	URL del comprobante

WITHDRAWAL_CANCELED y WITHDRAWAL_FAILED

Además del payload base, agregan:

Campo	Tipo	Obligatorio	Descripción
reason	string	No	Motivo de la cancelación o de la falla, cuando se informa

WITHDRAWAL_REFUNDED

Además del payload base, agrega:

Campo	Tipo	Obligatorio	Descripción
refundAmount	number	Sí	Monto del reembolso
refundDate	string (ISO)	No	Fecha del reembolso
endToEndRefund	string	No	Identificador end-to-end del reembolso
refundReceipt	string	No	URL del comprobante de reembolso

Sub-Objetos

AccountHolder

Campo	Tipo	Obligatorio	Descripción
type	string (enum) - PF, PJ	Sí	Tipo de titular
name	string	Sí	Nombre del titular
document	string	Sí	Documento del titular
bankAccount	object	Sí	Datos bancarios (ver Sub-Objeto BankAccount)
pix	object	Sí	Clave PIX del titular (ver Sub-Objeto PixKeyVo)

BankAccount

Campo	Tipo	Obligatorio	Descripción
type	string	Sí	Tipo de cuenta
digit	string	Sí	Dígito de la cuenta
ispb	string	Sí	ISPB del banco

PixKeyVo

Campo	Tipo	Obligatorio	Descripción
key	string	Sí	Clave PIX
type	string (enum) - CPF, CNPJ, EMAIL, PHONE, EVP	Sí	Tipo de la clave PIX

SpeiAccountVo

Campo	Tipo	Obligatorio	Descripción
clabe	object	Sí	CLABE de la cuenta de destino, en el campo value
holderName	string	Sí	Nombre del titular de la cuenta
institutionId	string	No	Identificador de la institución de destino

Ejemplo de payload

Datos enmascarados

Los valores sensibles pueden estar enmascarados con ***.

{
  "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"
  }
}