Consultar um saque

Recupera todos os detalhes de um saque específico a partir do seu identificador (cash_…): valor, status atual, método de transferência, taxa aplicada e os carimbos de tempo de criação, aprovação e pagamento. Use quando precisar confirmar em que ponto do fluxo um repasse está — por exemplo, depois de criar o saque ou ao responder a uma dúvida sobre uma transferência.

GET /v1/withdrawals/{withdrawalId}

Como funciona

Um saque (withdrawal) é a transferência de fundos disponíveis da sua conta Selectwin para uma carteira bancária (wall_…). Ele nasce com POST /v1/withdrawals e, a partir daí, avança por uma sequência de estados até ser pago, falhar ou ser cancelado. Este endpoint é a forma de ler o estado atual de um saque já existente.

A operação é uma leitura simples (idempotente e sem efeitos colaterais): você informa o withdrawalId na URL e recebe o objeto completo do saque. Diferente da listagem — que devolve uma projeção leve de cada item —, a leitura individual traz o objeto inteiro, incluindo o walletId de destino, o bloco merchant e os links _links (HATEOAS) para navegar até as operações relacionadas.

O campo mais importante na resposta é o status, que reflete a etapa do ciclo de vida do saque:

O ID é opaco: armazene a string cash_… inteira e não tente interpretá-la. Veja Convenções.

Quando usar (e quando não usar)

Use para:

• Confirmar o resultado logo após criar um saque com Criar Saque.
• Buscar os detalhes completos de um item que apareceu na listagem — a lista omite alguns campos (como walletId).
• Atender suporte/auditoria: mostrar a um cliente em que estado a transferência dele está.

Não use para vigiar um saque em busca de mudança de status. Repetir esta chamada em laço (polling) gasta seu limite de requisições e é desencorajado. Para reagir a mudanças de estado em tempo real, assine os webhooks de saque (withdrawal.processing, withdrawal.confirmed, withdrawal.refused, …) — veja Proibição de Polling. Esta leitura serve para uma conferência pontual, não para acompanhamento contínuo.

Requisição

Headers

Por ser uma leitura (GET), não há corpo nem Content-Type, e idempotência não se aplica.

Parâmetros de caminho

Exemplo de requisição

curl https://api.selectwin.io/v1/withdrawals/cash_01hqzvabc \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ"

Resposta

Em caso de sucesso, a API responde com 200 OK e o objeto completo do saque.

{
  "id": "cash_01hqzvabc",
  "walletId": "wall_01hqzvabc",
  "amount": 100000,
  "status": "pending",
  "method": "bankTransfer",
  "currency": "BRL",
  "fee": 15,
  "transferCode": null,
  "paidAt": null,
  "approvedAt": null,
  "updatedAt": "2026-04-12T17:56:33.000Z",
  "createdAt": "2026-04-12T17:56:33.000Z",
  "merchant": {
    "name": "Seller Name",
    "merchantId": "bus_1234567890",
    "isSubAccount": false
  },
  "_links": {
    "self": {
      "href": "https://api.selectwin.io/v1/withdrawals/cash_01hqzvabc",
      "method": "GET",
      "description": "Read a withdrawal."
    },
    "create": {
      "href": "https://api.selectwin.io/v1/withdrawals",
      "method": "POST",
      "description": "Make a withdrawal."
    },
    "list": {
      "href": "https://api.selectwin.io/v1/withdrawals",
      "method": "GET",
      "description": "List withdrawals."
    }
  }
}

Campos da resposta

Erros

Em caso de falha, a API retorna o status HTTP correspondente e um envelope com error.code estável. Trate sempre pelo error.code, nunca pela message — veja Tratamento de Erros.

Exemplo de resposta de erro (ID malformado):

{
  "error": {
    "code": "withdrawalIdIsInvalid",
    "statusCode": 400,
    "category": "validation",
    "message": "Withdrawal ID is invalid"
  }
}

A lista completa de códigos por recurso está no Catálogo de Códigos de Erro.

Boas práticas

• Cacheie estados finais. Uma vez que o saque chegue a paid, failed ou canceled, ele não muda mais — guarde o resultado e evite reler. Releia apenas o que estiver em pending/approved/processing.
• Prefira webhooks ao polling. Em vez de reler para detectar mudança de status, assine os eventos de saque e atualize seu sistema quando eles chegarem. Veja Proibição de Polling.
• Confirme a transferência por paidAt e transferCode. Considere o saque efetivamente pago só quando status for paid e paidAt estiver preenchido; use transferCode para reconciliar com o extrato bancário.
• Trate o ID como opaco. Armazene a string cash_… inteira; não a interprete nem reconstrua.
• Distinga 404 de 403. notFound indica ID inexistente na sua conta; forbidden indica falta de permissão — tratar os dois da mesma forma esconde problemas de chave de API.
• Lembre da projeção da lista. Se um campo (ex.: walletId) aparece vazio ao iterar a listagem, busque o objeto completo aqui.

Veja também

• Visão Geral de Saques — o objeto de saque, ciclo de vida e eventos de webhook.
• Criar Saque — solicitar um novo saque.
• Listar Saques — listar e filtrar saques.
• Convenções · Tratamento de Erros · Proibição de Polling