Abertura de Conta — Pessoa Física (PF)

Este guia mostra o passo a passo para abrir uma conta de pessoa física usando o fluxo padrão de biometria CorpX: nós geramos um link de captura facial, você entrega ao usuário final e, com a facial aprovada, a conta é aberta automaticamente — sem análise manual.

Fluxo

Passo 1: Criar a accreditation

Request

curl -X POST "https://tenant.api.corpx.com/v1/accreditations/pf" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: tenant-suaempresa" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: onboard-cliente-12345" \
  -d '{
    "person": {
      "name": "Maria da Silva",
      "cpf": "12345678901",
      "birthDate": "1990-05-20",
      "email": "maria@email.com",
      "phone": "+5511999998888",
      "monthlyIncome": 5000.00
    },
    "address": {
      "zipCode": "01310100",
      "street": "Avenida Paulista",
      "number": "1000",
      "complement": "Apto 42",
      "neighborhood": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "cityIbgeCode": "3550308"
    }
  }'

Parâmetros

Campo	Tipo	Obrigatório	Descrição
`person.name`	string	Sim	Nome completo do titular.
`person.cpf`	string	Sim	CPF (11 dígitos, sem pontuação).
`person.birthDate`	string	Sim	Data de nascimento (`YYYY-MM-DD`).
`person.email`	string	Sim	E-mail do titular.
`person.phone`	string	Sim	Telefone no padrão DDI + DDD + número (ex.: `+5511999998888`).
`person.monthlyIncome`	number	Não	Renda mensal declarada (BRL).
`address.*`	object	Sim	Endereço completo. `neighborhood` (bairro) é obrigatório (ou `district` legado). `cityIbgeCode` é o código IBGE do município com 7 dígitos.
`biometry`	object	Não	Somente para o fluxo de biometria própria.
`callbackUri`	string	Não	Para onde levar o titular de volta ao fim da jornada. Exige cadastro prévio junto ao suporte — ver Retorno ao seu app.

Limites PIX iniciais são aplicados automaticamente com valores padrão conservadores. Alteração de limite (aumento ou redução) exige solicitação manual ao suporte.

Resposta (201)

{
  "accreditationId": "acr_9f8e7d6c5b4a",
  "type": "pf",
  "status": "PENDING_BIOMETRY",
  "persons": [
    {
      "personId": "prs_3b1c9a7f2e4d",
      "cpf": "12345678901",
      "name": "Maria da Silva",
      "biometryStatus": "PENDING",
      "biometryLink": "https://cadastro.unico.app/process/abc123...",
      "linkExpiresAt": "2026-07-14T18:00:00Z"
    }
  ],
  "createdAt": "2026-07-07T18:00:00Z"
}

O personId é o identificador estável da pessoa dentro do credenciamento. Use-o para correlacionar o retorno ao seu app (ver Retorno ao seu app) — é ele, e não o CPF, que aparece na URI de volta.

Conta ainda não vinculada

Enquanto o status for PENDING_BIOMETRY, o CPF não é atrelado ao tenant e o accountId ainda não existe. O POST não deduplica — repetir com o mesmo CPF cria outra accreditation. Guarde o accreditationId e cancele pendências abandonadas com POST /v1/accreditations/{id}/cancel. O accountId só aparece após a biometria confirmada (webhooks accreditation.updated / accreditation.active).

Link assíncrono

O biometryLink é gerado em segundos, mas de forma assíncrona — em raras situações ele pode vir ausente na resposta do POST. Nesse caso, receba-o pelo webhook accreditation.biometry.link.created ou consulte o GET logo em seguida.

CPF que já tem conta

Se o CPF já for correntista e o seu tenant tiver a portabilidade automática habilitada, a resposta vem com status: "PENDING_CONSENT" e um consentLink em vez do biometryLink — não existe conta nova a abrir, e sim uma autorização do titular para você operar a conta que ele já tem. Sem essa habilitação (o padrão), a accreditation falha com existing_partner_account e a portabilidade é feita via suporte. Veja Titular que já tem conta mais abaixo.

Passo 2: Entregar o link de facial

Entregue o biometryLink ao usuário final pelo canal que preferir (dentro do seu app, WhatsApp, SMS, e-mail). A jornada de captura roda no navegador do celular, sem instalação de app.

