Cancel VCN
Closes a VCN for good, for all three types, even when its window has already ended: the card stops authorizing purchases and does not go back to ACTIVE. The body carries only the requestor, who requests the cancellation. The response is the Get VCN body with status: CANCELLED, without the card block; window, ceiling and counts do not change.
Before you call
- Retrying is safe: an already-cancelled VCN answers
200with the same body and the sameupdatedAt, with no new effect. - After cancellation, Reveal VCN card data answers
409 vcn-cancelledand, forCUSTOM, Update VCN answers409 vcn-not-active. - The idempotency key is freed: a new issuance with it on Create VCN creates another card, with a new PAN, and the cancelled
vcnIdstarts answering404on every route.
Errors
400 bad-request-exception— invalidvcnIdin the path (fieldpath.vcnId).400 bad-request-exception— invalid body, witherrors[]: no body, a missing or out-of-boundsrequestor, or a key other thanrequestor. See Request body.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— a final provider refusal (the VCN remains valid) or an internal timeout (the cancellation may have completed). Retry theDELETEor check thestatuswith Get VCN; if it is stillACTIVE, contact support with the time, therequestIdand thevcnId.503 vcn-cancel-unavailable— transient provider failure; the VCN remains valid. Retry the request.503 vcn-cancellation-not-persisted— the card was already cancelled at the provider, but the cancellation has not been completed at Conta Simples yet: Get VCN may showACTIVE, and a new issuance on the same key answers409 vcn-already-issued. Retry theDELETE; if it persists, contact support (thevcnIdcomes inmessage).
Rules
curl -X DELETE "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" \
-d '{
"requestor": "agente@exemplo.test"
}'
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"
}
data = {
"requestor": "agente@exemplo.test"
}
response = requests.delete(url, headers=headers, json=data)
print(response.json())
const response = await fetch("https://api-sandbox.contasimples.com/credit-cards/v1/vcns/01JQ8ZP4C7D9F1G3H5J7K9J2MN", {
method: "DELETE",
headers: {
"Content-Type": "application/json",
"X-Partner-Id": "ptn_01JQ8ZK7X4M8N2P5R6T7V8W9XY",
"Signature-Input": "example_string",
"Signature": "example_string",
"Authorization": "Bearer YOUR_API_TOKEN"
},
body: JSON.stringify({
"requestor": "agente@exemplo.test"
})
});
const data = await response.json();
console.log(data);
package main
import (
"fmt"
"net/http"
"bytes"
"encoding/json"
)
func main() {
data := []byte(`{
"requestor": "agente@exemplo.test"
}`)
req, err := http.NewRequest("DELETE", "https://api-sandbox.contasimples.com/credit-cards/v1/vcns/01JQ8ZP4C7D9F1G3H5J7K9J2MN", bytes.NewBuffer(data))
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::Delete.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'
request.body = '{
"requestor": "agente@exemplo.test"
}'
response = http.request(request)
puts response.body
{
"vcnId": "01JQ8ZP4C7D9F1G3H5J7K9J2MN",
"reference": "SUP-000123",
"type": "CUSTOM",
"status": "CANCELLED",
"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-08T11:04:55.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": "cancelVcn"
},
"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"
}
{
"code": "vcn-cancel-unavailable",
"message": "The VCN cancellation could not be completed; retry the request."
}
{
"code": "vcn-cancellation-not-persisted",
"message": "The VCN was cancelled at the provider but the local record was not updated; reconcile vcnId: 01JQ8ZP4C7D9F1G3H5J7K9J2MN"
}
/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).
The media type of the request body
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.
Who requests the issuance, update or cancellation, for auditing. Send a user's e-mail or, for an automated call, an identifier from your system. Free text, 1 to 100 characters.
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.
Body
Who requests the issuance, update or cancellation, for auditing. Send a user's e-mail or, for an automated call, an identifier from your system. Free text, 1 to 100 characters.
agente@exemplo.testResponses
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.