VCN guide

Overview

A VCN (Virtual Card Number) is a restricted-use virtual card, issued from your company's funding card, the corporate card it comes from. Each VCN has a usage window, a spending ceiling and a maximum number of authorizations (maxPurchaseQuantity). The PAN, CVV and expiration come back on issuance.

Types

Pick the type by what the card will pay for. The type defines the identifier you send and where the ceiling comes from:

Only CUSTOM can be updated: the HOTEL and AERIAL controls come from the booking.

Lifecycle

The sections below detail the rules of each step.

Platform identification (X-Partner-Id)

Every VCN call sends, in the X-Partner-Id header, the integrator platform (partner) it is made through. The header is required on every VCN route.

• Credential with more than one partner: a credential may be bound to more than one platform. On each call, send the X-Partner-Id of the platform for that operation. The idempotency key is scoped per partner: the same key under another partner does not collide (see Idempotency and reissuance).

curl -X GET https://api-sandbox.contasimples.com/credit-cards/v1/vcns/{vcnId}/reveal \
  -H "Authorization: Bearer {TOKEN}" \
  -H "User-Agent: {your-app-name}/{version}" \
  -H "X-Partner-Id: ptn_01JQ8ZK7X4M8N2P5R6T7V8W9XY"

Usage window

A VCN only authorizes purchases inside the startDate–endDate window. Both dates are calendar days in Brasília time — an exception to the API's general UTC date rule —, and "today" is the current day in Brasília.

• The window opens at 00:00 of startDate and closes at the end of the endDate day: endDate is inclusive.
• Without startDate, the window starts on the issuance day, and the card is usable right away.
• createdAt and updatedAt are UTC instants. For an issuance between 9 p.m. and midnight in Brasília, createdAt falls on the day after startDate.
• The window is not the physical card expiration, which comes in card.expirationDate.

Default end per type

Without endDate in the request, the end is the type default. The default does not follow startDate: if the start falls on the default day or later, the window is inverted and issuance is rejected — in that case, send endDate.

Date limits

Except where noted, the rejection is 400 invalid-vcn-request, without errors[], with the reason in message. For the funding-card cap, the reason is end date must not exceed the funding card expiration: shorten the window or contact Conta Simples.

Expiry and closing

• The VCN expires from the day after endDate. On the endDate day itself it still accepts updates, and a new issuance on the same key still answers 409.
• Once expired, Update VCN answers 409 vcn-expired: do not top it up, issue another one.
• There is no expired status: an expired VCN stays ACTIVE. Compare endDate with today's date in Brasília.
• Shortening endDate does not close the card. To close it, use Cancel VCN.
• Top-ups do not push the validity, and changing the validity does not touch the ceiling: for both, send limit and endDate.
• The startDate of an issued VCN does not change.

Idempotency and reissuance

Each type has an idempotency key, and it is also the identifier you send:

