VCNUpdate VCN

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 requestor and only what you want to change, at least one field besides it; anything you do not send stays as is.
  • ⚠️ In the TOTAL period, limit.value is 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 endDate does not close it.

Errors

  • 400 bad-request-exception — invalid body, with errors[]: a missing requestor, no field besides it, a value below 0.01, a key outside the updatable list or an invalid vcnId. See Request body.
  • 400 invalid-vcn-request — the new endDate breaks a window limit; the reason comes in message. See Date limits.
  • 400 bad-request-exception — missing or malformed X-Partner-Id (field headers.x-partner-id). See Platform identification.
  • 403 caller-not-authorized — the X-Partner-Id partner is not bound to your credential (details.reason PARTNER_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 not CUSTOM.
  • 409 vcn-not-active — the VCN is BLOCKED or CANCELLED. A cancelled one does not come back; for a blocked one, contact Conta Simples. Check the status with Get VCN.
  • 409 vcn-expired — the window has ended (from the day after endDate). 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 without expectedValue. 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 the requestId.
  • 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"
}'
{
  "vcnId": "01JQ8ZP4C7D9F1G3H5J7K9J2MN",
  "limit": {
    "value": 350,
    "currency": "BRL"
  },
  "endDate": "2027-05-07",
  "maxPurchaseQuantity": 10000,
  "spendLimitPeriod": "TOTAL",
  "updatedAt": "2027-03-04T09:15:40.000Z"
}
PATCH
/credit-cards/v1/vcns/{vcnId}
PATCH
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
path
vcnIdstring
Required

VCN identifier returned at issuance (vcnId field).

Content-Typestring
Required

The media type of the request body

Options: application/json
header
X-Partner-Idstring
Required

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.

Pattern: ^ptn_[0-9A-HJKMNP-TV-Z]{26}$
header
Signature-Inputstring

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.

header
Signaturestring

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.

header
Content-Digeststring

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.

limitobject

Top-up or adjustment of the spending ceiling.

endDatestring

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.

Format: date
maxPurchaseQuantityinteger

Maximum number of authorizations, up to 100000.

Min: 1 • Max: 100000
spendLimitPeriodstring

New ceiling period: TOTAL, MONTHLY or DAILY. Omitted, it keeps the current one. Changing the period does not reset what was spent.

Options: TOTAL, MONTHLY, DAILY
requestorstring
Required

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.

Min length: 1 • Max length: 100
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

Path Parameters

vcnIdstring
Required

VCN identifier returned at issuance (vcnId field).

Example:
01JQ8ZP4C7D9F1G3H5J7K9J2MN

Headers

X-Partner-Idstring
Required

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.

Example:
ptn_01JQ8ZK7X4M8N2P5R6T7V8W9XY
Signature-Inputstring

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.

Signaturestring

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.

Content-Digeststring

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

application/json
limitobject

Top-up or adjustment of the spending ceiling.

endDatestring

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.

Example:
2027-06-30
maxPurchaseQuantityinteger

Maximum number of authorizations, up to 100000.

Example:
10000
spendLimitPeriodstring

New ceiling period: TOTAL, MONTHLY or DAILY. Omitted, it keeps the current one. Changing the period does not reset what was spent.

Allowed values:TOTALMONTHLYDAILY
requestorstring
Required

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.

Example:
agente@exemplo.test

Responses

vcnIdstring
Required

Echo of the identifier.

limitstring
Required

Ceiling in effect after the operation — store it and add the next credit on top of it.

endDatestring
Required

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.

maxPurchaseQuantityinteger
Required

Effective value in effect.

spendLimitPeriodstring
Required

Period in effect after the operation — the one sent in this call or the one already in effect.

Allowed values:TOTALMONTHLYDAILY
updatedAtstring
Required

Timestamp of this update (UTC).