Visão geral

Um saque (withdrawal) transfere o dinheiro disponível do seu saldo na Selectwin para uma carteira bancária (wallet) que você cadastrou previamente. Use este recurso para resgatar o que vendeu: você solicita o valor, a plataforma valida o saldo e processa o repasse de forma assíncrona, notificando cada mudança de estado por webhook. Esta página explica o modelo do objeto, o ciclo de vida e todas as operações disponíveis.

O que é o recurso

Saque é o passo final do fluxo financeiro: o dinheiro de uma venda entra como pendente, é liberado e vira disponível no seu saldo e, então, você pode sacá-lo para uma carteira. Pontos-chave:

• O valor sai do seu saldo disponível e vai para a carteira indicada por walletId. Cadastre e gerencie carteiras no recurso Wallets antes de sacar.
• O processamento é assíncrono: a criação devolve um saque em pending (HTTP 201) e o repasse evolui em segundo plano. Acompanhe pelos webhooks (recomendado) ou consultando o saque (GET /v1/withdrawals/{withdrawalId}).
• Todos os valores são inteiros em centavos (45000 = R$ 450,00) e os timestamps seguem ISO 8601 UTC. Veja Convenções.

Modelo do objeto

O exemplo abaixo é a resposta completa de um saque (retornada por criar e consultar). Em listagens, cada item é uma projeção leve: não inclui walletId, merchant nem _links por item.

{
  "id": "cash_01hqzvabc",          // ID do saque (prefixo cash_), opaco
  "walletId": "wall_01hqzvabc",    // carteira de destino (ausente nos itens de lista)
  "amount": 45000,                 // valor em centavos = R$ 450,00
  "status": "pending",             // estado atual do saque
  "method": "bankTransfer",        // método do repasse (ex.: bankTransfer, pix)
  "currency": "BRL",               // ISO 4217
  "fee": 15,                       // taxa do saque, em centavos
  "transferCode": null,            // código da transferência (preenchido após processar)
  "paidAt": null,                  // quando foi pago (null = ainda não pago)
  "approvedAt": null,              // quando foi aprovado (null = ainda não aprovado)
  "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 do saque

Os campos transferCode, paidAt e approvedAt nascem null e são preenchidos conforme o saque avança. Use isso para distinguir um saque recém-criado de um já liquidado.

Ciclo de vida

O status é uma string que reflete o estágio do repasse. Você não muda o status por chamadas — quem o move é a plataforma, e cada transição dispara um webhook. Acompanhe pelos eventos, nunca por polling (veja Proibição de polling).

O conjunto exato de estados intermediários pode variar; trate qualquer status desconhecido como "ainda em andamento" e reaja aos estados terminais (paid, refused, canceled).

Operações

Base URL: https://api.selectwin.io/v1. Autentique toda requisição com o header SelectKey (nunca Authorization: Bearer/Basic) — em produção a chave começa com sl_live_; em sandbox, com sl_test_. Veja Autenticação.

Criar um saque (resumo)

A criação aceita apenas dois campos no corpo:

curl -X POST https://api.selectwin.io/v1/withdrawals \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -d '{
    "amount": 50000,
    "walletId": "wall_abc123"
  }'

A resposta é 201 Created com o saque em status: "pending". Use X-Idempotency-Key para evitar saques duplicados em caso de retry — veja Idempotência. Detalhes completos em Criar saque.

Eventos de webhook

Cada transição do saque emite um evento. Configure um endpoint de webhook e reaja a estes eventos em vez de consultar repetidamente a API:

Sempre verifique a assinatura do webhook antes de confiar no payload — veja Verificando Assinaturas de Webhook.

Erros

Trate sempre pelo error.code (estável), não pela message. Códigos específicos de saques:

Pode ocorrer também balanceIsInsufficient (422) quando o saldo disponível não cobre o valor. E os códigos transversais: unauthorized (401), forbidden (403), invalidParameters (400), unprocessableEntity/tooManyRequests (422/429) e serverError (500). Veja o Catálogo de Códigos de Erro e Tratamento de Erros.

Boas práticas

• Confirme o saldo disponível antes de sacar. Saque consome o saldo available; valores acima dele resultam em balanceIsInsufficient. Consulte seu saldo no recurso de Finanças.
• Respeite o valor mínimo do seu plano. Abaixo dele a API retorna withdrawalAmountLessThanMinimum. Calcule também a fee ao planejar quanto sacar.
• Cadastre e valide a carteira antes. Carteiras não registradas falham com withdrawalProcessFailedByWalletNotRegistered. Gerencie carteiras no recurso Wallets.
• Use X-Idempotency-Key na criação. Em retries de rede, garante que o mesmo saque não seja solicitado duas vezes.
• Reaja a webhooks, não a polling. Acompanhe withdrawal.* para saber quando o saque foi confirmado, recusado ou cancelado, em vez de consultar a API em laço.
• Sempre envie valores em centavos (45000) e nunca em reais com ponto decimal. Trate id e walletId como strings opacas.
• Para conciliação, busque o objeto completo. Itens de lista omitem walletId/merchant; quando precisar desses campos, faça GET /v1/withdrawals/{withdrawalId}.

Veja também

• Criar saque — solicitar um novo repasse.
• Consultar saque — ver status e detalhes de um saque.
• Listar saques — filtrar e paginar o histórico.
• Convenções · Autenticação · Idempotência · Catálogo de Códigos de Erro