提现 Webhook

Webhook 是提现事件发生时 API 自动发送的通知。 这样您就无需不断轮询 API：只需在事件到达时接收并处理即可。

如果您处理的是交易，请参见交易 Webhook。

支持的事件

事件	发送时机
WITHDRAWAL_CREATED	提现创建时
WITHDRAWAL_APPROVED	提现被批准时
WITHDRAWAL_PROCESSED	提现被处理时
WITHDRAWAL_APPROVED_AND_PROCESSED	提现被批准并处理时
WITHDRAWAL_CANCELED	提现被取消时
WITHDRAWAL_REFUNDED	提现被退回时
WITHDRAWAL_REJECTED	提现被拒绝时
WITHDRAWAL_FAILED	提现失败时

payload 格式

字段	类型	必填	说明
type	string (enum) - WITHDRAWAL_CREATED, WITHDRAWAL_APPROVED, WITHDRAWAL_PROCESSED, WITHDRAWAL_APPROVED_AND_PROCESSED, WITHDRAWAL_CANCELED, WITHDRAWAL_REFUNDED, WITHDRAWAL_REJECTED, WITHDRAWAL_FAILED	是	Webhook 中发送的事件类型
data	object	是	提现数据

基础 payload

以下字段出现在所有提现 Webhook 中。

字段	类型	必填	说明
id	string (UUID)	是	提现的唯一标识
externalCode	string	是	您的参考编号
amount	number	是	提现金额，以分为单位
method	string (enum) - PIX	是	提现方式
status	string (enum) - PENDING, PROCESSING, PROCESSED, FAILED, CANCELED, REFUNDED, REJECTED, PENDING_COMPLIANCE	是	PENDING：提现已创建，等待处理 PROCESSING：提现处理中 PROCESSED：提现处理成功 FAILED：处理出错 CANCELED：提现已取消 REFUNDED：提现已退回 REJECTED：提现被网关拒绝 PENDING_COMPLIANCE：提现等待合规审核
createdAt	string (ISO)	是	创建日期
endToEnd	string	是	提现的 end-to-end 标识

各事件的差异

WITHDRAWAL_CREATED、WITHDRAWAL_APPROVED 与 WITHDRAWAL_REJECTED

仅使用基础 payload。

WITHDRAWAL_PROCESSED 与 WITHDRAWAL_APPROVED_AND_PROCESSED

在基础 payload 之外，另增加：

字段	类型	必填	说明
pixKey	object	是	PIX 密钥（参见子对象 PixKeyVo）
trackingKey	string	否	SPEI 的 clave de rastreo（追踪码）。在 PIX 提现中始终返回 null
receiver	object	否	收款方信息（参见子对象 AccountHolder）
payer	object	否	付款方信息（参见子对象 AccountHolder）
amountWithdrawn	number	否	实际提现金额
processedDate	string (ISO)	否	处理日期
paymentReceipt	string	否	凭证的 URL

WITHDRAWAL_CANCELED 与 WITHDRAWAL_FAILED

在基础 payload 之外，另增加：

字段	类型	必填	说明
reason	string	否	取消或失败的原因，当有提供时返回

WITHDRAWAL_REFUNDED

在基础 payload 之外，另增加：

字段	类型	必填	说明
refundAmount	number	是	退回金额
refundDate	string (ISO)	否	退回日期
endToEndRefund	string	否	退回的 end-to-end 标识
refundReceipt	string	否	退回凭证的 URL

子对象

AccountHolder

字段	类型	必填	说明
type	string (enum) - PF, PJ	是	持有人类型
name	string	是	持有人姓名
document	string	是	持有人证件号
bankAccount	object	是	银行信息（参见子对象 BankAccount）
pix	object	是	持有人的 PIX 密钥（参见子对象 PixKeyVo）

BankAccount

字段	类型	必填	说明
type	string	是	账户类型
digit	string	是	账户校验位
ispb	string	是	银行的 ISPB

PixKeyVo

字段	类型	必填	说明
key	string	是	PIX 密钥
type	string (enum) - CPF, CNPJ, EMAIL, PHONE, EVP	是	PIX 密钥类型

SpeiAccountVo

字段	类型	必填	说明
clabe	object	是	目标账户的 CLABE，位于 value 字段
holderName	string	是	账户持有人的姓名
institutionId	string	否	目标机构的标识

payload 示例

数据脱敏

敏感信息可能以 *** 脱敏显示。

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