• The response returns the key in reference, as a string, for all three types. In the request, only CUSTOM sends reference.
• The key is scoped to company, type and integrator platform (the call's X-Partner-Id): the same key under another type or another partner does not collide.
• While the key's VCN is live (ACTIVE or BLOCKED, inside its window), a new issuance answers 409 vcn-already-issued, without the card data and without the vcnId. Store the vcnId from the 201 together with the key.
• For CUSTOM, that 409 is the expected path: the card for that reference already exists. Top it up with Update VCN; every new reference creates a new card.
• The key is freed after expiry or cancellation. A new issuance with it creates another card, with a new PAN, and the previous vcnId starts answering 404 on every route.
• Do not put personal data in the key: it is stored and returned in the responses.

Ceiling and top-up

• HOTEL and AERIAL: the ceiling is derived from the cost, amount.rate + amount.taxes + amount.fees, which must be greater than zero. For HOTEL, the extra-charges margin is added when allowExtraCharges is true: the extraChargesMargin value or, without it, the default margin — currently R$ 150.00 per night per guest, subject to change. To control the ceiling, send extraChargesMargin.
• CUSTOM: the ceiling is the limit.value you send, from 0.01. Only CUSTOM is updatable; HOTEL and AERIAL controls come from the booking.
• The ceiling is not a balance: the available amount is computed by the card network (available = ceiling − spent), and the API does not return what was spent.

Top-up in the TOTAL period

⚠️ In the TOTAL period, the default, limit.value is the window's accumulated ceiling, not an increment. To add credit, send current ceiling + credit.

Example: ceiling 100.01 and a new R$ 80.00 sale → send 180.01. If you send 80.00, the ceiling drops below what was already spent, and every new authorization is declined.

The current ceiling comes back in the Create VCN 201, in the Update VCN 200 and in Get VCN: keep the latest one you receive.

Ceiling period

• The top-up arithmetic above only holds for TOTAL. With MONTHLY or DAILY, limit.value is the ceiling for each month or day.
• The period does not interact with maxPurchaseQuantity, which counts authorizations.
• On Update VCN, an omitted spendLimitPeriod keeps the current period, and changing the period does not reset what was spent: a card moving from TOTAL to MONTHLY does not get a clean month.

Parallel top-ups

• Send limit.expectedValue with the ceiling you believe is current: the update only writes if it matches.
• If it does not match — or if another update of the same VCN writes in between, which also happens without expectedValue and on calls in quick succession —, the response is 409 vcn-limit-conflict. Recompute the total from the latest ceiling and retry. Re-read the ceiling with Get VCN; the read may take a few moments to reflect the latest update.

Retrying calls

The API's general retry rules do not apply the same way to every VCN endpoint:

On any endpoint, if the error persists, contact support with the time of the call and the requestId.

Reading right after writing

Reads are eventually consistent.

• Right after issuance, Update, Reveal, Get and Cancel may answer 404 for a few moments: retry before concluding the VCN does not exist.
• Right after an update or a cancellation, Get VCN may return the previous state for a few moments.
• Updates to the same VCN in very quick succession may get 409 vcn-limit-conflict (see Parallel top-ups).

Request body

Create VCN

• Send exactly one identifier, the one for your type: hotelBooking, flightBooking or reference. One of another type is rejected with 400 bad-request-exception, and the error field points at it (e.g. body.reference on a HOTEL).
• Money has one field per meaning: amount is the booking cost (required for HOTEL and AERIAL, forbidden for CUSTOM); limit is the ceiling (required for CUSTOM, forbidden for booking types).
• Amounts are decimals with up to 2 places. More places → 400, with no rounding. The currency is always BRL.
• Unknown keys are discarded silently — including partner: the platform comes only from the X-Partner-Id header and is never read from the body.
• null is not the same as an absent field: on an optional field, it is rejected with 400.
• reference is a string. An object ({"id": …}) is rejected with 400.
• requestor is required: a 1 to 100 character string, with a user's e-mail or an identifier from your system. An object ({"name": …}) is rejected with 400.
• customFields takes up to 50 items, with name up to 50 and value up to 100 characters: these are the limits the card network accepts. Above them, 400.

Update VCN

• Send Content-Type: application/json, the requestor (as in Create VCN) and only what you want to change: at least one of limit, endDate, maxPurchaseQuantity and spendLimitPeriod. An empty body or one with only the requestor → 400; a field you do not send does not change.
• The body is closed. Any other key is rejected with 400 bad-request-exception, and the error field points at the rejected key (e.g. body.expirationDate, body.limit.currency). That includes the immutable type, reference, startDate, customFields, the limit currency and the old name expirationDate.

Cancel VCN

• Send Content-Type: application/json and a body with only the requestor, as in Create VCN. No body, no requestor or any other key → 400 bad-request-exception.

Error format

Every error of the VCN endpoints has code, message and requestId; errors[] only comes with bad-request-exception.

• Handle the error by its code. The message text may change; the 500 always answers An unexpected error occurred on the server.
• bad-request-exception is a format rejection, with one errors[] entry per field. invalid-vcn-request is a window or ceiling rule rejection: it has no errors[], and the reason is in message.
• errors[].field always starts with the request part: body., path. or headers. (e.g. body.amount.rate, path.vcnId, headers.x-partner-id). When the rejection concerns the whole body — no field to change on Update VCN —, the field is just body. Do not look for a bare amount.rate.
• requestId identifies the call: give it to support along with the time.
• An invalid vcnId in the path — longer than 255 characters, containing /, \, ? or #, or equal to . or .. — gives 400 bad-request-exception with field path.vcnId.

Evaluation order

When more than one rule fails, the error you get is the first one in this order:

• Create VCN: 409 vcn-already-issued comes before the date rules. A live key answers 409 even if the request dates are invalid.
• Update VCN: vcn-not-updatable → vcn-not-active → vcn-expired → vcn-limit-conflict (on expectedValue) → 400 invalid-vcn-request (endDate rules).
• Reveal VCN card data: ownership comes before cancellation. A cancelled VCN of another company answers 404, not 409.