Listar cartões

Recupera a lista de cartões tokenizados da sua conta, em formato paginado, com filtros por titular (cliente), por ID de cartão e por intervalo de datas. Use esta rota para montar telas de "meus cartões", selecionar um método de pagamento no checkout ou auditar os cartões associados a um cliente.

GET /v1/cards

Como funciona

Um cartão na Selectwin nunca guarda o número completo (o PAN). No momento do cadastro ele é tokenizado — convertido em um identificador opaco (card_...) que representa o cartão para cobranças futuras, sem expor os dados sensíveis. Veja Segurança e PCI e Criar cartão para entender esse fluxo.

Esta rota faz uma leitura paginada desses tokens:

• O servidor retorna um envelope de paginação (offset, limit, total, hasMore, page) com o array data contendo os cartões.
• Cada item de data é uma projeção leve do cartão: apenas os campos seguros (bandeira, primeiros e últimos dígitos, validade, flags de estado). O número completo nunca é retornado. Para o objeto individual, use Consultar cartão.
• A resposta segue o padrão HATEOAS: o objeto _links traz as próximas ações disponíveis (aqui, self e create). Veja Recursos.

A operação é somente leitura (GET): não altera nada, não tem efeitos colaterais e não precisa de chave de idempotência.

Quando usar (e quando não usar)

Use esta rota quando precisar de um conjunto de cartões:

• Exibir todos os cartões de um cliente (filtre por holderid).
• Deixar o cliente escolher um cartão salvo no checkout.
• Construir um painel administrativo ou um relatório de cartões cadastrados.

Não use quando:

• Você já tem o card_... e quer um único cartão com todos os campos — use Consultar cartão, que evita paginar uma lista inteira.
• Você quer verificar a existência de um cartão específico — embora exista o filtro id, consultar diretamente pelo ID (GET /v1/cards/{cardId}) é mais simples e devolve 404 quando não existe.

Requisição

Headers

Esta rota não envia corpo, então não precisa de Content-Type. Autenticação é sempre pelo header SelectKey — nunca Authorization: Bearer ou Basic.

Parâmetros de query

Todos opcionais. Sem nenhum filtro, a rota devolve a primeira página de todos os cartões da conta.

Datas em ISO 8601 UTC (sufixo Z), ex.: 2026-01-01T00:00:00Z. IDs são opacos — armazene a string inteira, não faça parsing. Veja Convenções e Paginação.

Exemplo curl

Listar os cartões de um cliente, do mais recente para o mais antigo, 25 por página:

curl -G 'https://api.selectwin.io/v1/cards' \
  -H 'SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ' \
  --data-urlencode 'holderid=cus_01hqzvabc' \
  --data-urlencode 'sort=descending' \
  --data-urlencode 'limit=25' \
  --data-urlencode 'offset=0'

Filtrar cartões cadastrados a partir de uma data:

curl -G 'https://api.selectwin.io/v1/cards' \
  -H 'SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ' \
  --data-urlencode 'daterangegte=2026-04-01T00:00:00Z'

Resposta

200 OK — um envelope paginado com o array data de cartões.

{
  "offset": 0,
  "limit": 25,
  "total": 2,
  "hasMore": false,
  "page": {
    "current": 1,
    "total": 1,
    "offset": { "first": 0, "prev": null, "next": null, "last": 0 }
  },
  "data": [
    {
      "id": "card_01hqzvabc",
      "holderName": "JOÃO SILVA",
      "brand": "visa",
      "firstDigits": "411111",
      "lastDigits": "1111",
      "expirationMonth": "12",
      "expirationYear": "2025",
      "isPrimary": true,
      "isActive": true,
      "isValid": true,
      "isVerified": true,
      "isAssociated": true,
      "createdAt": "2026-04-12T17:56:33.000Z",
      "updatedAt": "2026-04-12T17:56:33.000Z"
    },
    {
      "id": "card_02hqzvxyz",
      "holderName": "JOÃO SILVA",
      "brand": "mastercard",
      "firstDigits": "510000",
      "lastDigits": "5555",
      "expirationMonth": "06",
      "expirationYear": "2026",
      "isPrimary": false,
      "isActive": true,
      "isValid": true,
      "isVerified": true,
      "isAssociated": true,
      "createdAt": "2026-03-15T10:20:00.000Z",
      "updatedAt": "2026-03-15T10:20:00.000Z"
    }
  ],
  "merchant": {
    "name": "Seller Name",
    "merchantId": "bus_1234567890",
    "isSubAccount": false
  },
  "_links": {
    "self": {
      "href": "https://api.selectwin.io/v1/cards",
      "method": "GET",
      "description": "List all cards."
    },
    "create": {
      "href": "https://api.selectwin.io/v1/cards",
      "method": "POST",
      "description": "Create and tokenize a new card."
    }
  }
}

Campos de paginação

Campos de cada cartão em data[]

As flags de estado aparecem na lista no formato is* (isPrimary, isActive, isValid, isVerified, isAssociated). Na resposta de um cartão individual em Consultar cartão e em Criar cartão, as mesmas flags aparecem sem o prefixo is (primary, active, valid, verified, associated). Trate isso ao mapear os dois formatos.

Os blocos merchant (dados do recebedor) e _links (ações HATEOAS) acompanham o envelope. Em listas, _links traz apenas self e create; as ações por item (update, delete) aparecem na consulta individual.

Erros

A estrutura do envelope de erro está em Tratamento de Erros. Trate sempre pelo error.code, não pela message.

Exemplo de 400 por validação de parâmetro:

{
  "error": {
    "code": "invalidParameters",
    "statusCode": 400,
    "category": "validation",
    "message": "Validation errors occurred.",
    "params": [
      { "limit": "limit must be between 1 and 100" }
    ]
  }
}

Boas práticas

• Pagine de verdade. Não fixe limit=100 para "pegar tudo de uma vez". Itere usando offset/limit (ou os deslocamentos de page.offset.next) enquanto hasMore for true.
• Filtre no servidor, não no cliente. Para os cartões de um cliente, passe holderid em vez de baixar tudo e filtrar localmente — é mais rápido e barato.
• Destaque o cartão principal usando isPrimary ao montar uma lista de seleção no checkout.
• Trate a lista vazia (data: []) como um estado de UI legítimo (ex.: "Nenhum cartão cadastrado") e ofereça o caminho para Criar cartão.
• Exiba apenas dados mascarados. Use brand, firstDigits e lastDigits para mostrar algo como visa •••• 1111. O PAN completo nunca é retornado, por design.
• Não confie em isValid para o sucesso da cobrança. A flag reflete o estado do token; a aprovação final ocorre no momento da transação. Para recusas, veja Recusas de Pagamento.
• Cacheie com moderação. Um cache curto reduz chamadas repetidas, mas cartões podem ser criados/removidos a qualquer momento; invalide o cache após operações de escrita.
• Reaja por webhooks, não por polling. Para saber de mudanças nos cartões, prefira eventos a repetir esta listagem em loop. Veja Proibição de Polling.

Veja também

• Visão geral de Cartões — o recurso, o modelo do objeto e o ciclo de vida.
• Criar cartão — cadastrar e tokenizar um novo cartão.
• Consultar cartão — obter um único cartão com todos os campos.
• Excluir cartão — remover um cartão tokenizado.
• Paginação · Convenções · Catálogo de Códigos de Erro