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, withstatus: CANCELLED. This is how you find out why Reveal answered409 vcn-cancelled. - There is no expired status: an expired VCN stays
ACTIVE. CompareendDate, 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— invalidvcnIdin the path (fieldpath.vcnId).400 bad-request-exception— missing or malformedX-Partner-Id(fieldheaders.x-partner-id). See Platform identification.403 caller-not-authorized— theX-Partner-Idpartner is not bound to your credential (details.reasonPARTNER_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 therequestId.
Rules
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"
import requests
import json
url = "https://api-sandbox.contasimples.com/credit-cards/v1/vcns/01JQ8ZP4C7D9F1G3H5J7K9J2MN"
headers = {
"Content-Type": "application/json",
"X-Partner-Id": "ptn_01JQ8ZK7X4M8N2P5R6T7V8W9XY",
"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/vcns/01JQ8ZP4C7D9F1G3H5J7K9J2MN", {
method: "GET",
headers: {
"Content-Type": "application/json",
"X-Partner-Id": "ptn_01JQ8ZK7X4M8N2P5R6T7V8W9XY",
"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/vcns/01JQ8ZP4C7D9F1G3H5J7K9J2MN", nil)
if err != nil {
panic(err)
}
req.Header.Set("Content-Type", "application/json")
req.Header.Set("X-Partner-Id", "ptn_01JQ8ZK7X4M8N2P5R6T7V8W9XY")
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/vcns/01JQ8ZP4C7D9F1G3H5J7K9J2MN')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Get.new(uri)
request['Content-Type'] = 'application/json'
request['X-Partner-Id'] = 'ptn_01JQ8ZK7X4M8N2P5R6T7V8W9XY'
request['Signature-Input'] = 'example_string'
request['Signature'] = 'example_string'
request['Authorization'] = 'Bearer YOUR_API_TOKEN'
response = http.request(request)
puts response.body
{
"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"
}
{
"vcnId": "01JQ8ZK7X4M8N2P5R6T7V8W9XY",
"reference": "ACME-RES-998877",
"type": "HOTEL",
"status": "ACTIVE",
"startDate": "2027-03-01",
"endDate": "2027-04-07",
"limit": {
"value": 1622.5,
"currency": "BRL"
},
"amount": {
"rate": 1250,
"taxes": 187.5,
"fees": 35,
"currency": "BRL"
},
"maxPurchaseQuantity": 3,
"spendLimitPeriod": "TOTAL",
"createdAt": "2027-03-01T13:05:22.000Z",
"updatedAt": "2027-03-01T13:05:22.000Z"
}
{
"code": "bad-request-exception",
"message": "Event failed validation",
"errors": [
{
"field": "path.vcnId",
"message": "vcnId is not a valid identifier"
}
]
}
{
"code": "bad-request-exception",
"message": "Event failed validation",
"errors": [
{
"field": "headers.x-partner-id",
"message": "x-partner-id must be a valid partner identifier"
}
]
}
{
"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": "getVcn"
},
"requestId": "123e4567-e89b-12d3-a456-426614174000"
}
{
"code": "caller-not-authorized",
"message": "The request is not allowed for the current credentials",
"details": {
"reason": "PARTNER_NOT_BOUND"
},
"requestId": "123e4567-e89b-12d3-a456-426614174000"
}
{
"code": "vcn-not-found",
"message": "VCN not found"
}
{
"code": "internal-exception",
"message": "An unexpected error occurred on the server"
}
/credit-cards/v1/vcns/{vcnId}Target server for requests. Edit to use your own host.
Bearer token from OAuth 2.0 client credentials. Format: Bearer TOKEN
Bearer TOKENVCN identifier returned at issuance (vcnId field).
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.
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
VCN identifier returned at issuance (vcnId field).
01JQ8ZP4C7D9F1G3H5J7K9J2MNHeaders
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.
ptn_01JQ8ZK7X4M8N2P5R6T7V8W9XYWhat 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
Echo of the identifier.
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.
What the card is tied to.
HOTELAERIALCUSTOMACTIVE, 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.
ACTIVEBLOCKEDCANCELLEDStart of the usage window, YYYY-MM-DD, as a calendar day in Brasília time — the same value returned at issuance.
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.
Spending ceiling in effect — not a balance nor the available amount: spending is not returned by this API.
Booking cost — present only for HOTEL/AERIAL; absent for CUSTOM. It is the only optional field of this body.
Maximum number of authorizations in effect.
Ceiling period in effect — always present.
TOTALMONTHLYDAILYIssuance 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.
Instant of the latest change — update or cancellation —, in UTC. Repeating the cancellation of an already-cancelled VCN does not change it.