Criar VCN (Em breve)

🚧 Em breve — este endpoint ainda não está disponível em Sandbox nem Produção. A documentação está publicada para você preparar a integração; avisaremos no changelog quando entrar no ar.

Emite um cartão virtual (VCN) para uma reserva de hotel ou aéreo.

Autenticação: além da API key/secret (que identifica o cliente), este endpoint exige mTLS na camada de transporte.

Retorna PAN, CVV e validade de forma síncrona. O CVV não é persistido.

Envie hotelBooking quando type for HOTEL e flightBooking quando for AIR — nunca os dois ao mesmo tempo.

Reenviar com a mesma Idempotency-Key retorna o mesmo VCN; reutilizar a chave com um payload diferente retorna 409.

curl -X POST "https://api-sandbox.contasimples.com/credit-cards/v1/vcns" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: example_string" \
  -H "X-Origin: ACME_TRAVEL" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
  "type": "HOTEL",
  "amount": {
    "rate": 1200,
    "taxes": 280,
    "currency": "BRL"
  },
  "hotelBooking": {
    "checkIn": "2026-06-01",
    "checkOut": "2026-06-05",
    "guests": 1,
    "rooms": 1,
    "hotelName": "Ibis Styles Palmas",
    "confirmationId": "000001"
  },
  "customFields": [
    {
      "key": "CENTRO DE CUSTO",
      "value": "Engenharia"
    }
  ],
  "bookingId": "ACME-RES-998877"
}'

import requests
import json

