CartõesConsultar Cartão por ID

Consultar Cartão por ID

Use este endpoint para ver quanto ainda resta do limite de um cartão no período e em quais grupos de MCC ele pode ser usado, por exemplo antes de aprovar uma despesa ou para exibir o cartão na sua plataforma. A resposta traz os mesmos dados de Listar Cartões e, além deles, o limite do período, o período de controle do limite e os grupos de MCC do cartão. O MCC (Merchant Category Code) é o código que identifica a categoria do estabelecimento, e os grupos de MCC são as categorias de gasto definidas para o cartão no Internet Banking.

Antes de chamar

  • O escopo desta rota é sensível: só pode ser concedido a uma credencial com chave pública, e toda chamada dessa credencial precisa ser assinada. Veja Quando a assinatura é exigida.

Como ler a resposta

  • limit está sempre presente na resposta e vem null quando limitControl é NO_LIMIT.
  • Os valores de limit estão em reais, com até 2 casas decimais, e se referem ao período em curso de limitControl (dia, semana ou mês).
  • limit.available é o que resta do limite do cartão, e não a garantia de que a próxima compra será aprovada: a aprovação também depende do status do cartão e dos grupos de MCC.
  • mccGroups vazio quer dizer que o cartão não tem restrição por grupo e pode ser usado em qualquer categoria de estabelecimento.
  • purpose é a finalidade do cartão e não restringe onde ele é usado; quem restringe é mccGroups.

Erros

Os erros desta rota identificam o motivo por code em texto (ex.: card-not-found). Listar Cartões, Bloquear Cartão e Desbloquear Cartão usam outro formato, com o status HTTP como número em code: se a sua integração trata os erros de cartão num lugar só, separe por rota.

  • 400 invalid-card-id — id fora do formato aceito, como um valor com mais de 120 caracteres (field path.id). Use o id exatamente como veio de Listar Cartões.
  • 401 unauthorized — token ausente, inválido ou expirado, ou assinatura ausente ou inválida (details.reason).
  • 403 caller-not-authorized — a credencial não tem o escopo getCreditCard (details.requiredScope). Os escopos de uma credencial não podem ser editados: crie outra credencial com esse escopo.
  • 404 card-not-found — cartão inexistente ou de outra empresa.
  • 500 internal-exception — erro interno; repetir a consulta é seguro. Se persistir, acione o suporte com o horário e o requestId.
curl -X GET "https://api-sandbox.contasimples.com/credit-cards/v1/cards/01JVWSWPWNAW27E802541SJ7P1" \
  -H "Content-Type: application/json" \
  -H "Signature-Input: example_string" \
  -H "Signature: example_string" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
{
  "id": "01JVWSWPWNAW27E802541SJ7P1",
  "maskedNumber": "**** **** **** 4821",
  "cardHolderName": "ANA SOUZA",
  "responsible": {
    "email": "ana.souza@empresa-exemplo.com.br"
  },
  "type": "VIRTUAL",
  "createdAt": "2026-03-10T14:30:00.000Z",
  "updatedAt": "2026-10-02T09:15:00.000Z",
  "status": "ACTIVATED",
  "expirationDate": "2031-03-31T23:59:59.000Z",
  "name": "Marketing Ads",
  "costCenter": {
    "id": "8f14e45f-ea0b-4b39-9c3e-2f6a1d7c5b90"
  },
  "formattedExpirationDate": "03/2031",
  "purpose": "FREE",
  "limit": {
    "total": 5000,
    "available": 3250.4,
    "consumed": 1749.6
  },
  "limitControl": "MONTHLY",
  "mccGroups": [
    "ADS",
    "SOFTWARE"
  ]
}
GET
/credit-cards/v1/cards/{id}
GET
Base URLstring

Target server for requests. Edit to use your own host.

Bearer Token
Bearer Tokenstring
Required

Token Bearer obtido via OAuth 2.0 Client Credentials. Formato: Bearer TOKEN

Token Bearer obtido via OAuth 2.0 Client Credentials. Formato: Bearer TOKEN
path
idstring
Required

Identificador do cartão — use o valor do campo id retornado em GET /credit-cards/v1/cards (ex.: 01JVWSWPWNAW27E802541SJ7P1).

Max length: 120
header
Signature-Inputstring

O que foi assinado e os parâmetros da assinatura, no formato da RFC 9421. Uma credencial com chave pública precisa enviar este header em todas as chamadas, inclusive as de leitura, ou a requisição é recusada com 401. A assinatura cobre os componentes @method, @path e @query, e também content-digest quando houver corpo. created e alg são obrigatórios, e o created vale por 300 segundos. O formato completo, com exemplos, está em Assinatura de Requisições.

