VCNCreate VCN (Coming soon)

Create VCN (Coming soon)

🚧 Coming soon — this endpoint is not available in Sandbox or Production yet. The documentation is published so you can prepare your integration; we will announce it in the changelog when it goes live.

Issues a virtual card (VCN) tied to a lodging booking (HOTEL), an air booking (AERIAL) or a use you define (CUSTOM — e.g. one card per supplier). PAN, CVV and expiration are returned synchronously.

Send exactly one block, the one matching your type — hotelBooking, flightBooking or reference — carrying the idempotency key inside it (reservationId, recordLocator — the PNR, Passenger Name Record — or reference.id). For booking types you send the cost (amount) and the card ceiling is derived from it; for CUSTOM you send the ceiling (limit) and no amount. Each field's rules are documented on the field itself, below; each error's behavior, under Responses.

Store the vcnId from the response: it addresses the top-up in Update VCN and the card-data retrieval in Reveal VCN card data.

curl -X POST "https://api-sandbox.contasimples.com/credit-cards/v1/vcns" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
  "type": "HOTEL",
  "amount": {
    "rate": 1250,
    "taxes": 187.5,
    "fees": 35,
    "currency": "BRL"
  },
  "maxPurchaseQuantity": 3,
  "hotelBooking": {
    "reservationId": "ACME-RES-998877",
    "checkIn": "2026-09-15",
    "checkOut": "2026-09-18",
    "propertyId": "PROP-000123",
    "hotelName": "Ibis Styles Palmas",
    "guests": [
      {
        "name": "Ana",
        "surname": "Ribeiro"
      },
      {
        "name": "Bruno",
        "surname": "Alves"
      }
    ],
    "allowExtraCharges": true,
    "extraChargesMargin": 150
  },
  "customFields": [
    {
      "name": "costCenter",
      "value": "CC-042",
      "dataType": "string"
    }
  ],
  "requestor": {
    "name": "Agente Exemplo",
    "email": "agente@exemplo.test",
    "phone": "+5511900000000"
  }
}'

{
  "vcnId": "01JQ8ZK7X4M8N2P5R6T7V8W9XY",
  "type": "HOTEL",
  "hotelBooking": {
    "reservationId": "ACME-RES-998877",
    "checkIn": "2026-09-15",
    "checkOut": "2026-09-18",
    "propertyId": "PROP-000123",
    "hotelName": "Ibis Styles Palmas",
    "guests": [
      {
        "name": "Ana",
        "surname": "Ribeiro"
      },
      {
        "name": "Bruno",
        "surname": "Alves"
      }
    ],
    "allowExtraCharges": true,
    "extraChargesMargin": 150
  },
  "status": "ACTIVE",
  "startDate": "2026-08-21",
  "endDate": "2026-10-08",
  "amount": {
    "rate": 1250,
    "taxes": 187.5,
    "fees": 35,
    "currency": "BRL"
  },
  "limit": {
    "value": 1622.5,
    "currency": "BRL"
  },
  "maxPurchaseQuantity": 3,
  "card": {
    "pan": "4111111111111111",
    "cvv": "123",
    "expirationDate": "06/2031"
  }
}
POST
/credit-cards/v1/vcns
POST
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
Content-Typestring
Required

The media type of the request body

Options: application/json
typestring
Required

What the card is tied to. Defines the required block (HOTEL → hotelBooking, AERIAL → flightBooking, CUSTOM → reference) and how the ceiling is born: derived from amount for booking types, sent in limit for CUSTOM.

Options: HOTEL, AERIAL, CUSTOM
amountobject

Booking cost, as decimal with at most 2 places (e.g. 1250.00). Required for `HOTEL` and `AERIAL`; forbidden for `CUSTOM`, which declares the ceiling directly in limit. The sum rate + taxes + fees must be greater than zero and defines the card's derived ceiling. A value with more than 2 decimal places is rejected with 400 — it is not rounded.

limitobject

Card spending ceiling. Required for `CUSTOM`; forbidden for HOTEL/AERIAL, where the ceiling is derived from amount.

startDatestring

Start of the usage window, YYYY-MM-DD, accepted for all three types. Omitted, the window opens at the moment of issuance. Sent, it cannot fall on a day before the issuance day, and endDate must come after it — otherwise, 400 invalid-vcn-request.

Format: date
endDatestring

End of the usage window, YYYY-MM-DD, accepted for all three types. When sent, it takes precedence over the derived validity (HOTEL = checkOut + 20 days · AERIAL = issuance + 1 day · CUSTOM = issuance + 60 days). Cap: 365 days from issuance — counted from issuance even when you send startDate, so postponing the start does not extend the cap. Beyond that, 400 invalid-vcn-request.

Format: date
maxPurchaseQuantityinteger

Maximum number of authorizations on the card, up to 100000. Overrides the type default (AERIAL 2 · HOTEL 3 · CUSTOM 10000).

Min: 1 • Max: 100000
hotelBookingobject

Lodging data. Required when `type` is `HOTEL` and forbidden for other types.

flightBookingobject

Air booking data. Required when `type` is `AERIAL` and forbidden for other types.

referenceobject

What the CUSTOM card is tied to, defined by you (a supplier, a contract, a payable). Required when `type` is `CUSTOM` and forbidden for other types.

customFieldsarray

Client governance fields. If sent, it must have at least 1 item.

requestorobject
Required

Who requested the issuance, for auditing. email and phone are for internal use and are not shared.

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


Body
application/json
typestring
Required
What the card is tied to. Defines the required block (HOTEL → hotelBooking, AERIAL → flightBooking, CUSTOM → reference) and how the ceiling is born: derived from amount for booking types, sent in limit for CUSTOM.
Allowed values:HOTELAERIALCUSTOM
amountobject
Booking cost, as decimal with at most 2 places (e.g. 1250.00). Required for HOTEL and AERIAL; forbidden for CUSTOM, which declares the ceiling directly in limit. The sum rate + taxes + fees must be greater than zero and defines the card's derived ceiling. A value with more than 2 decimal places is rejected with 400 — it is not rounded.
limitobject
Card spending ceiling. Required for CUSTOM; forbidden for HOTEL/AERIAL, where the ceiling is derived from amount.
startDatestring
Start of the usage window, YYYY-MM-DD, accepted for all three types. Omitted, the window opens at the moment of issuance. Sent, it cannot fall on a day before the issuance day, and endDate must come after it — otherwise, 400 invalid-vcn-request.
Example:
2026-09-10
endDatestring
End of the usage window, YYYY-MM-DD, accepted for all three types. When sent, it takes precedence over the derived validity (HOTEL = checkOut + 20 days · AERIAL = issuance + 1 day · CUSTOM = issuance + 60 days). Cap: 365 days from issuance — counted from issuance even when you send startDate, so postponing the start does not extend the cap. Beyond that, 400 invalid-vcn-request.
Example:
2026-10-27
maxPurchaseQuantityinteger
Maximum number of authorizations on the card, up to 100000. Overrides the type default (AERIAL 2 · HOTEL 3 · CUSTOM 10000).
Example:
3
hotelBookingobject
Lodging data. Required when type is HOTEL and forbidden for other types.
flightBookingobject
Air booking data. Required when type is AERIAL and forbidden for other types.
referenceobject
What the CUSTOM card is tied to, defined by you (a supplier, a contract, a payable). Required when type is CUSTOM and forbidden for other types.
customFieldsarray
Client governance fields. If sent, it must have at least 1 item.
requestorobject
Required
Who requested the issuance, for auditing. email and phone are for internal use and are not shared.


Responses


Was this page helpful?