> This page is for Internet banking (beta).

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.api.corpx.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.api.corpx.com/_mcp/server.

# Verificação de identidade

Esta API é paga à parte.

A API cria uma prova independente de conta para proteger redefinição de senha,
reset de segundo fator, transação de alto valor ou outra ação sensível. O
backend do banco cria a jornada para um CPF, o correntista faz a captura facial
e o backend consome a aprovação uma única vez antes de concluir a ação.

Há dois métodos de captura, escolhidos por `method` na criação:

* **`link`** (padrão): a API devolve um `verificationLink` que abre a página
  hospedada do provedor (Unico ou DracmaTrust).
* **`facetec_sdk`**: o app do banco embute o **SDK FaceTec v10**, abre a câmera
  e envia cada captura para `POST /v1/identity-verifications/{id}/facetec/process`.
  Exige `provider: dracma_trust`, a feature `identity_verification_facetec_sdk`
  e as chaves do SDK cadastradas pela CorpX. **Peça o pacote** (bundle id,
  application id, domínios) antes de embutir — o pedido e as linguagens
  aceitas estão no [guia de captura facial](/baas/guias/abertura-de-contas/captura-facial#pedir-o-sdk).
  O protocolo no app está em [Captura pelo SDK FaceTec](#captura-pelo-sdk-facetec).

> **Use a master, não a credencial da conta**
>
> Esta superfície é para a credencial **master M2M** do internet banking. A
> credencial filha, delegada para uma única conta, não pode criar, consultar nem
> consumir verificações. Nunca envie a master ao navegador ou ao app.

## Pré-requisitos

* token `client_credentials` da master;
* host `https://client.api.corpx.com` e os três headers de
  [assinatura](/ib/guias/autenticacao/assinatura-de-requisicoes);
* `X-Tenant-Id`;
* escopo `identity_verification.manage`;
* feature `identity_verification` habilitada para criar jornadas;
* `callbackUri` cadastrada em **Verificações de identidade** no painel, com comparação **exata**.

O download de evidências usa o escopo dedicado `kyc.read`.

## Criar

```bash
curl -X POST "https://client.api.corpx.com/v1/identity-verifications" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-Id: $TENANT_ID" \
  -H "X-Request-Timestamp: $TS" \
  -H "X-Content-SHA256: $BODY_SHA256" \
  -H "X-Request-Signature: $SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{
    "document": "12345678909",
    "purpose": "second_factor_reset",
    "referenceId": "reset_01J8Y6N7M8P9Q0R1S2T3",
    "displayMessage": "Confirme sua identidade para cadastrar o novo dispositivo.",
    "callbackUri": "https://ib.example.com/identity-verification/return",
    "ttlMinutes": 30,
    "consumeTtlMinutes": 10
  }'
```

`document` é um CPF de 11 dígitos. `referenceId` é obrigatório e identifica a
ação no seu sistema. As finalidades aceitas são `password_reset`,
`second_factor_reset`, `high_value_transaction` e `sensitive_action`.
`displayMessage` é texto simples opcional de até 240 caracteres.
`ttlMinutes` tem padrão 30 e `consumeTtlMinutes`, 10; ambos têm máximo 60.
`provider` (`unico` ou `dracma_trust`) e `method` (`link` ou `facetec_sdk`) são
opcionais; `referenceMatch` (`none`, `dracma` padrão ou `image`) só vale com
`facetec_sdk`.

Não envie `Idempotency-Key`: cada `POST` abre intencionalmente uma prova nova e
consome uma unidade da cota quando responde `201`.

Resposta `201` com `method: link`:

```json
{
  "verificationId": "idv_01J8Y7C8D9E0F1G2H3J4",
  "status": "PENDING",
  "provider": "unico",
  "method": "link",
  "verificationLink": "https://tenant.api.corpx.com/v1/identity-verifications/verify#capability-redacted",
  "expiresAt": "2026-09-24T14:30:00Z"
}
```

> **Cota por tenant e por tipo, não por conta**
>
> A cota é contada **por tipo**, por tenant e por mês-calendário BRT, somando
> todas as contas do internet banking: `link_unico`, `link_dracma`, `liveness`
> (`facetec_sdk` + `none`), `face_match_image` (`facetec_sdk` + `image`) e
> `face_match_cpf` (`facetec_sdk` + `dracma`). Os tipos `link` nascem com **10**;
> os tipos do SDK nascem com **0** e respondem `403
> identity_verification_kind_not_enabled` até a CorpX liberar. Cada `201` conta e
> nunca é estornado, mesmo se a jornada falhar, expirar ou não for consumida. Cota
> fechada responde HTTP `429` com `identity_verification_monthly_limit_exceeded`
> e `details.kind`; o erro `rate_limited` também usa HTTP `429`, mas é um limite
> de tráfego separado.

## Captura pelo SDK FaceTec

Com `method: facetec_sdk` o `201` não traz `verificationLink`; traz o bloco
`facetec` (`sessionToken`, `sessionTokenExpiresAt`, `deviceKeyIdentifier`) e
`attemptsRemaining: 3`. O Browser SDK v10 inicializa só com
`deviceKeyIdentifier` (`initializeWithSessionRequest`); o `sessionToken` fica
no backend e volta como `sessionId` em cada `/facetec/process`. O próprio
init gera um `requestBlob` e conta no limite de 15 chamadas. Cada captura
seguinte gera outro blob (1–3 MB em base64).

O app devolve o blob ao backend, e **só o backend** (com a master e a assinatura
de requisição) chama, uma vez por captura:

```bash
curl -X POST \
  "https://client.api.corpx.com/v1/identity-verifications/$VERIFICATION_ID/facetec/process" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-Id: $TENANT_ID" \
  -H "X-Request-Timestamp: $TS" \
  -H "X-Content-SHA256: $BODY_SHA256" \
  -H "X-Request-Signature: $SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{ "requestBlob": "<base64 do SDK>", "sessionId": "<sessionToken do 201>" }'
```

No modo `image`, inclua `referenceImage` (JPEG/PNG em base64, até 2 MB; foto de rosto, nunca de documento). A resposta traz
`responseBlob` (devolva ao SDK), `processed`, `status`, `attemptsRemaining`,
`checks` e, em falha definitiva, `failureReason`. Quando o token da sessão vence
(10 minutos) ou o `/process` responde `409 facetec_session_expired`, peça outro
em `POST /v1/identity-verifications/{id}/facetec/session` e reabra o SDK.

Limites: **3 capturas reprovadas** encerram a verificação como `FAILED`
(`liveness_failed` ou `face_mismatch`); capturas não processadas
(`processed: false`) não contam. Até **15 chamadas** a `/process` por
verificação (a 16ª responde `429 facetec_attempts_exhausted`). Uma captura por
vez (`409 facetec_process_in_progress` com `Retry-After`). Corpo de até **5 MB**
(`413 payload_too_large`). `/facetec/session` pode ser chamado a qualquer
momento enquanto `PENDING`, com freio de 1 a cada 5 s e 30 por verificação
(`429 facetec_session_renewal_limited`).

| `referenceMatch`  | O que prova                                             | Comparado com                                             | Tipo de cota       |
| ----------------- | ------------------------------------------------------- | --------------------------------------------------------- | ------------------ |
| `none`            | Há uma pessoa viva diante da câmera (liveness 3D / PAD) | ninguém                                                   | `liveness`         |
| `dracma` (padrão) | Vida **e** o rosto pertence ao CPF                      | base de referência da DracmaTrust para o CPF (1:1, 3D:2D) | `face_match_cpf`   |
| `image`           | Vida **e** o rosto bate com a foto que você envia       | `referenceImage` enviada no `/process` (1:1, 3D:2D)       | `face_match_image` |

Um `APPROVED` com `referenceMatch: none` só prova que uma pessoa viva concluiu a
captura — **não** prova quem ela é (`checks.faceMatch.result = not_performed`).
Use-o apenas como step-up de uma sessão já autenticada. Quando um modo com match
ainda não está disponível no provedor, a criação responde `422
facetec_match_unavailable`; a API nunca rebaixa silenciosamente para só
liveness. Para `password_reset` e `second_factor_reset`, prefira `dracma` ou
`image`.

## Consultar

```bash
curl "https://client.api.corpx.com/v1/identity-verifications/$VERIFICATION_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-Id: $TENANT_ID" \
  -H "X-Request-Timestamp: $TS" \
  -H "X-Content-SHA256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" \
  -H "X-Request-Signature: $SIGNATURE"
```

| Status     | Próximo passo                                                                                    |
| ---------- | ------------------------------------------------------------------------------------------------ |
| `PENDING`  | Aguarde; `verificationLink` continua presente (`link`) ou há `attemptsRemaining` (`facetec_sdk`) |
| `APPROVED` | Consuma antes de `consumableUntil`                                                               |
| `FAILED`   | Não execute a ação; leia `failureReason`                                                         |
| `EXPIRED`  | Crie outra jornada se ainda for necessário                                                       |

A resposta inclui `purpose`, `referenceId`, `document`, `provider`, `method`,
`expiresAt`, `failureReason`, `completedAt`, `consumableUntil` e `consumedAt`
quando aplicáveis. `verificationLink` só existe em `PENDING` com `method: link`.
Com `method: facetec_sdk` vêm também `referenceMatch`, `attemptsRemaining` e
`checks` (`liveness` e `faceMatch.result`/`faceMatch.reference`);
`liveness_failed` e `face_mismatch` são os `failureReason` específicos do SDK.

## Consumir

```bash
curl -X POST \
  "https://client.api.corpx.com/v1/identity-verifications/$VERIFICATION_ID/consume" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-Id: $TENANT_ID" \
  -H "X-Request-Timestamp: $TS" \
  -H "X-Content-SHA256: $BODY_SHA256" \
  -H "X-Request-Signature: $SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{
    "purpose": "second_factor_reset",
    "referenceId": "reset_01J8Y6N7M8P9Q0R1S2T3"
  }'
```

A finalidade e a referência precisam coincidir exatamente com a criação. A
primeira chamada válida grava `consumedAt`. Repetir o mesmo id e o mesmo corpo é
idempotente; finalidade/referência diferentes, consumo concorrente, estado não
aprovado ou janela vencida respondem `409`.

Consuma no backend imediatamente antes da ação protegida. Ver `APPROVED` no
`GET` não reserva a prova e, sozinho, não impede reutilização concorrente.

## Callback e webhook

A `callbackUri` só devolve o navegador. Ela precisa ser idêntica à URI
cadastrada — sem wildcard, prefixo ou normalização — e não prova o resultado.

`identity.verification.completed` é enviado para `APPROVED`, `FAILED` e
`EXPIRED`, com `X-Signature`. Valide os bytes brutos e deduplique pelo `id` do
envelope. Exemplo completo em
[Webhooks da conta](/ib/guias/conta/webhooks#identityverificationcompleted).

## Evidências

`GET /v1/identity-verifications/{verificationId}/artifacts` exige `kyc.read` no
lugar do escopo de gerenciamento e a feature `kyc_artifacts`. Assine a chamada
como qualquer outra no host client. O retorno pode conter biometria e evidências
do provedor; não registre URLs nem conteúdo em logs.

## Erros principais

| HTTP | `errorCode`                                                                  | Significado                                                           |
| ---- | ---------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| 400  | `invalid_document`, `invalid_purpose`, `invalid_reference_id`                | Campo de criação inválido                                             |
| 400  | `invalid_display_message`, `invalid_verification_ttl`, `invalid_consume_ttl` | Texto ou intervalo inválido                                           |
| 400  | `invalid_callback_uri`                                                       | A URI não coincide exatamente com o cadastro                          |
| 400  | `invalid_provider`, `invalid_method`, `invalid_reference_match`              | Combinação inválida de `provider`, `method` e `referenceMatch`        |
| 400  | `reference_image_required`                                                   | Modo `image` sem `referenceImage` no `/facetec/process`               |
| 403  | `feature_disabled`                                                           | Feature desligada                                                     |
| 403  | `facetec_sdk_not_enabled`                                                    | Feature `identity_verification_facetec_sdk` ou chaves do SDK ausentes |
| 403  | `identity_verification_kind_not_enabled`                                     | O tipo (`details.kind`) tem cota 0                                    |
| 403  | `insufficient_scope`                                                         | Falta `identity_verification.manage` ou `kyc.read`                    |
| 403  | `forbidden`                                                                  | A chamada não veio da master M2M                                      |
| 404  | `verification_not_found`                                                     | Id inexistente neste tenant                                           |
| 409  | `verification_not_consumable`                                                | Estado, janela ou vínculo de consumo incompatível                     |
| 409  | `reference_already_consumed`                                                 | Outra prova já autorizou esta finalidade/referência                   |
| 409  | `verification_method_mismatch`, `verification_not_pending`                   | Rota incompatível com o `method` ou o estado                          |
| 409  | `facetec_process_in_progress`                                                | Outra captura em curso; aguarde `Retry-After`                         |
| 409  | `facetec_session_expired`                                                    | Renove em `/facetec/session`                                          |
| 413  | `payload_too_large`                                                          | `requestBlob` acima de `details.maxBytes`                             |
| 415  | `unsupported_media_type`                                                     | Falta `Content-Type: application/json`                                |
| 422  | `facetec_match_unavailable`                                                  | Modo de match indisponível no provedor                                |
| 429  | `identity_verification_monthly_limit_exceeded`                               | Cota do tipo (`details.kind`) fechada no mês BRT                      |
| 429  | `facetec_attempts_exhausted`                                                 | Excesso de capturas; a verificação falhou                             |
| 429  | `facetec_session_renewal_limited`                                            | Renovação de sessão muito frequente                                   |
| 429  | `rate_limited`                                                               | Limite de tráfego, separado da cota                                   |
| 502  | `provider_error`                                                             | Falha no provedor (veja `partner`)                                    |
| 503  | `facetec_unavailable`                                                        | SDK indisponível no provedor                                          |