header
Signaturestring

A assinatura da base definida pela RFC 9421, em base64, entre : e com o mesmo rótulo usado no Signature-Input, por exemplo sig=:SGVsbG8gd29ybGQ=:. Vai sempre junto com o Signature-Input.

Request Preview
Response

Response will appear here after sending the request

Authentication

header
Authorizationstring
Required

Bearer token. Token Bearer obtido via OAuth 2.0 Client Credentials. Formato: Bearer TOKEN

Path Parameters

idstring
Required

Identificador do cartão — use o valor do campo id retornado em GET /credit-cards/v1/cards (ex.: 01JVWSWPWNAW27E802541SJ7P1).

Example:
01JVWSWPWNAW27E802541SJ7P1

Headers

Signature-Inputstring

O que foi assinado e os parâmetros da assinatura, no formato da RFC 9421. Uma credencial com chave pública precisa enviar este header em todas as chamadas, inclusive as de leitura, ou a requisição é recusada com 401. A assinatura cobre os componentes @method, @path e @query, e também content-digest quando houver corpo. created e alg são obrigatórios, e o created vale por 300 segundos. O formato completo, com exemplos, está em Assinatura de Requisições.

Signaturestring

A assinatura da base definida pela RFC 9421, em base64, entre : e com o mesmo rótulo usado no Signature-Input, por exemplo sig=:SGVsbG8gd29ybGQ=:. Vai sempre junto com o Signature-Input.

Responses

idstring
Required

Identificador único do cartão.

maskedNumberstring
Required

Número do cartão mascarado (ex: **** **** **** 1234).

cardHolderNamestring
Required

Nome do portador do cartão.

responsibleobject
Required

Dados do responsável pelo cartão. Sai vazio quando o cartão não tem e-mail de responsável.

typestring
Required

Tipo do cartão.

Allowed values:PHYSICALVIRTUAL
createdAtstring
Required

Data de criação do cartão (ISO 8601).

updatedAtstring
Required

Data da última atualização do cartão (ISO 8601).

statusstring
Required

Status atual do cartão.

Allowed values:ACTIVATEDBLOCKEDCANCELLEDINACTIVATED
expirationDatestring
Required

Data de expiração do cartão (ISO 8601).

namestring
Required

Nome atribuído ao cartão.

costCenterobject
Required

Centro de custo associado ao cartão.

formattedExpirationDatestring
Required

Data de expiração formatada (MM/YYYY).

purposestring
Required

Finalidade do cartão.

Allowed values:FREETRIPADSSOFTWAREAERIALHOTEL
limitobject
Required

Limite do período em curso. Sempre presente; vem null quando limitControl é NO_LIMIT.

limitControlstring
Required

Período de controle do limite: DAILY (dia), WEEKLY (semana), MONTHLY (mês) ou NO_LIMIT (o cartão não tem limite próprio).

Allowed values:NO_LIMITDAILYWEEKLYMONTHLY
mccGroupsstring[]
Required

Grupos de MCC em que o cartão pode ser usado. Vem vazio quando o cartão não tem restrição por grupo: nesse caso, ele aceita compras em qualquer categoria de estabelecimento.

No Internet Banking, os grupos aparecem como categorias de gasto:

  • FOOD (Alimentação): supermercados, restaurantes e padarias.
  • ADS (Anúncio): ferramentas de anúncio, e-commerce e plataformas de marketing.
  • OFFICE (Escritório): equipamentos, utensílios e papelaria.
  • AUTOMOTIVE (Gastos automotivos): postos de combustível, oficinas, autopeças e estacionamentos.
  • HOTEL (Hospedagem e transporte): hotéis, pousadas, pedágio e transporte em geral.
  • TRANSPORTATION (Mobilidade): táxi, ônibus e aplicativos de transporte.
  • SOFTWARE (Software): ferramentas, serviços digitais e assinaturas.
  • TRIP (Viagem): passagem, hospedagem e translado.

AERIAL (passagens aéreas) é o grupo dos VCN de reserva aérea e não aparece no Internet Banking.

OTHER é um grupo liberado sem categoria correspondente no Internet Banking. Vem uma vez só, mesmo que o cartão tenha mais de um grupo assim, e não indica ausência de restrição: um cartão só com OTHER não aceita compras em qualquer categoria.

Allowed values:TRANSPORTATIONFOODTRIPOFFICEADSSOFTWAREAERIALHOTELAUTOMOTIVEOTHER