url = "https://api-sandbox.contasimples.com/credit-cards/v1/vcns"
headers = {
  "Content-Type": "application/json",
  "Idempotency-Key": "example_string",
  "X-Origin": "ACME_TRAVEL",
  "Authorization": "Bearer YOUR_API_TOKEN"
}
data = {
  "type": "HOTEL",
  "amount": {
    "rate": 1200,
    "taxes": 280,
    "currency": "BRL"
  },
  "hotelBooking": {
    "checkIn": "2026-06-01",
    "checkOut": "2026-06-05",
    "guests": 1,
    "rooms": 1,
    "hotelName": "Ibis Styles Palmas",
    "confirmationId": "000001"
  },
  "customFields": [
    {
      "key": "CENTRO DE CUSTO",
      "value": "Engenharia"
    }
  ],
  "bookingId": "ACME-RES-998877"
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

const response = await fetch("https://api-sandbox.contasimples.com/credit-cards/v1/vcns", {
  method: "POST",
  headers: {
  "Content-Type": "application/json",
  "Idempotency-Key": "example_string",
  "X-Origin": "ACME_TRAVEL",
  "Authorization": "Bearer YOUR_API_TOKEN"
},
  body: JSON.stringify({
  "type": "HOTEL",
  "amount": {
    "rate": 1200,
    "taxes": 280,
    "currency": "BRL"
  },
  "hotelBooking": {
    "checkIn": "2026-06-01",
    "checkOut": "2026-06-05",
    "guests": 1,
    "rooms": 1,
    "hotelName": "Ibis Styles Palmas",
    "confirmationId": "000001"
  },
  "customFields": [
    {
      "key": "CENTRO DE CUSTO",
      "value": "Engenharia"
    }
  ],
  "bookingId": "ACME-RES-998877"
})
});

const data = await response.json();
console.log(data);

package main

import (
    "fmt"
    "net/http"
    "bytes"
    "encoding/json"
)

func main() {
    data := []byte(`{
  "type": "HOTEL",
  "amount": {
    "rate": 1200,
    "taxes": 280,
    "currency": "BRL"
  },
  "hotelBooking": {
    "checkIn": "2026-06-01",
    "checkOut": "2026-06-05",
    "guests": 1,
    "rooms": 1,
    "hotelName": "Ibis Styles Palmas",
    "confirmationId": "000001"
  },
  "customFields": [
    {
      "key": "CENTRO DE CUSTO",
      "value": "Engenharia"
    }
  ],
  "bookingId": "ACME-RES-998877"
}`)

    req, err := http.NewRequest("POST", "https://api-sandbox.contasimples.com/credit-cards/v1/vcns", bytes.NewBuffer(data))
    if err != nil {
        panic(err)
    }

    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("Idempotency-Key", "example_string")
    req.Header.Set("X-Origin", "ACME_TRAVEL")
    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')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request['Content-Type'] = 'application/json'
request['Idempotency-Key'] = 'example_string'
request['X-Origin'] = 'ACME_TRAVEL'
request['Authorization'] = 'Bearer YOUR_API_TOKEN'
request.body = '{
  "type": "HOTEL",
  "amount": {
    "rate": 1200,
    "taxes": 280,
    "currency": "BRL"
  },
  "hotelBooking": {
    "checkIn": "2026-06-01",
    "checkOut": "2026-06-05",
    "guests": 1,
    "rooms": 1,
    "hotelName": "Ibis Styles Palmas",
    "confirmationId": "000001"
  },
  "customFields": [
    {
      "key": "CENTRO DE CUSTO",
      "value": "Engenharia"
    }
  ],
  "bookingId": "ACME-RES-998877"
}'

response = http.request(request)
puts response.body

{
  "vcnId": "21624502",
  "bookingId": "ACME-AIR-554433",
  "type": "AIR",
  "card": {
    "pan": "4656350026056026",
    "cvv": "411",
    "expirationDate": "06/31",
    "holderName": "EMPRESA EXEMPLO LTDA"
  },
  "controls": {
    "spendLimit": {
      "value": 101,
      "currency": "BRL"
    },
    "maxTransactions": 2,
    "validity": {
      "start": "2026-06-09",
      "end": "2026-06-10"
    },
    "merchantCategory": "AIR"
  },
  "status": "ACTIVE",
  "createdAt": "2026-06-09T15:55:10Z"
}

{
  "error": "Bad Request",
  "message": "Um ou mais parâmetros da requisição são inválidos.",
  "code": 400,
  "requestId": "123e4567-e89b-12d3-a456-426614174000",
  "details": [
    "O campo exemplo deve ter um valor entre 5 e 100.",
    "datas devem estar no formato YYYY-MM-DD."
  ]
}

POST

/credit-cards/v1/vcns

POST

Base URLstring

Target server for requests. Edit to use your own host.

Bearer Token

Bearer Tokenstring

Required

Token Bearer obtido via OAuth 2.0 Client Credentials. Formato: Bearer TOKEN

Content-Typestring

Required

The media type of the request body

Options: application/json

header

Idempotency-Keystring

Required

Dedupe — use o identificador da reserva (bookingId). String estável e única por reserva.

Min length: 1 • Max length: 255

header

X-Originstring

Identifica a OBT originadora da requisição. Atribuído pela Conta Simples no onboarding.

typestring

Required

Tipo do produto. Define qual bloco de reserva é obrigatório (HOTEL → hotelBooking, AIR → flightBooking).

Options: HOTEL, AIR

bookingIdstring

Required

Identificador da reserva na OBT. Base da idempotência.

Min length: 1

amountobject

Required

Valores em formato decimal (ex.: 100.00), na moeda indicada em currency. O limite do cartão corresponde a rate + taxes.

hotelBookingobject

flightBookingobject

customFieldsarray

Campos de governança do cliente (ex.: centro de custo, solicitante). Aparecem no extrato/relatório do cartão e ficam disponíveis para conciliação.

metadataarray

Campos adicionais de extensão (chave/valor), persistidos apenas na Conta Simples. Use só para dados não cobertos por hotelBooking/flightBooking nem customFields.

Request Preview

Response

Response will appear here after sending the request

Authentication

header

Authorizationstring

Required

Bearer token. Token Bearer obtido via OAuth 2.0 Client Credentials. Formato: Bearer TOKEN

Headers

Idempotency-Keystring

Required

Dedupe — use o identificador da reserva (bookingId). String estável e única por reserva.

X-Originstring

Identifica a OBT originadora da requisição. Atribuído pela Conta Simples no onboarding.

Example:

ACME_TRAVEL

Body

application/json

typestring

Required

Tipo do produto. Define qual bloco de reserva é obrigatório (HOTEL → hotelBooking, AIR → flightBooking).

Allowed values:HOTELAIR

bookingIdstring

Required

Identificador da reserva na OBT. Base da idempotência.

amountobject

Required

Valores em formato decimal (ex.: 100.00), na moeda indicada em currency. O limite do cartão corresponde a rate + taxes.

hotelBookingobject

flightBookingobject

customFieldsarray

Campos de governança do cliente (ex.: centro de custo, solicitante). Aparecem no extrato/relatório do cartão e ficam disponíveis para conciliação.

metadataarray

Campos adicionais de extensão (chave/valor), persistidos apenas na Conta Simples. Use só para dados não cobertos por hotelBooking/flightBooking nem customFields.

Responses

Was this page helpful?