Criar um saque

Visão Geral

Este endpoint permite solicitar a transferência de fundos disponíveis em sua conta para uma carteira específica. É utilizado para iniciar o processo de saque, que será posteriormente processado e transferido para a carteira associada ao walletId fornecido.

Precauções

ATENÇÃO! Por favor, leia estas informações importantes antes de usar este endpoint.

• Saldo Disponível: Verifique sempre o saldo disponível antes de solicitar um saque usando o endpoint Consultar Saldo. O valor (mais a taxa) é debitado do saldo disponível no ato da criação.
• Saques habilitados: O saque precisa estar habilitado para a empresa; caso contrário, a criação retorna 400 withdrawalCreateNotEnabled.
• Valor Mínimo: Existe um valor mínimo de saque por empresa (padrão R$ 50,00 = 5000 centavos quando não configurado). Abaixo dele a API retorna 400 withdrawalAmountLessThanMinimum.
• Processamento: Saques não são instantâneos e passam por um processo de verificação antes de serem aprovados e processados.
• Step-up (sessão de dashboard): Em uma sessão interativa (JWT), o saque exige autenticação recente + fator forte (TOTP/código de backup) re-provado via POST /v1/authentication/step-up; caso contrário a API retorna 401 stepUpRequired. Chamadas com API key não passam por step-up (a chave é a própria credencial).
• Carência de carteira nova: Uma carteira recém-cadastrada não pode receber saque até completar o período de carência de segurança (padrão 24h, configurável pela plataforma) — a API retorna 422 withdrawalWalletInCooldown. Vale apenas no ambiente live.
• Idempotência: A criação é idempotente — envie a header X-Idempotency-Key para evitar saques duplicados.
• Valores Monetários: Todos os valores monetários devem ser informados em centavos (por exemplo, R$ 450,00 deve ser enviado como 45000, um número inteiro).

Descrição

O endpoint de Criação de Saque permite solicitar a transferência de fundos disponíveis em sua conta para uma carteira específica. Ao fornecer o ID da carteira e o valor desejado, o sistema iniciará o processo de saque, que será verificado, aprovado e processado de acordo com as políticas e prazos vigentes.

Requisição

POST /v1/withdrawals

Corpo da Requisição

{
  "walletId": "wall_01hqzvabc",
  "amount": 45000
}

Parâmetros do Corpo

Resposta - 201 Created

Em caso de sucesso, o servidor responde com o código de status HTTP 201 Created e um objeto JSON contendo as informações do saque criado.

{
  "id": "cash_01hqzvabc",
  "walletId": "wall_01hqzvabc",
  "amount": 45000,
  "fee": 15,
  "status": "pending",
  "method": "bankTransfer",
  "currency": "BRL",
  "transferCode": null,
  "paidAt": null,
  "approvedAt": null,
  "createdAt": "2025-02-07T00:12:33.000Z",
  "updatedAt": "2025-02-07T00:12:33.000Z",
  "receivingBankAccount": {
    "holderName": "João Santos",
    "document": "12345678901",
    "bankCode": "260",
    "bankName": null,
    "routingNumber": "0001",
    "accountNumber": "11111111-5",
    "type": "checking",
    "pixKey": null
  },
  "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": "Create a new withdrawal."
    },
    "list": {
      "href": "https://api.selectwin.io/v1/withdrawals",
      "method": "GET",
      "description": "List all withdrawals."
    }
  }
}

Atributos da Resposta

Respostas de Erro

400 Bad Request (validação)

Ocorre quando a requisição contém parâmetros inválidos ou está mal formatada.

{
  "error": {
    "status": "Bad Request",
    "statusCode": 400,
    "category": "validation",
    "message": "Validation errors occurred.",
    "params": [
      {
        "amount": "The withdrawal amount must be greater than zero."
      }
    ]
  }
}

422 Unprocessable Entity (saldo insuficiente)

{
  "error": {
    "status": "Unprocessable Entity",
    "statusCode": 422,
    "category": "validation",
    "code": "balanceIsInsufficient",
    "message": "Insufficient available balance for this withdrawal."
  }
}

Casos de Uso

1. Pagamento de Fornecedores: Transferir fundos para pagamento de fornecedores ou prestadores de serviço.
2. Retirada de Lucros: Realizar a retirada de lucros para os sócios ou proprietários do negócio.
3. Transferência Entre Contas: Mover fundos entre diferentes contas da mesma empresa.
4. Pagamentos Recorrentes: Configurar saques programados para pagamentos recorrentes.

Melhores Práticas

1. Verificar Saldo: Sempre verifique o saldo disponível antes de solicitar um saque.
2. Confirmar Valores: Confirme o valor correto em centavos para evitar erros.
3. Acompanhar Status: Utilize o endpoint Consultar Saque para acompanhar o status do saque após sua criação.
4. Tratamento de Erros: Implemente tratamento adequado para todas as possíveis respostas de erro.
5. Registro de Histórico: Mantenha um registro de todos os saques realizados para fins de auditoria.

Integração com Outros Endpoints

• Consultar Saldo: Use o endpoint Consultar Saldo para verificar o saldo disponível antes de solicitar um saque.
• Consultar Saque: Use o endpoint Consultar Saque para acompanhar o status do saque após sua criação.
• Listar Saques: Use o endpoint Listar Saques para obter o histórico completo de saques.