Get Card by ID
Use this endpoint to see how much of a card's limit is left in the period and which MCC groups the card can be used in, for example before approving an expense or to show the card on your platform. The response returns the same fields as List cards, plus the period limit, the limit control period, and the card's MCC groups. An MCC (Merchant Category Code) is the code that identifies a merchant's category, and MCC groups are the spending categories set for the card in Internet Banking.
Before you call
- This route's scope is sensitive: it can only be granted to a credential with a public key, and every call made with that credential must be signed. See When a signature is required.
How to read the response
limitis always present in the response and isnullwhenlimitControlisNO_LIMIT.limitvalues are in Brazilian reais (BRL), with up to 2 decimal places, and refer to the currentlimitControlperiod (day, week, or month).limit.availableis what's left of the card's limit, not a guarantee that the next purchase will be approved: approval also depends on the card status and its MCC groups.- An empty
mccGroupsmeans the card has no group restriction and can be used in any merchant category. purposeis the card's purpose and doesn't restrict where it can be used;mccGroupsdoes.
Errors
Errors on this route identify the reason with a text code (e.g. card-not-found). List cards, Block card, and Unblock card use a different format, with the HTTP status as a number in code: if your integration handles card errors in one place, branch by route.
400 invalid-card-id— anidin an invalid format, such as a value longer than 120 characters (fieldpath.id). Use theidexactly as returned by List cards.401 unauthorized— token missing, invalid, or expired, or signature missing or invalid (details.reason).403 caller-not-authorized— the credential doesn't have thegetCreditCardscope (details.requiredScope). A credential's scopes can't be edited: create another credential with this scope.404 card-not-found— the card doesn't exist or belongs to another company.500 internal-exception— internal error; retrying the request is safe. If it persists, contact support with the time and therequestId.
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.
Bearer token from OAuth 2.0 client credentials. Format: Bearer TOKEN
Bearer TOKENCard identifier — use the id field returned by GET /credit-cards/v1/cards (e.g. 01JVWSWPWNAW27E802541SJ7P1).
What was signed and the signature parameters, in the RFC 9421 format. A credential with a public key must send it on every call, reads included, or the request is refused with 401. The signature covers the @method, @path, and @query components, and also content-digest when there is a body. created and alg are required, and created is valid for 300 seconds. The full format, with examples, is in Request Signing.
The signature of the base defined by RFC 9421, in base64, between : and under the same label used in Signature-Input, for example sig=:SGVsbG8gd29ybGQ=:. It always goes together with Signature-Input.
Request Preview
Response
Response will appear here after sending the request
Authentication
Bearer token. Bearer token from OAuth 2.0 client credentials. Format: Bearer TOKEN
Path Parameters
Card identifier — use the id field returned by GET /credit-cards/v1/cards (e.g. 01JVWSWPWNAW27E802541SJ7P1).
01JVWSWPWNAW27E802541SJ7P1Headers
What was signed and the signature parameters, in the RFC 9421 format. A credential with a public key must send it on every call, reads included, or the request is refused with 401. The signature covers the @method, @path, and @query components, and also content-digest when there is a body. created and alg are required, and created is valid for 300 seconds. The full format, with examples, is in Request Signing.
The signature of the base defined by RFC 9421, in base64, between : and under the same label used in Signature-Input, for example sig=:SGVsbG8gd29ybGQ=:. It always goes together with Signature-Input.
Responses
Unique card identifier.
Masked card number (e.g. **** **** **** 1234).
Cardholder name on the card.
Card owner details. Empty when the card has no responsible email.
Card type.
PHYSICALVIRTUALWhen the card was created (ISO 8601).
When the card was last updated (ISO 8601).
Current card status.
ACTIVATEDBLOCKEDCANCELLEDINACTIVATEDCard expiry (ISO 8601).
Display name for the card.
Cost center linked to the card.
Formatted expiry (MM/YYYY).
Intended use of the card.
FREETRIPADSSOFTWAREAERIALHOTELLimit for the current period. Always present; null when limitControl is NO_LIMIT.
Limit control period: DAILY (day), WEEKLY (week), MONTHLY (month), or NO_LIMIT (the card has no limit of its own).
NO_LIMITDAILYWEEKLYMONTHLYMCC groups the card can be used in. Empty when the card has no group restriction: in that case, it accepts purchases in any merchant category.
In Internet Banking, the groups show up as spending categories:
FOOD(Alimentação): supermarkets, restaurants, and bakeries.ADS(Anúncio): ad tools, e-commerce, and marketing platforms.OFFICE(Escritório): equipment, supplies, and stationery.AUTOMOTIVE(Gastos automotivos): gas stations, repair shops, auto parts, and parking.HOTEL(Hospedagem e transporte): hotels, inns, tolls, and transportation in general.TRANSPORTATION(Mobilidade): taxis, buses, and ride-hailing apps.SOFTWARE(Software): tools, digital services, and subscriptions.TRIP(Viagem): tickets, lodging, and transfers.
AERIAL (airline tickets) is the group of air booking VCNs and doesn't show up in Internet Banking.
OTHER is an allowed group with no matching category in Internet Banking. It appears only once, even if the card has more than one such group, and it doesn't mean the card is unrestricted: a card with only OTHER doesn't accept purchases in every category.
TRANSPORTATIONFOODTRIPOFFICEADSSOFTWAREAERIALHOTELAUTOMOTIVEOTHER