Criar um saque

Solicita a transferência de fundos disponíveis do seu saldo na Selectwin para uma carteira bancária cadastrada. O saque é criado com status pending e segue de forma assíncrona por etapas de verificação até ser pago — você acompanha o resultado por webhooks ou consultando o recurso.

POST /v1/withdrawals

Como funciona

Um saque (withdrawal, prefixo de ID cash_) move dinheiro do seu saldo disponível para uma carteira (wall_) que você já registrou — uma conta bancária ou chave Pix. A criação é apenas o pedido: o repasse em si não é instantâneo.

Ao receber o POST, o servidor:

1. Valida o corpo (amount inteiro positivo em centavos, walletId no formato prefixo_valor).
2. Verifica se a carteira existe e está apta a receber.
3. Confere se o valor atende ao mínimo do seu plano de taxas e se há saldo suficiente.
4. Calcula a taxa do saque (fee) e cria o registro com status: "pending".

A partir daí o saque percorre seu ciclo de vida de forma assíncrona. O method (ex.: bankTransfer, pix) é determinado pela carteira de destino, não enviado por você.

Enquanto está pending, os campos approvedAt e paidAt vêm null; eles são preenchidos conforme o saque avança. Use os campos de timestamp para saber em que etapa ele está.

Quando usar

• Repassar para a conta da empresa o que você acumulou de vendas.
• Pagar fornecedores, parceiros ou sócios a partir do saldo disponível.
• Programar retiradas recorrentes no seu próprio sistema (cada uma é uma chamada a este endpoint).

Quando não usar: este endpoint não cria nem edita a carteira de destino — a carteira precisa existir antes (recurso Wallets). Ele também não consulta saldo: para saber quanto está disponível e qual o mínimo do plano, use Consultar Saldo primeiro.

Requisição

Headers

Corpo

O method e a currency (BRL) não são enviados: derivam da carteira e da conta. A taxa (fee) é calculada pelo servidor.

Exemplo curl

curl -X POST https://api.selectwin.io/v1/withdrawals \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: 9f1c2e7a-4b3d-4a6e-9c10-2f8b7d5e1a23" \
  -d '{
    "amount": 50000,
    "walletId": "wall_01hqzvabc"
  }'

Resposta

Em caso de sucesso, o servidor responde 201 Created com o objeto do saque recém-criado.

{
  "id": "cash_01hqzvabc",
  "walletId": "wall_01hqzvabc",
  "amount": 50000,
  "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

Trate sempre pelo error.code (estável), nunca pela message. A estrutura do envelope está em Tratamento de Erros; a lista completa em Catálogo de Códigos de Erro.

Exemplo de erro de validação (400):

{
  "error": {
    "code": "invalidParameters",
    "statusCode": 400,
    "category": "validation",
    "message": "Validation errors occurred.",
    "params": [
      { "amount": "amount must be a positive integer" }
    ]
  }
}

Boas práticas

• Cheque o saldo e o mínimo antes: chame Consultar Saldo e leia o feePlan para evitar balanceIsInsufficient e withdrawalAmountLessThanMinimum.
• Envie centavos, sempre como inteiro: R$ 450,00 é 45000 (número), nunca "450.00" nem string.
• Use X-Idempotency-Key em toda criação: protege contra saques duplicados em retries de rede.
• Garanta a carteira antes: confirme que walletId existe e está registrada para não cair em withdrawalProcessFailedByWalletNotRegistered.
• Guarde o id (cash_…) retornado: é a chave para consultar o status e para correlacionar com seus registros internos.
• Reaja por webhooks, não por polling: o saque nasce pending; aprovação e pagamento chegam por eventos. Veja Proibição de polling.
• Trate o erro pelo code: ramifique a lógica no error.code e use o error.statusCode/category no default.

Veja também

• Visão geral de Saques — o que é o recurso e seu ciclo de vida.
• Consultar Saque — ver o status e os detalhes de um saque.
• Listar Saques — histórico com filtros e paginação.
• Consultar Saldo — saldo disponível e mínimo do plano de taxas.
• Convenções da API · Idempotência · Catálogo de Códigos de Erro