O link expira em 7 dias (linkExpiresAt). Se expirar, use o endpoint de retry (Passo 4).
O mesmo link também é entregue no webhook accreditation.biometry.link.created.

Passo 3: Aguardar a conclusão

Assim que o usuário conclui a captura e a biometria é aprovada, a aprovação é automática — não há análise manual para PF no fluxo padrão. Acompanhe pelos webhooks:

accreditation.updated — PENDING_BIOMETRY → INTEGRATING;
accreditation.active — conta aberta; o accountId está pronto para operar.

Se a biometria for reprovada ou expirar, você recebe accreditation.updated com o detalhe da pessoa e pode fazer retry.

Você também pode consultar por polling:

curl -X GET "https://tenant.api.corpx.com/v1/accreditations/pf?document=12345678901" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: tenant-suaempresa"

{
  "items": [
    {
      "accreditationId": "acr_9f8e7d6c5b4a",
      "accountId": "c283eb5a-58da-47ef-844a-f36e51f078d8",
      "type": "pf",
      "status": "ACTIVE",
      "persons": [
        {
          "cpf": "12345678901",
          "name": "Maria da Silva",
          "biometryStatus": "APPROVED"
        }
      ],
      "createdAt": "2026-07-07T18:00:00Z",
      "updatedAt": "2026-07-07T18:25:41Z"
    }
  ]
}

Passo 4: Retry (link expirado ou biometria reprovada)

Se o link expirou ou a captura falhou, gere um novo link para a pessoa:

curl -X POST "https://tenant.api.corpx.com/v1/accreditations/acr_9f8e7d6c5b4a/persons/12345678901/retry" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: tenant-suaempresa"

A resposta traz o novo biometryLink e o novo linkExpiresAt. O evento accreditation.biometry.link.created também é reemitido.

Passo 5: Cancelar (pendência abandonada)

Se o usuário desistiu antes da biometria, cancele a accreditation enquanto o status for PENDING_BIOMETRY (ou PENDING_CONSENT):

curl -X POST "https://tenant.api.corpx.com/v1/accreditations/acr_9f8e7d6c5b4a/cancel" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: tenant-suaempresa" \
  -H "Content-Type: application/json" \
  -d '{"reason":"customer abandoned onboarding"}'

A accreditation termina como FAILED com errorReason=cancelled (webhooks accreditation.updated / accreditation.failed). Depois da biometria confirmada o cancelamento não é mais permitido (409 invalid_state).

Quando o CPF informado já é correntista, não há conta nova para abrir. O caminho passa a ser o titular autorizar você a operar a conta que ele já tem — e essa autorização é dada por ele mesmo, numa página nossa, com verificação de identidade.

O POST /v1/accreditations/pf é o mesmo: você não precisa detectar nada antes. A resposta é que muda.

Depende de habilitação contratual

A portabilidade automática não vem habilitada. Ela transfere o controle do dinheiro de uma conta que já existe, então depende de contrato específico e é liberada por tenant pelo nosso time.

Sem essa habilitação, o CPF já correntista continua terminando em FAILED com errorReason=existing_partner_account e a mensagem orientando o titular a solicitar a portabilidade ao suporte — nesse caso o processo é conduzido manualmente por nós, e nenhum consentLink é emitido.

Para habilitar, fale com o seu contato comercial na CorpX.

{
  "accreditationId": "acr_5c4b3a2f1e0d",
  "type": "pf",
  "status": "PENDING_CONSENT",
  "persons": [
    {
      "personId": "prs_3b1c9a7f2e4d",
      "cpf": "12345678901",
      "name": "Maria da Silva",
      "biometryStatus": "PENDING",
      "consentStatus": "PENDING",
      "consentLink": "https://tenant.api.corpx.com/v1/accreditations/consent/cst_...",
      "consentExpiresAt": "2026-07-30T18:00:00Z"
    }
  ],
  "createdAt": "2026-07-23T18:00:00Z"
}

Campo	Descrição
`status`	`PENDING_CONSENT` — aguardando a autorização do titular.
`persons[].consentLink`	Página de autorização. Entregue ao titular como você já entrega o link de facial.
`persons[].consentStatus`	`PENDING`, `ACCEPTED`, `DECLINED`, `DENIED` ou `EXPIRED`.
`persons[].consentExpiresAt`	Validade do link (7 dias). A jornada como um todo expira em 30 dias.

