Consultar uma carteira

Este endpoint permite recuperar detalhes completos de uma carteira específica através do seu ID único.

Visão Geral

Este endpoint permite recuperar detalhes completos de uma carteira específica através do seu ID único.

Precauções

Certifique-se de utilizar um ID de carteira válido no formato wall_XXXXXXXXX.
Verifique se você tem permissão para acessar a carteira requisitada.
A carteira deve pertencer ao vendedor autenticado ou a um vendedor para o qual você tenha acesso.

Descrição

A consulta de carteira é útil para obter todos os detalhes de uma carteira específica, incluindo informações bancárias, status, e dados de associação.

Requisição

GET /v1/wallets/{walletId}

Parâmetros de Caminho

Parâmetro	Tipo	Obrigatório	Descrição	Exemplo
`walletId`	string	Sim	Identificador único da carteira	`"wall_01hqzvabc"`

Resposta

Sucesso (200 OK)

{
  "id": "wall_01hqzvabc",
  "name": "Minha Carteira Principal",
  "holderName": "João Santos",
  "bankName": null,
  "bankCode": "260",
  "routingNumber": "0001",
  "accountNumber": "11111111-5",
  "accountType": "checking",
  "pixKey": null,
  "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."
    }
  }
}

Atributos da Resposta

Atributo	Tipo	Descrição
`id`	string	`wall_*`
`name`	string	Nome descritivo
`holderName`	string	Titular (derivado da empresa)
`bankName`	string \| null	Nome do banco (atualmente sempre `null`)
`bankCode`	string \| null	Código do banco
`routingNumber`	string \| null	Agência
`accountNumber`	string \| null	Conta
`accountType`	string	Tipo de conta — sempre `checking`
`pixKey`	string \| null	Chave PIX (atualmente sempre `null`)
`primary`	boolean	Principal
`enabled`	boolean	Ativa
`createdAt` / `updatedAt`	string	Timestamps
`merchant`	object	Merchant
`_links`	object	HATEOAS

Melhores Práticas

Armazene o ID da carteira quando ela é criada para facilitar consultas futuras.
Implemente cache para resultados frequentemente acessados, considerando um TTL (Time To Live) apropriado.
Verifique se a resposta retorna o atributo primary para determinar se esta é a carteira principal do vendedor.
Valide o formato do ID da carteira antes de fazer a requisição para evitar erros de validação.
Implemente tratamento de erros adequado para lidar com casos onde a carteira não é encontrada.
Armazene os IDs das carteiras em seu sistema para referência futura.
Utilize este endpoint para verificar o status atual da carteira antes de realizar operações com ela.
Implemente cache para informações de carteiras frequentemente acessadas.
Trate adequadamente os erros para fornecer feedback claro aos usuários.
Não armazene informações sensíveis da carteira em logs ou bancos de dados desprotegidos.
Verifique se a carteira é a principal (primary: true) antes de realizar operações que dependam da carteira padrão.

Consultar uma carteira

On this page