查询提现

使用此端点通过 id 查询某一笔具体的提现。

可用环境

生产环境

https://api.gateway.com.br/core

端点

• 方法：GET
• 端点：/withdrawal/{id}
• 认证方式：Bearer token

路径参数

名称	类型	必填	说明	校验规则
id	string (UUID)	是	提现的标识	必须为有效的 UUID

请求示例

cURL

curl --request GET \
--url https://api.gateway.com.br/core/withdrawal/553e8400-e29b-41d4-a716-436251480000 \
--header 'Authorization: Bearer your-jwt-token'

JavaScript

const response = await fetch('https://api.gateway.com.br/core/withdrawal/553e8400-e29b-41d4-a716-436251480000', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer your-jwt-token'
  }
});
const data = await response.json();

成功响应

字段	类型	必填	说明
id	string (UUID)	是	提现的唯一标识
acquirerCode	string	否	收单机构代码
acquirer	string	是	该笔提现的收单机构
amount	number	是	提现金额（整数，以分为单位）
method	string (enum) - PIX	是	提现方式
webhookUrl	string	否	已配置的 webhook URL
externalCode	string	否	您的参考编号
paymentReceipt	object	否	支付凭证（参见子对象 PaymentReceiptUrl）
refundReceipt	object	否	退款凭证（参见子对象 PaymentReceiptUrl）
createdAt	string (ISO)	是	创建日期
status	string (enum) - PENDING, PROCESSING, PROCESSED, FAILED, CANCELED, REFUNDED, REJECTED, PENDING_COMPLIANCE	是	PENDING：提现已创建，等待处理 PROCESSING：提现处理中 PROCESSED：提现处理成功 FAILED：处理出错 CANCELED：提现已取消 REFUNDED：提现已退回 REJECTED：提现被网关拒绝 PENDING_COMPLIANCE：提现等待合规审核
statusHistory	array	是	状态历史（参见子对象 StatusHistory）
updatedAt	string (ISO)	是	最后更新日期
amountWithdrawn	number	否	实际提现金额
processedDate	string (ISO)	否	处理日期
errorMessage	string	否	错误信息
endToEnd	string	否	提现的 end-to-end 标识
endToEndRefund	string	否	退回的 end-to-end 标识
refundDate	string (ISO)	否	退回日期
refundAmount	number	否	退回金额（整数，以分为单位）
payer	object	否	付款方信息（参见子对象 AccountHolder）
receiver	object	否	收款方信息（参见子对象 AccountHolder）
pixKey	object	否	PIX 密钥信息（参见子对象 PixKeyVo）
trackingKey	string	否	SPEI 的 clave de rastreo（追踪码）。在 PIX 提现中始终返回 null
feeAmount	number	否	手续费金额

子对象

StatusHistory（列表项）

字段	类型	必填	说明
status	string (enum) - PENDING, PROCESSING, PROCESSED, FAILED, CANCELED, REFUNDED, REJECTED, PENDING_COMPLIANCE	是	提现状态
date	string (ISO)	是	该状态的日期
durationInMilliseconds	number	是	该状态的持续时长（毫秒）

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 密钥类型

PaymentReceiptUrl

字段	类型	必填	说明
url	string	是	凭证的 URL
expirationDate	string (ISO)	是	凭证的过期日期

响应示例

数据脱敏

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

{
  "id": "553e8400-e29b-41d4-a716-436251480000",
  "acquirerCode": "ACQ-123",
  "acquirer": "ACQUIRER_EXEMPLO",
  "amount": 10000,
  "method": "PIX",
  "webhookUrl": "https://sua-api.com/webhooks/withdrawal",
  "externalCode": "SAQUE-123",
  "paymentReceipt": {
    "url": "https://files.exemplo.com.br/receipts/withdrawal-553e8400-e29b-41d4-a716-436251480000.pdf",
    "expirationDate": "2026-04-01T00:00:00.000Z"
  },
  "refundReceipt": {
    "url": "https://files.exemplo.com.br/receipts/withdrawal-refund-553e8400-e29b-41d4-a716-436251480000.pdf",
    "expirationDate": "2026-04-01T00:00:00.000Z"
  },
  "createdAt": "2026-03-06T12:49:04.681Z",
  "status": "REFUNDED",
  "statusHistory": [
    {
      "status": "PENDING",
      "date": "2026-03-06T12:49:04.681Z",
      "durationInMilliseconds": 1000
    },
    {
      "status": "PROCESSING",
      "date": "2026-03-06T12:49:04.681Z",
      "durationInMilliseconds": 10000
    },
    {
      "status": "PROCESSED",
      "date": "2026-03-06T12:49:04.681Z",
      "durationInMilliseconds": 10000
    },
    {
      "status": "REFUNDED",
      "date": "2026-03-06T12:49:04.681Z",
      "durationInMilliseconds": 5000
    }
  ],
  "updatedAt": "2026-03-06T12:49:04.681Z",
  "amountWithdrawn": 10000,
  "processedDate":  "2026-03-06T12:49:04.681Z",
  "errorMessage": "Falha ao registrar o estorno no PSP",
  "endToEnd": "0123456789",
  "endToEndRefund": "0123456789-REFUND",
  "refundDate": "2026-03-06T14:49:04.681Z",
  "refundAmount": 10000,
  "payer": {
    "type": "PF",
    "name": "Fulano de Tal",
    "document": "***456789**",
    "bankAccount": {
      "type": "CHECKING",
      "digit": "7",
      "ispb": "12345678"
    },
    "pix": {
      "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"
    }
  },
  "pixKey": {
    "key": "12345678910",
    "type": "CPF"
  },
  "feeAmount": 150
}

可能的错误

状态码	说明	处理方式
401	凭据无效	请检查您的凭据
403	无权限或未授权	请联系技术支持
404	未找到记录	请检查所传入的 id
422	数据无效或缺失	请检查数据格式
422	校验失败	请联系技术支持
500	内部错误	请联系技术支持