Withdrawal Webhook

Webhooks are automatic notifications that the API sends when a withdrawal event happens. That way you do not have to keep polling the API: just receive and process the event when it arrives.

If you work with transactions, see Transaction Webhook.

Supported events

Event	When it is sent
WITHDRAWAL_CREATED	When the withdrawal is created
WITHDRAWAL_APPROVED	When the withdrawal is approved
WITHDRAWAL_PROCESSED	When the withdrawal is processed
WITHDRAWAL_APPROVED_AND_PROCESSED	When the withdrawal is approved and processed
WITHDRAWAL_CANCELED	When the withdrawal is canceled
WITHDRAWAL_REFUNDED	When the withdrawal is refunded
WITHDRAWAL_REJECTED	When the withdrawal is rejected
WITHDRAWAL_FAILED	When the withdrawal fails

Payload format

Field	Type	Required	Description
type	string (enum) - WITHDRAWAL_CREATED, WITHDRAWAL_APPROVED, WITHDRAWAL_PROCESSED, WITHDRAWAL_APPROVED_AND_PROCESSED, WITHDRAWAL_CANCELED, WITHDRAWAL_REFUNDED, WITHDRAWAL_REJECTED, WITHDRAWAL_FAILED	Yes	Type of the event sent in the webhook
data	object	Yes	Withdrawal data

Base payload

These fields are present in every withdrawal webhook.

Field	Type	Required	Description
id	string (UUID)	Yes	Unique identifier of the withdrawal
externalCode	string	Yes	Your reference code
amount	number	Yes	Withdrawal amount, in cents
method	string (enum) - PIX	Yes	Withdrawal method
status	string (enum) - PENDING, PROCESSING, PROCESSED, FAILED, CANCELED, REFUNDED, REJECTED, PENDING_COMPLIANCE	Yes	PENDING: withdrawal created, awaiting processing PROCESSING: withdrawal being processed PROCESSED: withdrawal processed successfully FAILED: processing error CANCELED: withdrawal canceled REFUNDED: withdrawal refunded REJECTED: withdrawal rejected by the gateway PENDING_COMPLIANCE: withdrawal awaiting compliance review
createdAt	string (ISO)	Yes	Creation date
endToEnd	string	Yes	End-to-end identifier of the withdrawal

Variations per event

WITHDRAWAL_CREATED, WITHDRAWAL_APPROVED and WITHDRAWAL_REJECTED

They use the base payload only.

WITHDRAWAL_PROCESSED and WITHDRAWAL_APPROVED_AND_PROCESSED

In addition to the base payload, they add:

Field	Type	Required	Description
pixKey	object	Yes	PIX key (see Sub-Object PixKeyVo)
trackingKey	string	No	SPEI clave de rastreo. It always comes back null on PIX withdrawals
receiver	object	No	Receiver data (see Sub-Object AccountHolder)
payer	object	No	Payer data (see Sub-Object AccountHolder)
amountWithdrawn	number	No	Amount actually withdrawn
processedDate	string (ISO)	No	Processing date
paymentReceipt	string	No	URL of the receipt

WITHDRAWAL_CANCELED and WITHDRAWAL_FAILED

In addition to the base payload, they add:

Field	Type	Required	Description
reason	string	No	Reason for the cancellation or failure, when provided

WITHDRAWAL_REFUNDED

In addition to the base payload, it adds:

Field	Type	Required	Description
refundAmount	number	Yes	Refund amount
refundDate	string (ISO)	No	Refund date
endToEndRefund	string	No	End-to-end identifier of the refund
refundReceipt	string	No	URL of the refund receipt

Sub-Objects

AccountHolder

Field	Type	Required	Description
type	string (enum) - PF, PJ	Yes	Holder type
name	string	Yes	Holder name
document	string	Yes	Holder document
bankAccount	object	Yes	Bank data (see Sub-Object BankAccount)
pix	object	Yes	PIX key of the holder (see Sub-Object PixKeyVo)

BankAccount

Field	Type	Required	Description
type	string	Yes	Account type
digit	string	Yes	Account check digit
ispb	string	Yes	ISPB of the bank

PixKeyVo

Field	Type	Required	Description
key	string	Yes	PIX key
type	string (enum) - CPF, CNPJ, EMAIL, PHONE, EVP	Yes	PIX key type

SpeiAccountVo

Field	Type	Required	Description
clabe	object	Yes	CLABE of the destination account, in the value field
holderName	string	Yes	Name of the account holder
institutionId	string	No	Identifier of the destination institution

Payload example

Masked data

Sensitive values may be masked with ***.

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