Account opening

Onboarding Webhooks

All onboarding events follow the platform’s standard webhook envelope (same delivery format, authentication, retries and idempotency). This page documents the accreditation-specific events.

Events

EventWhen it is emitted
accreditation.pf.createdA PF accreditation was created.
accreditation.pj.createdA PJ accreditation was created.
accreditation.biometry.link.createdA facial capture link was generated for a person (emitted per person; re-emitted on retry).
accreditation.acceptance.link.createdA terms acceptance link was generated for a person (only in flows enabled on request by CorpX).
accreditation.consent.link.createdAn authorization link was generated because the CPF already has an account (re-emitted on retry).
account.shared_access.grantedAnother tenant started operating an account you already operated, authorized by the holder.
accreditation.updatedEvery state transition of the accreditation. Source of truth for progress.
accreditation.activeAccount opened successfully — accountId ready to operate.
accreditation.failedProcess ended without opening an account.
Recommendation

Subscribe to accreditation.updated as the source of truth for progress, and use accreditation.active / accreditation.failed as terminal triggers in your system. The link events are meant to automate delivering links to end users.

callbackUri does not replace these events

If you use the return to your app, the outcome that arrives in the URI is a UI hint: it travels in the address bar and the holder can edit it. Use it only to decide which screen to show when the user comes back. Every trigger with an effect in your system still comes from here — or from GET /v1/accreditations/{accreditationId}.

accreditation.updated

Emitted on every state transition, with the previous status, the current one and per-person details.

{
  "id": "evt_acr_upd_001",
  "type": "accreditation.updated",
  "occurredAt": "2026-07-07T18:20:00.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "c283eb5a-58da-47ef-844a-f36e51f078d8",
  "data": {
    "accreditationId": "acr_9f8e7d6c5b4a",
    "type": "pf",
    "document": "12345678901",
    "previousStatus": "PENDING_BIOMETRY",
    "status": "INTEGRATING",
    "persons": [
      {
        "cpf": "12345678901",
        "name": "Maria da Silva",
        "biometryStatus": "APPROVED"
      }
    ]
  }
}
data fieldDescription
accreditationIdAccreditation ID.
typepf or pj.
documentHolder’s CPF (PF) or CNPJ (PJ).
previousStatus / statusState transition (vocabulary from the Overview).
persons[]Per-person details: cpf, name, biometryStatus (PENDING, APPROVED, FAILED, EXPIRED) and, when a terms acceptance is involved, acceptanceStatus (PENDING, ACCEPTED).
errorReasonPresent when status = FAILED.

accreditation.biometry.link.created

Emitted when a facial capture link is generated for a person (at accreditation creation and on each retry).

{
  "id": "evt_acr_link_001",
  "type": "accreditation.biometry.link.created",
  "occurredAt": "2026-07-07T18:00:05.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "c283eb5a-58da-47ef-844a-f36e51f078d8",
  "data": {
    "accreditationId": "acr_9f8e7d6c5b4a",
    "type": "pf",
    "cpf": "12345678901",
    "name": "Maria da Silva",
    "biometryLink": "https://cadastro.unico.app/process/abc123...",
    "linkExpiresAt": "2026-07-14T18:00:00Z"
  }
}

For PJ, this event is emitted once per partner — use the cpf to know who each link belongs to.

accreditation.acceptance.link.created

Emitted when a terms acceptance link is generated for a person. Only happens in flows enabled on request by CorpX; the default flow never emits it.

{
  "id": "evt_acr_acc_001",
  "type": "accreditation.acceptance.link.created",
  "occurredAt": "2026-07-07T18:05:00.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "c283eb5a-58da-47ef-844a-f36e51f078d8",
  "data": {
    "accreditationId": "acr_9f8e7d6c5b4a",
    "type": "pf",
    "cpf": "12345678901",
    "name": "Maria da Silva",
    "acceptanceLink": "https://tenant.api.corpx.com/v1/accreditations/accept/tok_...",
    "linkExpiresAt": "2026-07-14T18:00:00Z"
  }
}

accreditation.consent.link.created

Emitted when the CPF already has an account and the accreditation starts as PENDING_CONSENT: instead of opening a new account, the holder must authorize you to operate the existing one. Deliver the consentLink to them. Re-emitted on every retry.

{
  "id": "acr-acr_5c4b3a2f1e0d-consent-12345678901-1",
  "type": "accreditation.consent.link.created",
  "occurredAt": "2026-07-23T18:00:05.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "data": {
    "accreditationId": "acr_5c4b3a2f1e0d",
    "type": "pf",
    "cpf": "12345678901",
    "name": "Maria da Silva",
    "consentId": "cns_8f2a1c9d4b70",
    "consentLink": "https://tenant.api.corpx.com/v1/accreditations/consent/cst_...",
    "linkExpiresAt": "2026-07-30T18:00:00Z",
    "status": "PENDING_CONSENT"
  }
}

Journey details in Holder who already has an account.

accreditation.active

Terminal success event — the account is ready to operate.

