API BaaSAccreditations

Cancel a pending accreditation

Cancels an accreditation that is still in `PENDING_BIOMETRY` or `PENDING_CONSENT` (before the CPF/CNPJ is bound to the tenant). The workflow ends as `FAILED` with `errorReason=cancelled` and emits `accreditation.updated` / `accreditation.failed`. Cancelling a `PENDING_CONSENT` accreditation also invalidates the authorization link already delivered to the account holder. Idempotent when already cancelled (`200` with the failed detail). Returns `409 invalid_state` for any other status. **BaaS integrators only.**

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

accreditationIdstringRequired

Accreditation identifier (acr_*).

Headers

X-Tenant-IdstringRequired
Tenant context used for authorization and routing.
Idempotency-KeystringOptional

Optional client-generated idempotency token (recommended for safe retries).

Request

This endpoint expects an object.
reasonstringOptional

Optional free-text reason stored in errorMessage.

Response

Accreditation cancelled (or already cancelled).

accreditationIdstringOptional
accountIdstringOptional

Account id — usable in all banking endpoints once status is ACTIVE.

typeenumOptional
documentstringOptional
statusenumOptional
Accreditation lifecycle status.
biometryModeenumOptional

unico = CorpX-managed facial biometrics (default); external = provider enabled by CorpX on request.

legalFormenumOptional

PJ only — corporate form from create.

documentslist of objectsOptional

PJ only — uploaded company PDFs.

requiredDocumentKindslist of enumsOptional

PJ only — kinds required for this legalForm (operator approve gate).

missingDocumentKindslist of enumsOptional

PJ only — required kinds not yet uploaded.

documentsOverridebooleanOptional
true when an operator forced approve with incomplete docs.
documentsOverrideBystringOptional
documentsOverrideReasonstringOptional
documentsOverrideMissinglist of stringsOptional
documentsOverrideAtdatetimeOptional
callbackUristringOptional

Optional. Where to send the account holder back to when the step is finished (facial capture, terms acceptance or portability authorization). Without it the holder ends on a CorpX completion page, as before.

The URI must be registered for your tenant by CorpX support before the first use, and the match is exact — no wildcards, no prefix matching. An unregistered URI is rejected at creation time with 400 invalid_callback_uri.

Accepted: https:// and your application’s own scheme (deeplink). Rejected: http://, javascript:, data:, file:, credentials in the URI, fragments (#), localhost, private/link-local IP ranges and internal suffixes (.local, .internal).

On return, CorpX appends accreditationId, outcome, personId (for per-person steps) and remainingPeople (when the accreditation has more than one person). These parameters are not proof of anything: they travel in the address bar and the holder can edit them. Any decision with an effect must rely on the webhook or on GET /v1/accreditations/{accreditationId}.

personslist of objectsOptional
errorReasonstringOptional
errorMessagestringOptional
partnerobjectOptional

Raw refusal from the banking provider, present only when a FAILED accreditation was refused by it. It is the same block delivered in the accreditation.failed webhook — the query never shows less than the webhook. All three keys are optional: the block mirrors what the provider sent, and some refusals carry message only. Informative — branch your code on errorReason, not on this.

createdAtdatetimeOptional
updatedAtdatetimeOptional

Errors

404
Not Found Error
409
Conflict Error
500
Internal Server Error