Abertura de Contas (Onboarding)

As APIs de Accreditation permitem abrir contas para os seus clientes finais — pessoas físicas (PF) e pessoas jurídicas (PJ) — de forma programática, com verificação de identidade por biometria facial.

Habilitação

As APIs de onboarding estão em rollout controlado. Solicite a habilitação para o seu tenant ao nosso time de suporte antes de integrar.

Como funciona

O processo tem três grandes etapas:

Verificação de identidade (biometria facial) — cada pessoa física envolvida (o titular no PF; cada sócio no PJ) precisa ter a identidade verificada por biometria facial.
Documentos societários (só PJ) — envie os PDFs exigidos pelo company.legalForm via POST /v1/accreditations/{id}/documents (em paralelo com a biometria). Detalhes em Abertura PJ.
Análise — dependendo do fluxo, a abertura é aprovada automaticamente ou passa por análise prévia de um analista.
Abertura da conta no liquidante — após aprovação, a conta é aberta e vinculada automaticamente ao seu tenant. Você recebe o accountId definitivo e pode começar a operar (PIX, boletos, extrato etc.).

CPF que já tem conta

Para PF, se o CPF já for correntista não existe conta nova a abrir. Para tenants com portabilidade automática habilitada (depende de contrato; não vem ligada), a accreditation nasce em PENDING_CONSENT e devolve um link para o titular autorizar que você opere a conta que ele já tem — com verificação de identidade e divulgação de saldo antes do aceite. Sem essa habilitação, a accreditation falha com existing_partner_account e a portabilidade é solicitada ao suporte. Veja Titular que já tem conta.

Existem dois fluxos de biometria:

Fluxo	Como funciona	Aprovação
Biometria CorpX (padrão)	Nós geramos um link de captura facial (powered by Unico) para cada pessoa. Você entrega o link ao usuário final, que faz a jornada de captura no navegador ou celular.	PF: automática após a facial aprovada. PJ: análise prévia.
Biometria própria (alternativo)	Você já coleta biometria facial com uma plataforma parceira (Unico, SERPRO, IDWALL, SUMSUB, ClearSale, CAF, Valid) e envia a evidência exportada + metadados para validarmos. O usuário final confirma um termo de aceite em página hospedada por nós.	Sempre passa por análise prévia. Requer habilitação específica no seu tenant.

Padrão recomendado

O fluxo padrão com a biometria CorpX é o caminho mais simples: você só precisa entregar um link ao usuário final e aguardar os webhooks. O fluxo de biometria própria exige habilitação adicional — veja Biometria própria (BYO).

Máquina de estados

Toda accreditation percorre a seguinte máquina de estados:

Status

Status	Significado	Ação esperada do integrador
`PENDING_BIOMETRY`	Aguardando a biometria facial de uma ou mais pessoas.	Entregue o link de facial (ou de aceite) a cada pessoa pendente. Reenvie se necessário.
`PENDING_CONSENT`	Só PF, e só com portabilidade automática habilitada: o CPF já tem conta, então não há conta nova a abrir — o titular precisa autorizar você a operar a conta existente.	Entregue o `consentLink` ao titular. Detalhes em Titular que já tem conta.
`BIOMETRY_APPROVED`	Todas as biometrias aprovadas. Estado transitório.	Nenhuma — aguarde o próximo webhook.
`PENDING_REVIEW`	Aguardando análise prévia de um analista.	Nenhuma — aguarde. O prazo típico é de 1 dia útil.
`INTEGRATING`	Conta sendo aberta no liquidante. Estado transitório.	Nenhuma — aguarde.
`ACTIVE`	Conta aberta e pronta para operar.	Guarde o `accountId` e comece a operar.
`FAILED`	Processo encerrado sem abertura de conta.	Verifique `errorReason`. Em `consent_*`, o titular não autorizou (ou não concluiu) o acesso à conta que já tinha. Nos demais casos, retry de biometria ou nova accreditation.

Acompanhando o progresso

Você tem duas formas complementares de acompanhar cada accreditation:

Webhooks (recomendado) — o evento accreditation.updated é emitido a cada transição de estado, além de eventos específicos (link de facial criado, conta ativa, falha). Veja Webhooks de Onboarding.
Polling — GET /v1/accreditations/pf e GET /v1/accreditations/pj retornam o status agregado e o detalhe por pessoa (estado da biometria, link, expiração).

O campo opcional callbackUri traz o titular de volta ao seu app quando ele termina a etapa dele, com o desfecho na URI — útil para a experiência, mas não substitui nenhuma das duas formas acima. Veja Retorno ao seu app.

Vínculo com o seu tenant

O CPF/CNPJ só é atrelado ao tenant após a biometria (ou aceite BYO) ser confirmada. Enquanto PENDING_BIOMETRY, não há accountId e o POST não deduplica: repetir com o mesmo documento cria outra accreditation (201). Use POST /v1/accreditations/{id}/cancel para encerrar pendências abandonadas (FAILED / errorReason=cancelled).

Depois da confirmação, a conta aberta no liquidante fica automaticamente vinculada ao tenant que criou a accreditation — sem passo adicional de ativação. Um novo POST com o documento já claimado pelo seu próprio tenant retorna 409 already_accredited.

Conta compartilhada entre tenants

Uma conta PF pode ser operada por mais de um tenant, quando o titular autoriza cada um deles pelo fluxo de consent (Titular que já tem conta). Nesse caso:

É a mesma conta — saldo, extrato e chaves Pix são compartilhados. Cada tenant tem seu próprio accountId apontando para ela.
Todos os tenants autorizados recebem os webhooks de cada movimento. Operações originadas fora da sua API (por outro tenant autorizado ou pelo próprio titular) chegam com external: true.
Autorizações anteriores não são revogadas quando um novo tenant é autorizado. Se você já operava a conta e recebe account.shared_access.granted, outro tenant passou a operá-la também — se isso não faz sentido para o seu caso, fale com o suporte.
O titular pode revogar qualquer um dos acessos pelo suporte; a partir daí as chamadas do tenant revogado para aquela conta respondem 403.

Como funciona​

Máquina de estados​

Status​

Acompanhando o progresso​

Vínculo com o seu tenant​

Conta compartilhada entre tenants​

Próximos passos​