{
  "id": "evt_acr_active_001",
  "type": "accreditation.active",
  "occurredAt": "2026-07-07T18:25:41.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "c283eb5a-58da-47ef-844a-f36e51f078d8",
  "data": {
    "accreditationId": "acr_9f8e7d6c5b4a",
    "type": "pf",
    "document": "12345678901",
    "status": "ACTIVE",
    "accountId": "c283eb5a-58da-47ef-844a-f36e51f078d8"
  }
}

When the accreditation came from the consent flow, data carries two extra fields:

data fieldDescription
sharedAccounttrue — the account already existed and remains operated by whoever the holder had already authorized. Balance and statement are shared.
partnerAccountIdHolder identifier at the settlement partner, common to every authorized tenant. Useful for reconciliation.

account.shared_access.granted

Emitted to the tenants that already operated an account when the holder authorizes a new tenant to operate it too. Your access does not change — this event exists so that you know the account is now being moved by someone else as well.

{
  "id": "acr-acr_5c4b3a2f1e0d-shared-tenant-acme",
  "type": "account.shared_access.granted",
  "occurredAt": "2026-07-23T18:40:00.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "c283eb5a-58da-47ef-844a-f36e51f078d8",
  "data": {
    "accountId": "c283eb5a-58da-47ef-844a-f36e51f078d8",
    "tenantId": "tenant-acme",
    "partnerAccountId": "hld_7c1e...",
    "grantedAt": "2026-07-23T18:40:00Z",
    "reason": "account_holder_authorized_another_tenant"
  }
}
data fieldDescription
accountIdYour account (the identifier you already use), not the one of the tenant that joined.
partnerAccountIdHolder at the settlement partner — this is what evidences it is the same account.
grantedAtMoment of the holder’s authorization.
reasonaccount_holder_authorized_another_tenant.
Don't recognize it?

If the sharing does not make sense for your case, contact support: the holder can revoke the granted access, and from then on the revoked tenant’s calls for that account return 403.

accreditation.failed

Terminal failure event — the process ended without opening an account.

{
  "id": "evt_acr_failed_001",
  "type": "accreditation.failed",
  "occurredAt": "2026-07-08T10:00:00.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "c283eb5a-58da-47ef-844a-f36e51f078d8",
  "data": {
    "accreditationId": "acr_9f8e7d6c5b4a",
    "type": "pf",
    "document": "12345678901",
    "status": "FAILED",
    "errorReason": "biometry_expired",
    "errorMessage": "Facial biometrics not completed within the 7-day deadline"
  }
}

Common errorReason values:

errorReasonMeaning
biometry_failedFacial biometrics rejected.
biometry_expiredFacial link expired without completion.
evidence_invalidExternal biometrics evidence not validated with the partner (flows enabled on request).
acceptance_timeoutAcceptance term not confirmed in time (flows enabled on request).
cancelledCancelled by the integrator via POST /v1/accreditations/{id}/cancel (still PENDING_BIOMETRY or PENDING_CONSENT).
review_rejectedRejected during prior review.
partner_rejectedRejected by the settlement partner during account opening.
partner_validation_failedThe provider rejected a registration value. See the partner block below.
partner_unavailableProvider outage. Transient: resend the accreditation.
consent_declinedThe holder declined to authorize access to the account they already had.
consent_expiredThe holder did not complete the authorization in time (7-day link, 30-day journey).
consent_facial_failedThe identity verification did not confirm the person as the CPF holder.
consent_link_failedThe authorization could not be prepared or completed (e.g. holder data diverged between the request and the authorization). Contact support.
castle_denyThe device risk assessment blocked the acceptance — both on the acceptance term and on the portability authorization. Contact support.
existing_partner_accountCPF/CNPJ that already has an account. Portability is manual: the holder must request it from support. For PF, if your tenant has automatic portability enabled, this reason does not occur — the path is the consentLink. There is no hosted authorization flow for PJ.

When the refusal comes from the provider, data also carries a partner block with what it reported — the same block is returned by GET /v1/accreditations/{id}, so the query and the webhook never disagree:

"partner": {
  "code": "request.body.invalid",
  "field": "address.number",
  "message": "A solicitação é inválida: O número não pode exceder 10 caracteres."
}

All three keys are optional: the block mirrors what the provider sent, and some refusals arrive with message only. Use it for logs and support — your code should still branch on errorReason.

accreditation.pf.created / accreditation.pj.created

Emitted when the accreditation is created (workflow start), as an asynchronous confirmation of the POST. Subscribe in the portal (Settings → Webhooks) or via PUT on the subscription.

{
  "id": "acr-acr_1a2b3c4d5e6f-created",
  "type": "accreditation.pj.created",
  "occurredAt": "2026-07-07T18:00:00.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "data": {
    "accreditationId": "acr_1a2b3c4d5e6f",
    "type": "pj",
    "document": "12345678000199",
    "status": "PENDING_BIOMETRY",
    "biometryMode": "external"
  }
}