Consultar um cartão

Recupera os dados de um cartão tokenizado a partir do seu identificador. A resposta traz informações seguras (apenas dígitos parciais, nunca o número completo nem o CVV) e o estado atual do cartão — ideal para exibir o meio de pagamento salvo de um cliente ou conferir se ele ainda está válido antes de cobrar.

GET /v1/cards/{cardId}

Como funciona

Quando você cria um cartão na Selectwin (veja Criar cartão), os dados sensíveis (número completo, o chamado PAN, e o código de segurança) não ficam armazenados — eles são substituídos por um token, uma referência opaca representada pelo id do cartão (ex.: card_01hqzvabc). "Tokenizar" é justamente esse processo: trocar o dado sensível por uma referência segura que você pode guardar e reutilizar.

O endpoint de leitura recebe esse id e devolve a representação atual do cartão: os dígitos parciais para identificação visual, a bandeira detectada e um conjunto de flags de estado (ativo, válido, verificado, associado e principal). Por baixo, é uma operação somente leitura e idempotente — chamá-la quantas vezes quiser não altera nada no servidor nem dispara cobranças.

Cartões são imutáveis: não existe endpoint para editar os dados de um cartão já cadastrado. Para "alterar" um cartão (por exemplo, atualizar a validade), você exclui o antigo e cria um novo. Por isso, a leitura é a forma canônica de obter o estado mais recente — não confie em cópias antigas guardadas no seu lado.

As flags de estado

Quando usar (e quando não usar)

Use a consulta individual quando você já tem o id do cartão e precisa do estado completo e atual:

• Exibir o meio de pagamento salvo na tela do cliente (bandeira + últimos 4 dígitos).
• Conferir, antes de cobrar, se o cartão está active e valid.
• Confirmar para o usuário qual cartão será usado em um pagamento.

Quando não usar:

• Para descobrir todos os cartões de um cliente, use Listar cartões com o filtro holderid. Não tente "adivinhar" IDs.
• A leitura não valida fundos nem autoriza pagamentos — isso acontece no momento da transação. As flags refletem o estado do token, não a disponibilidade de crédito no banco emissor.

Requisição

Headers

Esta é uma operação de leitura, então não há corpo nem necessidade de Content-Type ou X-Idempotency-Key. As demais convenções (camelCase, dinheiro em centavos, datas ISO 8601 UTC, IDs opacos) seguem o padrão geral — veja Convenções.

Parâmetros de caminho

Exemplo

curl https://api.selectwin.io/v1/cards/card_01hqzvabc \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ"

Resposta

Em caso de sucesso, retorna 200 OK com o objeto do cartão.

{
  "id": "card_01hqzvabc",
  "holderName": "JOÃO SILVA",
  "brand": "visa",
  "firstDigits": "411111",
  "lastDigits": "1111",
  "expirationMonth": "12",
  "expirationYear": "2025",
  "primary": null,
  "active": true,
  "valid": true,
  "verified": true,
  "associated": true,
  "updatedAt": "2026-04-12T17:56:33.000Z",
  "createdAt": "2026-04-12T17:56:33.000Z",
  "metadata": null,
  "merchant": {
    "name": "Seller Name",
    "merchantId": "bus_1234567890",
    "isSubAccount": false
  },
  "_links": {
    "self":   { "href": "https://api.selectwin.io/v1/cards/card_01hqzvabc", "method": "GET",    "description": "Read a card." },
    "create": { "href": "https://api.selectwin.io/v1/cards",                "method": "POST",   "description": "Create a new card." },
    "update": { "href": "https://api.selectwin.io/v1/cards/card_01hqzvabc", "method": "PUT",    "description": "Update the card." },
    "delete": { "href": "https://api.selectwin.io/v1/cards/card_01hqzvabc", "method": "DELETE", "description": "Delete the card." },
    "list":   { "href": "https://api.selectwin.io/v1/cards",                "method": "GET",    "description": "List all cards." }
  }
}

Campos da resposta

Erros

Em caso de falha, a API retorna o envelope padrão com um error.code estável — trate sempre pelo code, nunca pela message. Estrutura completa em Tratamento de Erros.

Exemplo de erro para um ID malformado:

{
  "error": {
    "code": "cardIdIsInvalid",
    "statusCode": 400,
    "category": "validation",
    "message": "Card ID is invalid"
  }
}

Boas práticas

• Leia sob demanda, não em loop. Para reagir a mudanças (ex.: cartão expirado), prefira webhooks (card.expired, card.updated) a ficar consultando — a API desencoraja polling. Veja Proibição de polling.
• Cache curto. Se cachear a resposta para reduzir chamadas, use TTL baixo e invalide ao receber card.updated ou card.deleted.
• Exiba só o que é seguro. Mostre bandeira + lastDigits ao usuário; nunca exponha mais do que a API devolve.
• Cheque o estado antes de cobrar. Confirme active e valid (e, se preciso, alerte sobre expirationMonth/expirationYear próximos do vencimento) antes de criar uma transação com o cartão.
• Trate 404 como fluxo normal. Um cartão pode ter sido excluído pelo cliente entre uma tela e outra; trate cardNotFound de forma graciosa, sem quebrar a experiência.
• Não construa nem faça parsing de IDs. Guarde o id inteiro retornado na criação e reutilize-o; o prefixo card_ é só conveniência de leitura.

Veja também

• Visão geral de Cartões — modelo do objeto, ciclo de vida e segurança PCI.
• Criar cartão — cadastrar e tokenizar um novo cartão.
• Listar cartões — obter os cartões de um cliente com filtros e paginação.
• Excluir cartão — remover um cartão tokenizado.
• Convenções e Códigos de Erro.