Listar carteiras

Liste as carteiras (contas bancárias) cadastradas na sua conta para recebimento e saque, com paginação, ordenação e filtros por ID ou por data. Use esta operação para montar telas de seleção de conta, conferir qual carteira é a principal ou auditar as contas disponíveis antes de criar um saque.

GET /v1/wallets

Como funciona

Uma carteira representa uma conta bancária vinculada ao seu negócio (lojista). É para ela que o saldo disponível é enviado quando você solicita um saque (withdrawal). A listagem devolve as carteiras da conta autenticada pela sua SelectKey — você não consulta carteiras de terceiros.

A resposta é paginada por offset: você pede uma "fatia" dos resultados informando offset (quantos itens pular) e limit (quantos trazer). O servidor devolve essa fatia dentro de data, junto com metadados (total, hasMore, page) que dizem se há mais páginas. Os campos de paginação seguem o padrão geral descrito em Paginação.

Existem duas formas de listar carteiras, com formatos de resposta diferentes:

Quando usar

• Use para listar e paginar as carteiras da conta, encontrar a carteira primary (principal) ou auditar contas antes de um saque.
• Não use para obter o detalhe completo de uma carteira (com accountType): para isso, consulte GET /v1/wallets/{walletId}.
• Para criar uma carteira, veja POST /v1/wallets; para remover, veja DELETE /v1/wallets/{walletId}.

Requisição

Headers

Esta é uma operação de leitura (GET), portanto não tem corpo e não usa Content-Type nem X-Idempotency-Key. Nunca use Authorization: Bearer/Basic — a autenticação é sempre pelo header SelectKey.

Parâmetros de consulta (query)

Todos são opcionais e valem para GET /v1/wallets e GET /v1/wallets/listall.

Exemplo de requisição

Listar as 20 carteiras mais recentes, primeira página:

curl -G https://api.selectwin.io/v1/wallets \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ" \
  --data-urlencode "limit=20" \
  --data-urlencode "offset=0" \
  --data-urlencode "sort=descending"

Filtrar por uma carteira específica:

curl -G https://api.selectwin.io/v1/wallets \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ" \
  --data-urlencode "id=wall_01hqzvabc"

Trazer todas de uma vez (array simples):

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

Resposta

GET /v1/wallets — 200 OK (paginado)

{
  "offset": 0,
  "limit": 20,
  "total": 2,
  "hasMore": false,
  "page": {
    "current": 1,
    "total": 1,
    "offset": { "first": 0, "prev": null, "next": null, "last": 0 }
  },
  "data": [
    {
      "id": "wall_01hqzvabc",
      "name": "Conta principal",
      "bankName": "Nubank",
      "bankCode": "260",
      "holderName": "João Santos",
      "routingNumber": "0001",
      "accountNumber": "12345678",
      "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",
      "method": "GET",
      "description": "List all wallets."
    },
    "create": {
      "href": "https://api.selectwin.io/v1/wallets",
      "method": "POST",
      "description": "Create a new wallet."
    }
  }
}

Campos do envelope paginado

Campos de cada carteira em data[]

GET /v1/wallets/listall — 200 OK (array)

Retorna diretamente um array de carteiras, sem envelope de paginação, merchant ou _links:

[
  {
    "id": "wall_01hqzvabc",
    "name": "Conta principal",
    "bankName": "Nubank",
    "bankCode": "260",
    "holderName": "João Santos",
    "routingNumber": "0001",
    "accountNumber": "12345678",
    "primary": true,
    "enabled": true,
    "updatedAt": "2026-04-12T17:56:33.000Z",
    "createdAt": "2026-04-12T17:56:33.000Z"
  }
]

Os campos de cada item são os mesmos da projeção data[] acima (sem accountType).

Erros

Verifique sempre o error.code (estável, legível por máquina), não a message. Veja Tratamento de Erros e o Catálogo de Códigos de Erro.

Boas práticas

1. Pagine sempre que hasMore for true. Avance somando limit ao offset (ou use page.offset.next) até hasMore virar false. Não presuma que a primeira página traz tudo.
2. Escolha o endpoint certo. Use GET /v1/wallets/listall para preencher um seletor pequeno de uma vez; use GET /v1/wallets quando precisar de paginação e metadados.
3. Trate data[] como projeção leve. Se precisar de accountType, busque o detalhe com GET /v1/wallets/{walletId} — não conte com esse campo na listagem.
4. Para achar a carteira principal, filtre o resultado pelo campo primary === true em vez de assumir que é o primeiro item da lista.
5. Considere enabled antes de oferecer uma carteira para saque: uma carteira desabilitada não deve ser usada como destino.
6. Trate os IDs como opacos. Armazene a string id inteira; não faça parsing nem confie no prefixo para lógica — veja Convenções.
7. Não fique fazendo polling para detectar mudanças nas carteiras; reaja a webhooks quando aplicável — veja Proibição de Polling.

Veja também

• Visão geral de Carteiras
• Criar carteira (POST /v1/wallets)
• Consultar carteira (GET /v1/wallets/{walletId})
• Excluir carteira (DELETE /v1/wallets/{walletId})
• Paginação · Convenções · Autenticação