Consultar um saque

Visão Geral

Este endpoint permite recuperar informações detalhadas sobre um saque específico, incluindo seu status atual, valor, método de transferência e datas de processamento. Isso é útil para acompanhar o status de saques em processamento, verificar detalhes de saques anteriores ou auditar movimentações financeiras.

Precauções

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

• Identificador do Saque: Certifique-se de utilizar o identificador correto do saque para obter informações precisas.
• Valores Monetários: Todos os valores monetários são retornados em centavos.
• Histórico: Os registros de saques são mantidos por tempo indeterminado para fins de auditoria, mesmo após concluídos ou cancelados.

Descrição

O endpoint de Consulta de Saque permite recuperar informações detalhadas sobre um saque através do seu identificador único. As informações retornadas incluem o valor do saque, status atual, método de transferência, taxas aplicadas (se houver) e datas relevantes, como criação, aprovação e pagamento.

Requisição

GET /v1/withdrawals/{withdrawalId}

Parâmetros do Caminho

Resposta - 200 OK

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

{
  "id": "cash_01hqzvabc",
  "walletId": "wall_01hqzvabc",
  "amount": 45000,
  "fee": 15,
  "status": "paid",
  "method": "bankTransfer",
  "currency": "BRL",
  "transferCode": "TRF987654",
  "paidAt": "2025-02-08T11:20:00.000Z",
  "approvedAt": "2025-02-07T18:00:00.000Z",
  "createdAt": "2025-02-07T00:12:33.000Z",
  "updatedAt": "2025-02-08T11:20:00.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

404 Not Found

Ocorre quando o saque informado não existe.

{
  "error": {
    "status": "Not Found",
    "statusCode": 404,
    "category": "client",
    "code": "withdrawalNotFound",
    "message": "Withdrawal not found."
  }
}

Casos de Uso

1. Acompanhamento de Status: Verificar se um saque pendente foi processado ou pago.
2. Histórico Financeiro: Acessar detalhes de saques anteriores para fins de registro.
3. Auditorias Financeiras: Obter informações detalhadas sobre saques específicos para reconciliação financeira.
4. Suporte ao Cliente: Verificar o status e detalhes de um saque quando um cliente questiona sobre o mesmo.

Melhores Práticas

1. Verificação Regular: Para saques pendentes, verifique regularmente o status usando este endpoint.
2. Tratamento de Erros: Implemente tratamento adequado para todos os possíveis códigos de erro.
3. Webhook de Notificações: Em vez de consultar frequentemente, considere usar webhooks para receber notificações automáticas de mudanças no status do saque.
4. Armazenamento em Cache: Evite consultas repetidas para saques que já estão em estados finais (paid, failed, canceled).

Integração com Outros Endpoints

• Criar Saque: Use o endpoint Criar Saque para iniciar um novo saque.
• Listar Saques: Use o endpoint Listar Saques para obter uma lista de todos os saques.
• Consultar Saldo: Use o endpoint Consultar Saldo para verificar o saldo disponível antes de solicitar um saque.