Listar Saques

Utilize este endpoint para listar saques com filtros.

Ambientes Disponíveis

Produção

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

Endpoint

Método: GET
Endpoint: /withdrawal
Autenticação: Bearer token

Query Params

ℹ️ Datas em ISO

Os campos startDate e endDate devem ser enviados em ISO date string com horário.

Exemplo:

2026-03-06T12:00:00.000Z

ℹ️ Paginação por snapshot

O snapshot não é um ponteiro para a "próxima página": é um identificador fixo da sessão de paginação, usado junto com page (que continua sendo enviado e incrementado normalmente) para manter os resultados consistentes mesmo se novos registros forem criados durante a navegação.

Pegue o valor de snapshot na primeira resposta (sem enviar snapshot no primeiro request) e reenvie esse mesmo valor, sem alterá-lo, nas requisições das páginas seguintes, junto com os mesmos filtros e o mesmo perPage usados originalmente. Se algum desses valores mudar enquanto um snapshot antigo é reenviado, a API retorna erro.

Nome	Tipo	Obrigatório	Descrição	Validações
`snapshot`	string	Não	Identificador da sessão de paginação (recebido no campo `snapshot` da primeira resposta); reenvie sem alterar junto com `page` nas páginas seguintes	Deve corresponder aos mesmos filtros e ao mesmo `perPage` da requisição original
`startDate`	string	Não	Data inicial do filtro	Deve ser ISO date string com horário
`endDate`	string	Não	Data final do filtro	Deve ser ISO date string com horário
`status`	string[] (enum) - `PENDING`, `PROCESSING`, `PROCESSED`, `FAILED`, `CANCELED`, `REFUNDED`, `REJECTED`, `PENDING_COMPLIANCE`	Não	Lista de status para filtrar	Deve ser um array não vazio e sem duplicados
`id`	string (UUID v4)	Não	Identificador do saque	Deve ser UUID v4 válido
`pixKey`	string	Não	Chave PIX do saque	Deve ser uma chave PIX válida (CPF, CNPJ, EMAIL, PHONE ou EVP)
`endToEnd`	string	Não	Identificador end-to-end do saque	Deve ter entre 8 e 255 caracteres
`endToEndRefund`	string	Não	Identificador end-to-end do estorno	Deve ter entre 8 e 255 caracteres
`externalCode`	string	Não	Seu código de referência	Deve ter entre 8 e 255 caracteres
`minAmount`	number	Não	Valor mínimo do saque (centavos)	Deve ser inteiro em centavos; mínimo `10` (R$ 0,10) e máximo `10000000` (R$ 100.000,00)
`maxAmount`	number	Não	Valor máximo do saque (centavos)	Deve ser inteiro em centavos; mínimo `10` (R$ 0,10) e máximo `10000000` (R$ 100.000,00)

Exemplo de Requisição

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 seu-token-jwt'

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 seu-token-jwt'
  }
});
const data = await response.json();

Resposta de Sucesso

Campo	Tipo	Obrigatório	Descrição
`totalPages`	number	Sim	Total de páginas
`currentPage`	number	Sim	Página atual
`perPage`	number	Sim	Itens por página
`snapshot`	string	Não	Identificador da sessão de paginação; reenvie sem alterações nas páginas seguintes
`data`	array	Sim	Lista de saques

Campos do item em `data`

