Account Onboarding

The Accreditation APIs let you open accounts for your end customers — individuals (PF) and companies (PJ) — programmatically, with identity verification through facial biometrics.

Enablement

The onboarding APIs are in controlled rollout. Ask our support team to enable them for your tenant before integrating.

How it works

The process has four major stages:

1. Identity verification (facial biometrics) — every individual involved (the holder for PF; every partner for PJ) must have their identity verified through facial biometrics.
2. Company documents (PJ only) — upload the PDFs required by company.legalForm via POST /v1/accreditations/{id}/documents (in parallel with biometrics). Details in PJ account opening.
3. Review — depending on the flow, the opening is approved automatically or goes through prior review by an analyst.
4. Account opening at the settlement partner — after approval, the account is opened and automatically bound to your tenant. You receive the final accountId and can start operating (PIX, boletos, statement, etc.).

CPF that already has an account

For PF, if the CPF is already an account holder there is no new account to open. For tenants with automatic portability enabled (contractual; not on by default), the accreditation starts as PENDING_CONSENT and returns a link for the holder to authorize you to operate the account they already have — with identity verification and balance disclosure before the authorization. Without it, the accreditation fails with existing_partner_account and portability is requested from support. See Holder who already has an account.

There are two biometrics flows:

Flow	How it works	Approval
CorpX biometrics (default)	We generate a facial capture link (powered by Unico) for each person. You deliver the link to the end user, who completes the capture journey in the browser or on their phone.	PF: automatic once the facial check is approved. PJ: prior review.
Bring Your Own biometrics (alternative)	You already collect facial biometrics with a partner platform (Unico, SERPRO, IDWALL, SUMSUB, ClearSale, CAF, Valid) and send us the exported evidence + metadata for validation. The end user confirms an acceptance term on a page hosted by us.	Always goes through prior review. Requires specific enablement on your tenant.

Recommended default

The default flow with CorpX biometrics is the simplest path: you only need to deliver a link to the end user and wait for the webhooks. The BYO flow requires additional enablement — see Bring Your Own Biometrics.

State machine

Every accreditation goes through the following state machine:

Statuses

Status	Meaning	Expected integrator action
PENDING_BIOMETRY	Waiting for facial biometrics from one or more persons.	Deliver the facial (or acceptance) link to each pending person. Resend if needed.
PENDING_CONSENT	PF only, and only with automatic portability enabled: the CPF already has an account, so there is no new account to open — the holder must authorize you to operate the existing one.	Deliver the consentLink to the holder. Details in Holder who already has an account.
BIOMETRY_APPROVED	All biometrics approved. Transitional state.	None — wait for the next webhook.
PENDING_REVIEW	Waiting for prior review by an analyst.	None — wait. Typical turnaround is 1 business day.
INTEGRATING	Account being opened at the settlement partner. Transitional state.	None — wait.
ACTIVE	Account opened and ready to operate.	Store the accountId and start operating.
FAILED	Process ended without opening an account.	Check errorReason. Depending on the reason, retry the biometrics or open a new accreditation with corrected data.

Tracking progress

You have two complementary ways to track each accreditation:

• Webhooks (recommended) — the accreditation.updated event is emitted on every state transition, plus specific events (facial link created, account active, failure). See Onboarding Webhooks.
• Polling — GET /v1/accreditations/pf and GET /v1/accreditations/pj return the aggregated status and per-person details (biometrics state, link, expiration).

The optional callbackUri field brings the holder back to your app when they finish their step, with the outcome in the URI — useful for the experience, but it does not replace either of the two ways above. See Returning to your app.

Tenant binding

The CPF/CNPJ is only bound to the tenant after biometry (or BYO acceptance) is confirmed. While PENDING_BIOMETRY, there is no accountId and POST does not deduplicate: repeating with the same document creates another accreditation (201). Cancel abandoned pendings with POST /v1/accreditations/{id}/cancel (FAILED / errorReason=cancelled).

After confirmation, the settlement account is automatically bound to the tenant that created the accreditation — no extra activation step. A further POST for a document already claimed by your own tenant returns 409 already_accredited.

Accounts shared between tenants

A PF account can be operated by more than one tenant, when the holder authorizes each of them through the consent flow (Holder who already has an account). In that case:

• It is the same account — balance, statement and Pix keys are shared. Each tenant has its own accountId pointing to it.
• Every authorized tenant receives the webhooks for each movement. Operations originated outside your API (by another authorized tenant or by the holder) arrive with external: true.
• Previous authorizations are not revoked when a new tenant is authorized. If you already operated the account and receive account.shared_access.granted, another tenant started operating it too — if that does not make sense for your case, talk to support.
• The holder can revoke any of these accesses through support; from then on the revoked tenant's calls for that account return 403.

Next steps

• PF account opening
• PJ account opening
• Bring Your Own Biometrics
• Returning to your app (callbackUri)
• Onboarding Webhooks