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
limitestá sempre presente na resposta e vemnullquandolimitControléNO_LIMIT.- Os valores de
limitestão em reais, com até 2 casas decimais, e se referem ao período em curso delimitControl(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.mccGroupsvazio 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—idfora do formato aceito, como um valor com mais de 120 caracteres (fieldpath.id). Use oidexatamente 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 escopogetCreditCard(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 orequestId.
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"
import requests
import json
url = "https://api-sandbox.contasimples.com/credit-cards/v1/cards/01JVWSWPWNAW27E802541SJ7P1"
headers = {
"Content-Type": "application/json",
"Signature-Input": "example_string",
"Signature": "example_string",
"Authorization": "Bearer YOUR_API_TOKEN"
}
response = requests.get(url, headers=headers)
print(response.json())
const response = await fetch("https://api-sandbox.contasimples.com/credit-cards/v1/cards/01JVWSWPWNAW27E802541SJ7P1", {
method: "GET",
headers: {
"Content-Type": "application/json",
"Signature-Input": "example_string",
"Signature": "example_string",
"Authorization": "Bearer YOUR_API_TOKEN"
}
});
const data = await response.json();
console.log(data);
package main
import (
"fmt"
"net/http"
)
func main() {
req, err := http.NewRequest("GET", "https://api-sandbox.contasimples.com/credit-cards/v1/cards/01JVWSWPWNAW27E802541SJ7P1", nil)
if err != nil {
panic(err)
}
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Signature-Input", "example_string")
req.Header.Set("Signature", "example_string")
req.Header.Set("Authorization", "Bearer YOUR_API_TOKEN")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
fmt.Println("Response Status:", resp.Status)
}
require 'net/http'
require 'json'
uri = URI('https://api-sandbox.contasimples.com/credit-cards/v1/cards/01JVWSWPWNAW27E802541SJ7P1')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri)
request['Content-Type'] = 'application/json'
request['Signature-Input'] = 'example_string'
request['Signature'] = 'example_string'
request['Authorization'] = 'Bearer YOUR_API_TOKEN'
response = http.request(request)
puts response.body
{
"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"
]
}
{
"id": "01JVX2B7K3M9Q4R8T1W5Y6Z0AC",
"maskedNumber": "**** **** **** 1307",
"cardHolderName": "CARLOS LIMA",
"responsible": {
"email": "carlos.lima@empresa-exemplo.com.br"
},
"type": "PHYSICAL",
"createdAt": "2025-11-18T12:00:00.000Z",
"updatedAt": "2026-08-21T16:42:00.000Z",
"status": "ACTIVATED",
"expirationDate": "2030-11-30T23:59:59.000Z",
"name": "Viagens Comercial",
"costCenter": {
"id": "3c59dc04-8e1f-4a6b-b2d7-5f0e9a8c1d24"
},
"formattedExpirationDate": "11/2030",
"purpose": "FREE",
"limit": null,
"limitControl": "NO_LIMIT",
"mccGroups": []
}
{
"code": "invalid-card-id",
"message": "Card id is not valid",
"errors": [
{
"field": "path.id",
"message": "id must be shorter than or equal to 120 characters"
}
],
"requestId": "123e4567-e89b-12d3-a456-426614174000"
}
{
"code": "unauthorized",
"message": "Authentication failed. Check the API token and the request signature",
"requestId": "123e4567-e89b-12d3-a456-426614174000"
}
{
"code": "unauthorized",
"message": "Authentication failed. Check the API token and the request signature",
"details": {
"reason": "SIGNATURE_REQUIRED"
},
"requestId": "123e4567-e89b-12d3-a456-426614174000"
}
{
"code": "unauthorized",
"message": "Authentication failed. Check the API token and the request signature",
"details": {
"reason": "INVALID_SIGNATURE"
},
"requestId": "123e4567-e89b-12d3-a456-426614174000"
}
{
"code": "caller-not-authorized",
"message": "The request is not allowed for the current credentials",
"details": {
"requiredScope": "getCreditCard"
},
"requestId": "123e4567-e89b-12d3-a456-426614174000"
}
{
"code": "card-not-found",
"message": "Card not found",
"requestId": "123e4567-e89b-12d3-a456-426614174000"
}
{
"code": "internal-exception",
"message": "An unexpected error occurred on the server",
"requestId": "123e4567-e89b-12d3-a456-426614174000"
}
/credit-cards/v1/cards/{id}Target server for requests. Edit to use your own host.
Token Bearer obtido via OAuth 2.0 Client Credentials. Formato: Bearer TOKEN
Bearer TOKENIdentificador do cartão — use o valor do campo id retornado em GET /credit-cards/v1/cards (ex.: 01JVWSWPWNAW27E802541SJ7P1).
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.
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
Bearer token. Token Bearer obtido via OAuth 2.0 Client Credentials. Formato: Bearer TOKEN
Path Parameters
Identificador do cartão — use o valor do campo id retornado em GET /credit-cards/v1/cards (ex.: 01JVWSWPWNAW27E802541SJ7P1).
01JVWSWPWNAW27E802541SJ7P1Headers
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.
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
Identificador único do cartão.
Número do cartão mascarado (ex: **** **** **** 1234).
Nome do portador do cartão.
Dados do responsável pelo cartão. Sai vazio quando o cartão não tem e-mail de responsável.
Tipo do cartão.
PHYSICALVIRTUALData de criação do cartão (ISO 8601).
Data da última atualização do cartão (ISO 8601).
Status atual do cartão.
ACTIVATEDBLOCKEDCANCELLEDINACTIVATEDData de expiração do cartão (ISO 8601).
Nome atribuído ao cartão.
Centro de custo associado ao cartão.
Data de expiração formatada (MM/YYYY).
Finalidade do cartão.
FREETRIPADSSOFTWAREAERIALHOTELLimite do período em curso. Sempre presente; vem null quando limitControl é NO_LIMIT.
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).
NO_LIMITDAILYWEEKLYMONTHLYGrupos 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.
TRANSPORTATIONFOODTRIPOFFICEADSSOFTWAREAERIALHOTELAUTOMOTIVEOTHER