Consultar um cartão

Visão Geral

Este endpoint permite consultar informações detalhadas sobre um cartão específico, identificado pelo seu ID único. Os dados retornados incluem informações parciais do cartão (por segurança), detalhes sobre o estado do cartão, e metadados associados.

Precauções

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

• Segurança: Apenas dados parciais do cartão são retornados (primeiros e últimos dígitos), nunca o número completo.
• Autenticação: Certifique-se de que o usuário tem permissão para acessar os dados do cartão especificado.
• ID do Cartão: O ID do cartão deve ser válido e existir no sistema.

Descrição

O endpoint Consultar Cartão permite obter todas as informações disponíveis sobre um cartão específico cadastrado no sistema, utilizando seu identificador único.

Requisição

GET /v1/cards/{cardId}

Parâmetros da Requisição

Resposta - 200 OK

Se a requisição for bem-sucedida, um objeto JSON com detalhes do cartão solicitado é retornado.

Exemplo de Resposta

{
  "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,
  "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/cards/card_01hqzvabc",
      "method": "GET",
      "description": "Read a 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."
    }
  }
}

Atributos da Resposta

O recurso de cartão não retorna metadata. As flags usam os nomes acima (sem prefixo is).

Respostas de Erro

Todas as respostas de erro seguem o envelope { "error": { status, statusCode, category, code, message, resource, details?, params? } }.

400 Bad Request - Formato de ID Inválido

Retornado quando o cardId não tem o prefixo card_.

{
  "error": {
    "status": "Bad Request",
    "statusCode": 400,
    "category": "validation",
    "code": "validation",
    "message": "Validation errors occurred.",
    "resource": "card",
    "params": [
      { "cardId": "must be a valid card_ id" }
    ]
  }
}

404 Not Found - Cartão não encontrado

{
  "error": {
    "status": "Not Found",
    "statusCode": 404,
    "category": "client",
    "code": "cardIdNotFound",
    "message": "Card ID not found.",
    "resource": "card",
    "details": "The card ID was not found. Please check the card ID and try again."
  }
}

409 Conflict - Cartão expirado

Retornado quando o cartão existe mas já está marcado como expirado.

{
  "error": {
    "status": "Conflict",
    "statusCode": 409,
    "category": "client",
    "code": "cardExpired",
    "message": "Card expired",
    "resource": "card",
    "details": "The provided card has expired. Please use a valid card."
  }
}

Casos de Uso

1. Exibição de Detalhes do Cartão: Mostrar informações do cartão na interface do cliente
2. Verificação de Status: Verificar se um cartão está ativo, válido ou marcado como primário
3. Confirmação Antes do Pagamento: Exibir informações mascaradas do cartão para confirmação antes de efetuar uma transação
4. Validação Antes de Operações: Verificar a validade e o estado do cartão antes de operações críticas

Melhores Práticas

1. Caching Limitado: Implemente cache com tempo de expiração curto para reduzir chamadas repetidas ao API
2. Exibição Segura: Sempre exiba apenas informações mascaradas dos cartões na interface do usuário
3. Verificações Regulares: Verifique periodicamente a validade dos cartões armazenados para notificar clientes sobre cartões prestes a expirar
4. Tratamento de Erros: Implemente tratamento adequado para os diferentes cenários de erro
5. Verificação de Permissões: Confirme que o usuário atual tem permissão para acessar as informações do cartão solicitado

Integração com Outros Endpoints

• Use Listar Cartões para obter todos os cartões de um cliente
• Cartões são imutáveis: para alterar dados, exclua o cartão e cadastre um novo
• Use Excluir Cartão para remover um cartão que não será mais utilizado