CardsGet Card by ID

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

  • limit is always present in the response and is null when limitControl is NO_LIMIT.
  • limit values are in Brazilian reais (BRL), with up to 2 decimal places, and refer to the current limitControl period (day, week, or month).
  • limit.available is 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 mccGroups means the card has no group restriction and can be used in any merchant category.
  • purpose is the card's purpose and doesn't restrict where it can be used; mccGroups does.

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 — an id in an invalid format, such as a value longer than 120 characters (field path.id). Use the id exactly 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 the getCreditCard scope (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 the 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

Bearer token from OAuth 2.0 client credentials. Format: Bearer TOKEN

Bearer token from OAuth 2.0 client credentials. Format: Bearer TOKEN
path
idstring
Required

Card identifier — use the id field returned by GET /credit-cards/v1/cards (e.g. 01JVWSWPWNAW27E802541SJ7P1).

Max length: 120
header
Signature-Inputstring

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.

header
Signaturestring

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

header
Authorizationstring
Required

Bearer token. Bearer token from OAuth 2.0 client credentials. Format: Bearer TOKEN

Path Parameters

idstring
Required

Card identifier — use the id field returned by GET /credit-cards/v1/cards (e.g. 01JVWSWPWNAW27E802541SJ7P1).

Example:
01JVWSWPWNAW27E802541SJ7P1

Headers

Signature-Inputstring

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.

Signaturestring

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

idstring
Required

Unique card identifier.

maskedNumberstring
Required

Masked card number (e.g. **** **** **** 1234).

cardHolderNamestring
Required

Cardholder name on the card.

responsibleobject
Required

Card owner details. Empty when the card has no responsible email.

typestring
Required

Card type.

Allowed values:PHYSICALVIRTUAL
createdAtstring
Required

When the card was created (ISO 8601).

updatedAtstring
Required

When the card was last updated (ISO 8601).

statusstring
Required

Current card status.

Allowed values:ACTIVATEDBLOCKEDCANCELLEDINACTIVATED
expirationDatestring
Required

Card expiry (ISO 8601).

namestring
Required

Display name for the card.

costCenterobject
Required

Cost center linked to the card.

formattedExpirationDatestring
Required

Formatted expiry (MM/YYYY).

purposestring
Required

Intended use of the card.

Allowed values:FREETRIPADSSOFTWAREAERIALHOTEL
limitobject
Required

Limit for the current period. Always present; null when limitControl is NO_LIMIT.

limitControlstring
Required

Limit control period: DAILY (day), WEEKLY (week), MONTHLY (month), or NO_LIMIT (the card has no limit of its own).

Allowed values:NO_LIMITDAILYWEEKLYMONTHLY
mccGroupsstring[]
Required

MCC 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.

Allowed values:TRANSPORTATIONFOODTRIPOFFICEADSSOFTWAREAERIALHOTELAUTOMOTIVEOTHER