查询提现列表

使用此端点按筛选条件查询提现列表。

可用环境

生产环境

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

端点

方法：GET
端点：/withdrawal
认证方式：Bearer token

查询参数

ℹ️ 使用 ISO 日期

startDate 和 endDate 必须以带时间的 ISO date string 格式传入。

示例：

2026-03-06T12:00:00.000Z

ℹ️ snapshot 分页

snapshot 并不是指向“下一页”的指针：它是分页会话的固定标识，与 page（仍需正常传入并递增）配合使用，即使在翻页过程中产生了新记录，也能保持结果一致。

请从第一次响应中取得 snapshot 的值（首次请求不传 snapshot），并在后续各页的请求中原样重发该值，同时保持与最初相同的筛选条件和相同的 perPage。如果在重发旧 snapshot 时其中任一值发生变化，API 将返回错误。

名称	类型	必填	说明	校验规则
`snapshot`	string	否	分页会话的标识（取自第一次响应的 `snapshot` 字段）；在后续页中与 `page` 一起原样重发	必须与原始请求的筛选条件及 `perPage` 一致
`startDate`	string	否	筛选的起始日期	必须为带时间的 ISO date string
`endDate`	string	否	筛选的结束日期	必须为带时间的 ISO date string
`status`	string[] (enum) - `PENDING`, `PROCESSING`, `PROCESSED`, `FAILED`, `CANCELED`, `REFUNDED`, `REJECTED`, `PENDING_COMPLIANCE`	否	用于筛选的状态列表	必须为非空且不含重复项的数组
`id`	string (UUID v4)	否	提现的标识	必须为有效的 UUID v4
`pixKey`	string	否	该笔提现的 PIX 密钥	必须为有效的 PIX 密钥（CPF、CNPJ、EMAIL、PHONE 或 EVP）
`endToEnd`	string	否	提现的 end-to-end 标识	长度须在 8 到 255 个字符之间
`endToEndRefund`	string	否	退回的 end-to-end 标识	长度须在 8 到 255 个字符之间
`externalCode`	string	否	您的参考编号	长度须在 8 到 255 个字符之间
`minAmount`	number	否	提现的最小金额（分）	必须为以分为单位的整数；最小 `10`（R$0.10），最大 `10000000`（R$100,000.00）
`maxAmount`	number	否	提现的最大金额（分）	必须为以分为单位的整数；最小 `10`（R$0.10），最大 `10000000`（R$100,000.00）

请求示例

cURL
JavaScript

curl --request GET \
--url https://api.gateway.com.br/core/withdrawal?status=PENDING&status=PROCESSING&startDate=2026-03-06T00:00:00.000Z&endDate=2026-03-06T23:59:59.999Z \
--header 'Authorization: Bearer your-jwt-token'

const params = new URLSearchParams({
  startDate: '2026-03-06T00:00:00.000Z',
  endDate: '2026-03-06T23:59:59.999Z'
});
params.append('status', 'PENDING');
params.append('status', 'PROCESSING');

const response = await fetch(`https://api.gateway.com.br/core/withdrawal?${params}`, {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer your-jwt-token'
  }
});
const data = await response.json();

成功响应

字段	类型	必填	说明
`totalPages`	number	是	总页数
`currentPage`	number	是	当前页
`perPage`	number	是	每页条数
`snapshot`	string	否	分页会话的标识；在后续页中原样重发
`data`	array	是	提现列表

`data` 中每一项的字段

字段	类型	必填	说明
`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)	是	凭证的过期日期

响应示例

数据脱敏

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

{
  "totalPages": 1,
  "currentPage": 1,
  "perPage": 15,
  "snapshot": "b3BhcXVlLXNuYXBzaG90LXRva2Vu",
  "data": [
    {
      "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	无权限或未授权	请联系技术支持
422	数据无效或缺失	请检查数据格式
422	校验失败	请联系技术支持
500	内部错误	请联系技术支持

可用环境​

端点​

查询参数​

请求示例​

成功响应​

data 中每一项的字段​

子对象​

StatusHistory（列表项）​

AccountHolder​

BankAccount​

PixKeyVo​

PaymentReceiptUrl​

响应示例​

可能的错误​