VCNGet VCN

Get VCN

Returns the state of an issued VCN: status, usage window, current ceiling and controls. It does not carry the card data, which lives in Reveal VCN card data, nor the booking block echo, nor balance or spending: limit.value is the ceiling, not the available amount.

Before you call

  • A cancelled VCN answers 200, with status: CANCELLED. This is how you find out why Reveal answered 409 vcn-cancelled.
  • There is no expired status: an expired VCN stays ACTIVE. Compare endDate, which is inclusive, with today's date in Brasília.
  • Right after issuing, updating or cancelling, the read may lag for a few moments. See Reading right after writing.

Errors

  • 400 bad-request-exception — invalid vcnId in the path (field path.vcnId).
  • 400 bad-request-exception — missing or malformed X-Partner-Id (field headers.x-partner-id). See Platform identification.
  • 403 caller-not-authorized — the X-Partner-Id partner is not bound to your credential (details.reason PARTNER_NOT_BOUND), or the credential lacks the route scope (details.requiredScope). See Platform identification.
  • 404 vcn-not-found — the VCN does not exist, belongs to another company or was replaced by a reissuance. Right after issuance, retry before concluding.
  • 500 internal-exception — internal error; retrying the read is safe. If it persists, contact support with the time and the requestId.

Rules

Reading right after writing · Idempotency and reissuance

curl -X GET "https://api-sandbox.contasimples.com/credit-cards/v1/vcns/01JQ8ZP4C7D9F1G3H5J7K9J2MN" \
  -H "Content-Type: application/json" \
  -H "X-Partner-Id: ptn_01JQ8ZK7X4M8N2P5R6T7V8W9XY" \
  -H "Signature-Input: example_string" \
  -H "Signature: example_string" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
{
  "vcnId": "01JQ8ZP4C7D9F1G3H5J7K9J2MN",
  "reference": "SUP-000123",
  "type": "CUSTOM",
  "status": "ACTIVE",
  "startDate": "2027-03-01",
  "endDate": "2027-06-30",
  "limit": {
    "value": 350,
    "currency": "BRL"
  },
  "maxPurchaseQuantity": 10000,
  "spendLimitPeriod": "TOTAL",
  "createdAt": "2027-03-01T14:32:10.000Z",
  "updatedAt": "2027-03-05T10:20:03.000Z"
}
GET
/credit-cards/v1/vcns/{vcnId}
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
vcnIdstring
Required

VCN identifier returned at issuance (vcnId field).

header
X-Partner-Idstring
Required

Identifier of the integrator platform (partner) the call is made through: ptn_ followed by a 26-character ULID. Conta Simples generates it and hands it to you at onboarding. See Platform identification.

Pattern: ^ptn_[0-9A-HJKMNP-TV-Z]{26}$
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

vcnIdstring
Required

VCN identifier returned at issuance (vcnId field).

Example:
01JQ8ZP4C7D9F1G3H5J7K9J2MN

Headers

X-Partner-Idstring
Required

Identifier of the integrator platform (partner) the call is made through: ptn_ followed by a 26-character ULID. Conta Simples generates it and hands it to you at onboarding. See Platform identification.

Example:
ptn_01JQ8ZK7X4M8N2P5R6T7V8W9XY
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

vcnIdstring
Required

Echo of the identifier.

referencestring
Required

The VCN's idempotency key, as a string, for all three types: the reservationId for HOTEL, the recordLocator for AERIAL and the reference sent for CUSTOM.

typestring
Required

What the card is tied to.

Allowed values:HOTELAERIALCUSTOM
statusstring
Required

ACTIVE, BLOCKED or CANCELLED. CANCELLED is final and comes from Cancel VCN. There is no expired status: compare endDate with today's date in Brasília.

Allowed values:ACTIVEBLOCKEDCANCELLED
startDatestring
Required

Start of the usage window, YYYY-MM-DD, as a calendar day in Brasília time — the same value returned at issuance.

endDatestring
Required

Current end of the usage window, YYYY-MM-DD, inclusive: the card authorizes until the end of that day, in Brasília time. It reflects the latest update; cancellation does not change it.

limitstring
Required

Spending ceiling in effect — not a balance nor the available amount: spending is not returned by this API.

amountstring

Booking cost — present only for HOTEL/AERIAL; absent for CUSTOM. It is the only optional field of this body.

maxPurchaseQuantityinteger
Required

Maximum number of authorizations in effect.

spendLimitPeriodstring
Required

Ceiling period in effect — always present.

Allowed values:TOTALMONTHLYDAILY
createdAtstring
Required

Issuance instant, in UTC. The issuance day in startDate is counted in Brasília time: for an issuance between 9 p.m. and midnight (Brasília), the two dates differ.

updatedAtstring
Required

Instant of the latest change — update or cancellation —, in UTC. Repeating the cancellation of an already-cancelled VCN does not change it.