O mesmo link chega no webhook accreditation.consent.link.created — assine esse evento se a sua integração pega links por webhook, porque o accreditation.updated não carrega link nenhum.

Reenviar o POST não reemite o consent

Enquanto a jornada estiver em PENDING_CONSENT, repetir o POST /v1/accreditations/pf para o mesmo CPF responde 409 already_accredited — com accountId: null, status: "PENDING_CONSENT" e o accreditationId da jornada que está em andamento. Não é conta existente no seu tenant: é a autorização que ainda está pendente com o titular.

Para recuperar o link em vez de reenviar:

GET /v1/accreditations/{accreditationId} devolve o link atual em persons[].consentLink, com o consentExpiresAt.
POST /v1/accreditations/{accreditationId}/persons/{cpf}/retry reemite o link com validade nova de 7 dias (o mesmo endpoint do Passo 4), desde que a jornada de 30 dias não tenha expirado.

Se a intenção for realmente abandonar a jornada, cancele com POST /v1/accreditations/{accreditationId}/cancel (Passo 5) antes de criar outra.

Fluxo

O que o titular vê

Antes de qualquer captura, a página diz quem está pedindo acesso e o que a autorização permite — inclusive movimentar e sacar o dinheiro da conta.
Verificação de identidade: selfie com prova de vida, validada contra bases oficiais pelo CPF. Sem isso, a página não avança.
Só depois da identidade confirmada, aparecem número da conta e saldo atual — para ele autorizar sabendo exatamente qual dinheiro passa a ser operado por você.
Autorização explícita, registrada com data, hora, dispositivo e o saldo que foi exibido.

O aceite vale apenas na mesma sessão e no mesmo dispositivo que passou pela verificação de identidade. Encaminhar o link para outra pessoa, repetir o POST da página ou reaproveitar uma verificação antiga não autoriza nada.

Depois da autorização

Você recebe accreditation.active com sharedAccount: true e um accountId para operar normalmente. Dois pontos importantes:

É a mesma conta, não uma cópia: saldo, extrato e chaves Pix são os que já existiam. O accountId é o identificador dela no seu tenant.
Quem já operava a conta continua operando. Todos os tenants autorizados pelo titular recebem os webhooks de cada movimento — inclusive os de operações que não partiram da sua API (que chegam com external: true).

Se o titular não autorizar, a accreditation termina em FAILED com um destes errorReason: consent_declined, consent_expired, consent_facial_failed, castle_deny ou consent_link_failed (detalhe em Webhooks de Onboarding).

Revogação

O titular pode revogar o acesso concedido a qualquer momento pelo suporte. A partir da revogação, as chamadas do tenant revogado para aquela conta passam a responder 403 — a conta segue ativa para o titular e para os demais tenants autorizados.

Conta pronta

Com o status ACTIVE, a conta já está vinculada ao seu tenant e pronta para operar. Use o accountId nos demais endpoints da API — PIX, extrato, boletos, QR Codes etc.

dica

Guarde o par accreditationId + accountId no seu sistema. O accountId é o identificador que você usará em todas as operações bancárias dali em diante.

Fluxo​

Passo 1: Criar a accreditation​

Request​

Parâmetros​

Resposta (201)​

Passo 2: Entregar o link de facial​

Passo 3: Aguardar a conclusão​

Passo 4: Retry (link expirado ou biometria reprovada)​

Passo 5: Cancelar (pendência abandonada)​

Titular que já tem conta (consent)​

Resposta (201) em modo consent​

Fluxo​

O que o titular vê​

Depois da autorização​

Conta pronta​

Fluxo

Passo 1: Criar a accreditation

Request

Parâmetros

Resposta (201)

Passo 2: Entregar o link de facial

Passo 3: Aguardar a conclusão

Passo 4: Retry (link expirado ou biometria reprovada)

Passo 5: Cancelar (pendência abandonada)

Titular que já tem conta (consent)

Resposta (201) em modo consent

Fluxo

O que o titular vê

Depois da autorização

Conta pronta