Listar saques

Recupera, de forma paginada, o histórico de saques (repasses bancários) da sua conta, com filtros por status, método de pagamento, período e identificador. Use este endpoint para acompanhar repasses, conciliar com o extrato bancário e construir relatórios financeiros.

GET /v1/withdrawals

Como funciona

Um saque (recurso withdrawal, prefixo de ID cash_) é uma ordem de transferência do saldo disponível da sua conta para uma carteira bancária (wallet) cadastrada. Cada saque tem um ciclo de vida assíncrono: nasce como pending, é aprovado e, então, liquidado (pago) ou rejeitado.

Este endpoint devolve uma lista paginada desses saques. Alguns pontos do mecanismo que vale entender antes de integrar:

• Projeção leve. Os itens em data[] são versões resumidas do objeto. Em particular, o campo walletId não vem na listagem. Para obter o objeto completo de um saque (incluindo walletId), use Consultar saque com o id.
• Paginação por offset. A resposta carrega offset, limit, total, hasMore e um bloco page com a página atual e os offsets de navegação (first/prev/next/last). Veja Paginação para o padrão completo.
• HATEOAS. O bloco _links traz links navegáveis (self, create) já prontos com método e URL absoluta — útil para descobrir as próximas ações sem montar URLs à mão.
• Somente leitura. A listagem não altera nada. Não precisa de chave de idempotência.

O status exato segue o ciclo de vida do saque. Para mudanças de estado em tempo real, prefira webhooks a ficar consultando esta lista em loop — veja Por que não fazer polling.

Quando usar

• Conciliação bancária: cruzar os saques liquidados com as entradas do seu extrato.
• Relatórios e auditoria: montar um histórico financeiro filtrando por período.
• Painéis e monitoramento: listar saques pending ou approved para acompanhar repasses em andamento.

Quando não usar:

• Para os detalhes completos de um saque (com walletId), use Consultar saque — é mais barato e traz o objeto inteiro.
• Para reagir a uma mudança de status (ex.: saque foi pago), use webhooks em vez de re-listar periodicamente.

Requisição

Headers

Esta é uma requisição GET sem corpo, portanto não envia Content-Type. Autentique sempre pelo header SelectKey — a API não usa Authorization: Bearer nem Basic.

Parâmetros de query

Todos são opcionais. Combine-os para refinar a busca.

Exemplo curl

# Listar os 20 saques pendentes mais recentes via Pix em abril de 2026
curl -G "https://api.selectwin.io/v1/withdrawals" \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ" \
  --data-urlencode "limit=20" \
  --data-urlencode "sort=descending" \
  --data-urlencode "status=pending" \
  --data-urlencode "method=pix" \
  --data-urlencode "daterangegte=2026-04-01T00:00:00Z" \
  --data-urlencode "daterangelte=2026-04-30T23:59:59Z"

Resposta

200 OK com o objeto paginado. Cada item de data[] é uma projeção leve do saque (sem walletId).

{
  "offset": 0,
  "limit": 20,
  "total": 1,
  "page": {
    "offset": { "first": 0, "prev": null, "next": null, "last": 0 },
    "current": 1,
    "total": 1
  },
  "data": [
    {
      "id": "cash_01hqzvabc",
      "amount": 45000,
      "status": "pending",
      "method": "bankTransfer",
      "currency": "BRL",
      "fee": 0,
      "transferCode": null,
      "paidAt": null,
      "approvedAt": null,
      "updatedAt": "2026-04-12T17:56:33.000Z",
      "createdAt": "2026-04-12T17:56:33.000Z"
    }
  ],
  "hasMore": false,
  "merchant": {
    "name": "Seller Name",
    "merchantId": "bus_1234567890",
    "isSubAccount": false
  },
  "_links": {
    "self": {
      "href": "https://api.selectwin.io/v1/withdrawals",
      "method": "GET",
      "description": "List withdrawals."
    },
    "create": {
      "href": "https://api.selectwin.io/v1/withdrawals",
      "method": "POST",
      "description": "Make a withdrawal."
    }
  }
}

Campos do envelope paginado

Campos de cada saque (data[])

Erros

Trate sempre pelo error.code (estável), nunca pela message. Veja Tratamento de Erros e o Catálogo de Códigos de Erro.

Boas práticas

• Pagine sempre. Use limit (até 100) e offset; pare quando hasMore for false em vez de assumir um total fixo. Para listagens grandes, prefira _links e os offsets de page para navegar.
• Filtre no servidor, não no cliente. Restringir por status, method e o intervalo daterangegte/daterangelte reduz dados trafegados e custo de processamento — mais eficiente do que baixar tudo e filtrar localmente.
• Datas em UTC. Envie os filtros de data em ISO 8601 com sufixo Z; converta para o fuso do usuário apenas na exibição.
• Valores em centavos. amount e fee são inteiros em centavos; divida por 100 só para exibir.
• Não construa IDs. Use o id retornado como string opaca; passe-o direto para Consultar saque quando precisar dos detalhes.
• Não faça polling para acompanhar status. Para saber quando um saque foi pago ou recusado, assine os webhooks em vez de re-listar em loop — veja Por que não fazer polling.
• Concilie pelo período correto. Para fechamento, combine daterangegte/daterangelte cobrindo o ciclo e cruze transferCode com o extrato bancário.

Veja também

• Visão geral de Saques — o recurso, o modelo do objeto e o ciclo de vida.
• Criar saque — solicitar um novo repasse.
• Consultar saque — detalhes completos de um saque (com walletId).
• Paginação e Convenções.