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."
]
}
{
"error": "Unauthorized",
"message": "Token de acesso inválido ou expirado.",
"requestId": "123e4567-e89b-12d3-a456-426614174000",
"code": 401
}
{
"error": "Forbidden",
"message": "Você não tem permissão para realizar esta operação.",
"requestId": "123e4567-e89b-12d3-a456-426614174000",
"code": 403
}
{
"error": "Conflict",
"message": "Já existe um fornecedor com o mesmo nome para esta empresa.",
"requestId": "123e4567-e89b-12d3-a456-426614174000",
"code": 409
}
{
"error": "Unprocessable Entity",
"message": "A categoria informada não existe ou não pertence à empresa.",
"requestId": "123e4567-e89b-12d3-a456-426614174000",
"code": 422
}
{
"error": "Internal Server Error",
"message": "Ocorreu um erro inesperado ao processar a solicitação.",
"requestId": "123e4567-e89b-12d3-a456-426614174000",
"code": 500
}
/credit-cards/v1/vcns
Target server for requests. Edit to use your own host.
Token Bearer obtido via OAuth 2.0 Client Credentials. Formato: Bearer {token}
Bearer {token}The media type of the request body
Dedupe — use o identificador da reserva (bookingId). String estável e única por reserva.
Identifica a OBT originadora da requisição. Atribuído pela Conta Simples no onboarding.
Tipo do produto. Define qual bloco de reserva é obrigatório (HOTEL → hotelBooking, AIR → flightBooking).
Identificador da reserva na OBT. Base da idempotência.
Valores em formato decimal (ex.: 100.00), na moeda indicada em currency. O limite do cartão corresponde a rate + taxes.
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.
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
Bearer token. Token Bearer obtido via OAuth 2.0 Client Credentials. Formato: Bearer {token}
Headers
Dedupe — use o identificador da reserva (bookingId). String estável e única por reserva.
Identifica a OBT originadora da requisição. Atribuído pela Conta Simples no onboarding.
ACME_TRAVELBody
Tipo do produto. Define qual bloco de reserva é obrigatório (HOTEL → hotelBooking, AIR → flightBooking).
HOTELAIRIdentificador da reserva na OBT. Base da idempotência.
Valores em formato decimal (ex.: 100.00), na moeda indicada em currency. O limite do cartão corresponde a rate + taxes.
Data de entrada (check-in), formato ISO (YYYY-MM-DD).
Data de saída (check-out), formato ISO (YYYY-MM-DD).
Número de hóspedes. Influencia a margem do limite.
Número de quartos. Influencia o número de autorizações permitidas.
Nome do hóspede titular.
Sobrenome do hóspede titular.
Nome do hotel.
Localizador / ID de confirmação da reserva.
Data de ida, formato ISO (YYYY-MM-DD).
Data de volta. Ausente/nulo = somente ida.
Número de passageiros.
Nome do passageiro titular.
Sobrenome do passageiro titular.
Localizador da reserva (PNR).
Companhia aérea emissora (código IATA, ex.: JJ).
Número do bilhete.
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.
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
HOTELAIRNúmero do cartão (PAN). Não deve ser logado.
Código de segurança (CVV). Nunca persistido.
Validade do cartão no formato MM/AA (ex.: 06/31 = junho de 2031).
Nome do titular.
Categoria de comerciante (MCC) travada no cartão: LODG (hotelaria) quando type=HOTEL, AIR (companhias aéreas) quando type=AIR.
LODGAIRACTIVECANCELLEDEXPIREDBreve identificação do tipo de erro (ex.: Bad Request, Not Found).
Descrição breve do erro para o cliente da API.
Código HTTP do erro (corresponde ao status da resposta).
Opcional. Em erros 400, pode ser uma string com um único detalhe ou um array de strings com cada falha de validação.
Breve identificação do tipo de erro (ex.: Bad Request, Not Found).
Descrição breve do erro para o cliente da API.
Código HTTP do erro (corresponde ao status da resposta).
Opcional. Em erros 400, pode ser uma string com um único detalhe ou um array de strings com cada falha de validação.
Breve identificação do tipo de erro (ex.: Bad Request, Not Found).
Descrição breve do erro para o cliente da API.
Código HTTP do erro (corresponde ao status da resposta).
Opcional. Em erros 400, pode ser uma string com um único detalhe ou um array de strings com cada falha de validação.
Breve identificação do tipo de erro (ex.: Bad Request, Not Found).
Descrição breve do erro para o cliente da API.
Código HTTP do erro (corresponde ao status da resposta).
Opcional. Em erros 400, pode ser uma string com um único detalhe ou um array de strings com cada falha de validação.
Breve identificação do tipo de erro (ex.: Bad Request, Not Found).
Descrição breve do erro para o cliente da API.
Código HTTP do erro (corresponde ao status da resposta).
Opcional. Em erros 400, pode ser uma string com um único detalhe ou um array de strings com cada falha de validação.
Breve identificação do tipo de erro (ex.: Bad Request, Not Found).
Descrição breve do erro para o cliente da API.
Código HTTP do erro (corresponde ao status da resposta).
Opcional. Em erros 400, pode ser uma string com um único detalhe ou um array de strings com cada falha de validação.