Campo	Tipo	Obrigatório	Descrição
`id`	string (UUID)	Sim	Identificador único do saque
`acquirerCode`	string	Não	Código do adquirente
`acquirer`	string	Sim	Adquirente do saque
`amount`	number	Sim	Valor do saque (inteiro em centavos)
`method`	string (enum) - `PIX`	Sim	Método do saque
`webhookUrl`	string	Não	URL de webhook configurada
`externalCode`	string	Não	Seu código de referência
`paymentReceipt`	object	Não	Comprovante de pagamento (ver Sub-Objeto `PaymentReceiptUrl`)
`refundReceipt`	object	Não	Comprovante de estorno (ver Sub-Objeto `PaymentReceiptUrl`)
`createdAt`	string (ISO)	Sim	Data de criação
`status`	string (enum) - `PENDING`, `PROCESSING`, `PROCESSED`, `FAILED`, `CANCELED`, `REFUNDED`, `REJECTED`, `PENDING_COMPLIANCE`	Sim	PENDING: Saque criado, aguardando processamento PROCESSING: Saque em processamento PROCESSED: Saque processado com sucesso FAILED: Erro no processamento CANCELED: Saque cancelado REFUNDED: Saque estornado REJECTED: Saque rejeitado pela gateway PENDING_COMPLIANCE: Saque pendente de análise de compliance
`statusHistory`	array	Sim	Histórico de status (ver Sub-Objetos `StatusHistory`)
`updatedAt`	string (ISO)	Sim	Data da última atualização
`amountWithdrawn`	number	Não	Valor efetivamente sacado
`processedDate`	string (ISO)	Não	Data de processamento
`errorMessage`	string	Não	Mensagem de erro
`endToEnd`	string	Não	Identificador end-to-end do saque
`endToEndRefund`	string	Não	Identificador end-to-end do estorno
`refundDate`	string (ISO)	Não	Data do estorno
`refundAmount`	number	Não	Valor do estorno (inteiro em centavos)
`payer`	object	Não	Dados do pagador (ver Sub-Objetos `AccountHolder`)
`receiver`	object	Não	Dados do recebedor (ver Sub-Objetos `AccountHolder`)
`pixKey`	object	Não	Dados da chave PIX (ver Sub-Objetos `PixKeyVo`)
`trackingKey`	string	Não	Clave de rastreo do SPEI. Vem sempre `null` em saques PIX
`feeAmount`	number	Não	Valor da taxa

Sub-Objetos

StatusHistory (item)

Campo	Tipo	Obrigatório	Descrição
`status`	string (enum) - `PENDING`, `PROCESSING`, `PROCESSED`, `FAILED`, `CANCELED`, `REFUNDED`, `REJECTED`, `PENDING_COMPLIANCE`	Sim	Status do saque
`date`	string (ISO)	Sim	Data do status
`durationInMilliseconds`	number	Sim	Duração do status em milissegundos

AccountHolder

Campo	Tipo	Obrigatório	Descrição
`type`	string (enum) - `PF`, `PJ`	Sim	Tipo do titular
`name`	string	Sim	Nome do titular
`document`	string	Sim	Documento do titular
`bankAccount`	object	Sim	Dados bancários (ver Sub-Objetos `BankAccount`)
`pix`	object	Sim	Chave PIX do titular (ver Sub-Objetos `PixKeyVo`)

BankAccount

Campo	Tipo	Obrigatório	Descrição
`type`	string	Sim	Tipo de conta
`digit`	string	Sim	Dígito da conta
`ispb`	string	Sim	ISPB do banco

PixKeyVo

Campo	Tipo	Obrigatório	Descrição
`key`	string	Sim	Chave PIX
`type`	string (enum) - `CPF`, `CNPJ`, `EMAIL`, `PHONE`, `EVP`	Sim	Tipo da chave PIX

PaymentReceiptUrl

Campo	Tipo	Obrigatório	Descrição
`url`	string	Sim	URL do comprovante
`expirationDate`	string (ISO)	Sim	Data de expiração do comprovante

Exemplo de Resposta

Dados mascarados

Valores sensíveis podem estar mascarados com ***.

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

Possíveis Erros

Código	Descrição	Solução
401	Credenciais inválidas	Verifique suas credenciais
403	Sem permissão/autorização	Contate o suporte
422	Dados inválidos ou faltando	Verifique o formato dos dados
422	Validações	Contate o suporte
500	Erro interno	Contate o suporte

Ambientes Disponíveis​

Endpoint​

Query Params​

Exemplo de Requisição​

Resposta de Sucesso​

Campos do item em data​

Sub-Objetos​

StatusHistory (item)​

AccountHolder​

BankAccount​

PixKeyVo​

PaymentReceiptUrl​

Exemplo de Resposta​

Possíveis Erros​