Update VCN
Use the Sandbox to prepare your integration and validate authentication and the contract.
Updates a CUSTOM VCN without replacing the card (the PAN stays the same): tops up the ceiling, extends or shortens the window and adjusts the controls. HOTEL and AERIAL VCNs are not updatable: their controls come from the booking.
Before you call
- Send the
requestorand only what you want to change, at least one field besides it; anything you do not send stays as is. - ⚠️ In the
TOTALperiod,limit.valueis the window's accumulated ceiling, not an increment: send the current ceiling plus the credit. See Ceiling and top-up. - Keep the ceiling returned in the
200: it is the base for the next top-up. - To re-read the state and the ceiling, use Get VCN; to close the card, Cancel VCN. Shortening
endDatedoes not close it.
Errors
400 bad-request-exception— invalid body, witherrors[]: a missingrequestor, no field besides it, a value below0.01, a key outside the updatable list or an invalidvcnId. See Request body.400 invalid-vcn-request— the newendDatebreaks a window limit; the reason comes inmessage. See Date limits.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.409 vcn-not-updatable— the VCN is notCUSTOM.409 vcn-not-active— the VCN isBLOCKEDorCANCELLED. A cancelled one does not come back; for a blocked one, contact Conta Simples. Check thestatuswith Get VCN.409 vcn-expired— the window has ended (from the day afterendDate). Do not top it up: issue another one with Create VCN, on the same key.409 vcn-limit-conflict— the ceiling changed between the read and the write, with or withoutexpectedValue. Recompute from the latest ceiling and retry. See Parallel top-ups.500 internal-exception— internal error, including a final refusal from the provider. Contact support with the time and therequestId.503 vcn-update-unavailable— transient provider failure. Retry the request.
The 409s are evaluated before the 400 invalid-vcn-request, in the order of the list.
Rules
Ceiling and top-up · Usage window · Request body · Evaluation order
curl -X PATCH "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 "Content-Digest: example_string" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-d '{
"limit": {
"value": 350,
"expectedValue": 0.01
},
"requestor": "automacao-fornecedores"
}'
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",
"Content-Digest": "example_string",
"Authorization": "Bearer YOUR_API_TOKEN"
}
data = {
"limit": {
"value": 350,
"expectedValue": 0.01
},
"requestor": "automacao-fornecedores"
}
response = requests.patch(url, headers=headers, json=data)
print(response.json())
const response = await fetch("https://api-sandbox.contasimples.com/credit-cards/v1/vcns/01JQ8ZP4C7D9F1G3H5J7K9J2MN", {
method: "PATCH",
headers: {
"Content-Type": "application/json",
"X-Partner-Id": "ptn_01JQ8ZK7X4M8N2P5R6T7V8W9XY",
"Signature-Input": "example_string",
"Signature": "example_string",
"Content-Digest": "example_string",
"Authorization": "Bearer YOUR_API_TOKEN"
},
body: JSON.stringify({
"limit": {
"value": 350,
"expectedValue": 0.01
},
"requestor": "automacao-fornecedores"
})
});
const data = await response.json();
console.log(data);
package main
import (
"fmt"
"net/http"
"bytes"
"encoding/json"
)
func main() {
data := []byte(`{
"limit": {
"value": 350,
"expectedValue": 0.01
},
"requestor": "automacao-fornecedores"
}`)
req, err := http.NewRequest("PATCH", "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("Content-Digest", "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::Patch.new(uri)
request['Content-Type'] = 'application/json'
request['X-Partner-Id'] = 'ptn_01JQ8ZK7X4M8N2P5R6T7V8W9XY'
request['Signature-Input'] = 'example_string'
request['Signature'] = 'example_string'
request['Content-Digest'] = 'example_string'
request['Authorization'] = 'Bearer YOUR_API_TOKEN'
request.body = '{
"limit": {
"value": 350,
"expectedValue": 0.01
},
"requestor": "automacao-fornecedores"
}'
response = http.request(request)
puts response.body
{
"vcnId": "01JQ8ZP4C7D9F1G3H5J7K9J2MN",
"limit": {
"value": 350,
"currency": "BRL"
},
"endDate": "2027-05-07",
"maxPurchaseQuantity": 10000,
"spendLimitPeriod": "TOTAL",
"updatedAt": "2027-03-04T09:15:40.000Z"
}
{
"code": "bad-request-exception",
"message": "Event failed validation",
"errors": [
{
"field": "body",
"message": "at least one updatable field is required"
}
]
}
{
"code": "invalid-vcn-request",
"message": "Unable to issue a VCN for this request: validity window must end after it starts"
}
{
"code": "invalid-vcn-request",
"message": "Unable to issue a VCN for this request: end date must fall within the maximum validity window from issuance"
}
{
"code": "invalid-vcn-request",
"message": "Unable to issue a VCN for this request: end date must not exceed the funding card expiration"
}
{
"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": "updateVcn"
},
"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": "vcn-expired",
"message": "The VCN validity window has ended; issue a new VCN."
}
{
"code": "vcn-not-active",
"message": "The VCN is not active and cannot be updated."
}
{
"code": "vcn-limit-conflict",
"message": "The current limit does not match expectedValue; re-read the VCN and retry."
}
{
"code": "vcn-not-updatable",
"message": "This VCN type does not accept updates."
}
{
"code": "internal-exception",
"message": "An unexpected error occurred on the server"
}
{
"code": "vcn-update-unavailable",
"message": "The VCN update could not be completed; retry the request."
}
/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.
Hash of the request body in the RFC 9530 format, with sha-256 or sha-512, for example sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=:. It is required when the request has a body and the credential has a public key, and in that case Signature-Input must include the content-digest component.
Top-up or adjustment of the spending ceiling.
New end of the window, YYYY-MM-DD, inclusive, as a Brasília day; it can go up or down. It cannot be earlier than today, must come after startDate and follows the issuance limits. See Date limits. To close the card, use Cancel VCN.
Maximum number of authorizations, up to 100000.
New ceiling period: TOTAL, MONTHLY or DAILY. Omitted, it keeps the current one. Changing the period does not reset what was spent.
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.
Hash of the request body in the RFC 9530 format, with sha-256 or sha-512, for example sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=:. It is required when the request has a body and the credential has a public key, and in that case Signature-Input must include the content-digest component.
Body
Top-up or adjustment of the spending ceiling.
New end of the window, YYYY-MM-DD, inclusive, as a Brasília day; it can go up or down. It cannot be earlier than today, must come after startDate and follows the issuance limits. See Date limits. To close the card, use Cancel VCN.
2027-06-30New ceiling period: TOTAL, MONTHLY or DAILY. Omitted, it keeps the current one. Changing the period does not reset what was spent.
TOTALMONTHLYDAILYWho 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.
Ceiling in effect after the operation — store it and add the next credit on top of it.
Current end of the usage window, YYYY-MM-DD — the same name and the same format as the field on issuance. Inclusive: the card authorizes until the end of that day, in Brasília time.
Effective value in effect.
Period in effect after the operation — the one sent in this call or the one already in effect.
TOTALMONTHLYDAILYTimestamp of this update (UTC).