Consultar uma carteira

Recupera todos os detalhes de uma carteira (conta bancária) cadastrada, a partir do seu identificador único. Use esta consulta para conferir os dados bancários antes de realizar um saque, verificar qual carteira é a principal ou exibir a conta de recebimento na sua interface.

GET /v1/wallets/{walletId}

Como funciona

Uma carteira representa uma conta bancária vinculada ao seu negócio (o merchant) e serve como destino dos seus saques. Este endpoint é uma operação de leitura (GET): ele não altera nada no servidor, é seguro de repetir quantas vezes quiser (idempotente por natureza) e devolve o objeto completo da carteira.

Diferente da listagem — que retorna projeções leves (versões resumidas de cada carteira) —, a consulta individual entrega o objeto completo, incluindo campos como accountType e o bloco merchant. Sempre que precisar de todos os detalhes de uma carteira específica, prefira este endpoint ao invés de filtrar a lista.

A resposta também traz um bloco _links (padrão HATEOAS — links que indicam as próximas ações possíveis a partir deste recurso). Em vez de montar URLs manualmente, você pode seguir _links.delete.href para apagar esta carteira ou _links.list.href para listar todas. Veja Convenções para os padrões transversais da API.

Quando usar (e quando não usar)

Use quando:

• Precisar exibir ou conferir os dados bancários completos de uma carteira específica (titular, agência, conta, tipo).
• Quiser confirmar se uma carteira está habilitada (enabled) ou se é a principal (primary) antes de iniciar um saque.
• Já tiver o walletId em mãos (por exemplo, salvo após a criação ou obtido na listagem).

Prefira alternativas quando:

• Quiser percorrer ou filtrar várias carteiras de uma vez — use Listar carteiras, que aceita paginação e filtros.
• Ainda não tiver o ID — você não pode consultar por número de conta; obtenha o walletId primeiro na listagem.

Requisição

Headers

Por ser uma leitura sem corpo, não é necessário enviar Content-Type nem X-Idempotency-Key. Nunca use Authorization: Bearer ou Basic — a autenticação é sempre via header SelectKey.

Parâmetros de caminho

Exemplo (curl)

curl https://api.selectwin.io/v1/wallets/wall_01hqzvabc \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ"

Resposta

Sucesso (200 OK)

{
  "id": "wall_01hqzvabc",
  "name": "Conta principal",
  "bankName": "Nubank",
  "bankCode": "260",
  "holderName": "João Santos",
  "routingNumber": "0001",
  "accountNumber": "12345678",
  "accountType": "checking",
  "primary": true,
  "enabled": true,
  "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/wallets/wall_01hqzvabc",
      "method": "GET",
      "description": "Read a wallet."
    },
    "create": {
      "href": "https://api.selectwin.io/v1/wallets",
      "method": "POST",
      "description": "Create a new wallet."
    },
    "delete": {
      "href": "https://api.selectwin.io/v1/wallets/wall_01hqzvabc",
      "method": "DELETE",
      "description": "Delete the wallet."
    },
    "list": {
      "href": "https://api.selectwin.io/v1/wallets",
      "method": "GET",
      "description": "List all wallets."
    }
  }
}

Campos da resposta

Erros

Em caso de falha, a resposta segue o envelope padrão de erro — identifique sempre pelo error.code (estável), nunca pela message (texto livre). Veja Tratamento de Erros e o Catálogo de Códigos de Erro.

{
  "error": {
    "code": "walletNotFound",
    "statusCode": 404,
    "category": "client",
    "message": "Wallet not found"
  }
}

Boas práticas

• Armazene o walletId retornado na criação para consultar a carteira depois sem precisar varrer a listagem.
• Trate o ID como opaco: não valide comprimento nem tente derivar dados dele; apenas verifique a presença antes de chamar a API para evitar walletIdIsInvalid.
• Confira enabled e primary antes de iniciar um saque: opere com a carteira certa e evite tentar sacar de uma conta inativa.
• Diferencie 404 de 403: walletNotFound significa que o ID não existe (ou não é seu); forbidden indica falta de permissão. Trate-os de formas distintas na sua aplicação.
• Não registre dados sensíveis (accountNumber, holderName) em logs ou bancos desprotegidos.
• Faça cache com cuidado: se cachear a resposta, use um TTL curto e invalide-o após qualquer alteração; campos como primary e enabled podem mudar.
• Siga os _links em vez de montar URLs à mão — assim seu código acompanha mudanças de rota automaticamente.

Veja também

• Visão geral de Carteiras — o modelo do objeto e o ciclo de vida.
• Criar carteira — cadastrar uma nova conta bancária.
• Listar carteiras — buscar e filtrar várias carteiras.
• Excluir carteira — remover uma carteira cadastrada.
• Convenções · Autenticação · Catálogo de Códigos de Erro