Listar cartões

Visão Geral

Este endpoint permite recuperar informações sobre todos os cartões armazenados para um cliente específico, facilitando a gestão de métodos de pagamento e oferecendo opções de filtragem e paginação para uma consulta eficiente.

Precauções

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

• Paginação: Este endpoint retorna resultados paginados. Utilize os parâmetros limit e offset para navegar entre as páginas.
• ID do Cliente: Para listar cartões de um cliente específico, forneça o ID do cliente como parâmetro.
• Dados Sensíveis: Por razões de segurança, os números completos dos cartões nunca são retornados, apenas os primeiros e últimos dígitos.

Descrição

O endpoint Listar Cartões permite consultar a lista de cartões cadastrados no sistema, com opções de filtragem por cliente e paginação.

Requisição

GET /v1/cards?limit=10&offset=0&sort=ascending&holderid=cus_123456789

Parâmetros da Requisição

Resposta - 200 OK

Se a requisição for bem-sucedida, um objeto JSON com a lista de cartões e informações de paginação é retornado.

Exemplo de Resposta

{
  "offset": 0,
  "limit": 10,
  "total": 2,
  "page": {
    "offset": { "first": 0, "prev": 0, "next": 0, "last": 0 },
    "current": 1,
    "total": 1
  },
  "hasMore": false,
  "data": [
    {
      "id": "card_01hqzvabc",
      "holderName": "João Silva",
      "brand": "Visa",
      "firstDigits": "411111",
      "lastDigits": "1111",
      "expirationMonth": "12",
      "expirationYear": "2025",
      "primary": true,
      "active": true,
      "valid": true,
      "verified": true,
      "associated": 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",
      "primary": false,
      "active": true,
      "valid": true,
      "verified": true,
      "associated": 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 a new card."
    }
  }
}

Atributos da Resposta

Atributos de Paginação

Os offsets em page.offset são sempre inteiros (nunca null).

Atributos de cada objeto de Cartão no array data

Cada item de data segue o mesmo objeto de cartão da leitura, porém sem os blocos merchant e _links (que aparecem apenas no nível da lista).

Respostas de Erro

404 Not Found - Cliente Não Encontrado

Retornado quando o filtro holderid aponta para um cliente inexistente.

{
  "error": {
    "status": "Not Found",
    "statusCode": 404,
    "category": "client",
    "code": "invalidCustomerId",
    "message": "Invalid customer ID.",
    "resource": "customer"
  }
}

Um holderid/id com formato de prefixo inválido (sem cus_/card_) retorna 400 Bad Request (validação de campo) com o array params.

Casos de Uso

1. Exibição em Perfil do Cliente: Mostrar todos os cartões disponíveis na área do cliente
2. Seleção de Método de Pagamento: Permitir que o cliente escolha entre seus cartões durante o checkout
3. Gestão de Cartões: Apresentar uma interface para que o cliente gerencie seus cartões
4. Dashboard Administrativo: Visualizar todos os cartões associados a um cliente específico

Melhores Práticas

1. Implementação de Paginação: Utilize os parâmetros offset e limit para implementar paginação eficiente
2. Cache de Resultados: Considere armazenar em cache os resultados por um curto período para melhorar o desempenho
3. Tratamento de Lista Vazia: Implemente um tratamento adequado para quando a lista de cartões estiver vazia
4. Exibição Segura: Sempre exiba apenas informações mascaradas dos cartões na interface do usuário
5. Filtro de Cartão Principal: Utilize o atributo primary para destacar o cartão principal do cliente

Integração com Outros Endpoints

• Use Consultar Cartão para obter detalhes completos de um cartão específico da lista
• Use Criar Cartão para adicionar um novo cartão quando a lista estiver vazia ou incompleta
• Use Excluir Cartão para remover cartões indesejados ou expirados da lista