VCNCancel VCN

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 200 with the same body and the same updatedAt, with no new effect.
  • After cancellation, Reveal VCN card data answers 409 vcn-cancelled and, for CUSTOM, Update VCN answers 409 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 vcnId starts answering 404 on every route.

Errors

  • 400 bad-request-exception — invalid vcnId in the path (field path.vcnId).
  • 400 bad-request-exception — invalid body, with errors[]: no body, a missing or out-of-bounds requestor, or a key other than requestor. See Request body.
  • 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.
  • 500 internal-exception — a final provider refusal (the VCN remains valid) or an internal timeout (the cancellation may have completed). Retry the DELETE or check the status with Get VCN; if it is still ACTIVE, contact support with the time, the requestId and the vcnId.
  • 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 show ACTIVE, and a new issuance on the same key answers 409 vcn-already-issued. Retry the DELETE; if it persists, contact support (the vcnId comes in message).

Rules

Retrying calls · Idempotency and reissuance · Request body

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"
}'
{
  "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"
}
DELETE
/credit-cards/v1/vcns/{vcnId}
DELETE
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.

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.

Body

application/json
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.

referencestring
Required

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.

typestring
Required

What the card is tied to.

Allowed values:HOTELAERIALCUSTOM
statusstring
Required

ACTIVE, 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.

Allowed values:ACTIVEBLOCKEDCANCELLED
startDatestring
Required

Start of the usage window, YYYY-MM-DD, as a calendar day in Brasília time — the same value returned at issuance.

endDatestring
Required

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.

limitstring
Required

Spending ceiling in effect — not a balance nor the available amount: spending is not returned by this API.

amountstring

Booking cost — present only for HOTEL/AERIAL; absent for CUSTOM. It is the only optional field of this body.

maxPurchaseQuantityinteger
Required

Maximum number of authorizations in effect.

spendLimitPeriodstring
Required

Ceiling period in effect — always present.

Allowed values:TOTALMONTHLYDAILY
createdAtstring
Required

Issuance 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.

updatedAtstring
Required

Instant of the latest change — update or cancellation —, in UTC. Repeating the cancellation of an already-cancelled VCN does not change it.