Abertura de contas

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

CampoTipoObrigatórioDescrição
person.namestringSimNome completo do titular.
person.cpfstringSimCPF (11 dígitos, sem pontuação).
person.birthDatestringSimData de nascimento (YYYY-MM-DD).
person.emailstringSimE-mail do titular.
person.phonestringSimTelefone no padrão DDI + DDD + número (ex.: +5511999998888).
person.monthlyIncomenumberNãoRenda mensal declarada (BRL).
address.*objectSimEndereço completo. neighborhood (bairro) é obrigatório (ou district legado). cityIbgeCode é o código IBGE do município com 7 dígitos.
callbackUristringNãoPara 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.

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:

  1. accreditation.updated — PENDING_BIOMETRY → INTEGRATING;
  2. 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"
    }
  ]
}

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"
}
CampoDescrição
statusPENDING_CONSENT — aguardando a autorização do titular.
persons[].consentLinkPágina de autorização. Entregue ao titular como você já entrega o link de facial.
persons[].consentStatusPENDING, ACCEPTED, DECLINED, DENIED ou EXPIRED.
persons[].consentExpiresAtValidade 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ê

  1. 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.
  2. Verificação de identidade: selfie com prova de vida, validada contra bases oficiais pelo CPF. Sem isso, a página não avança.
  3. 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ê.
  4. 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.

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.