> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Status de verificação: ciclo de vida e códigos da sessão

> Status de sessão da Didit: Approved, Declined, In Review, Expired, Resubmitted, Abandoned e KYC Expired. Trate decisões, novas tentativas e webhooks.

Toda sessão de verificação passa por uma série de status. Entendê-los ajuda você a acompanhar o progresso do usuário, automatizar decisões de conformidade e otimizar a conversão.

Este enum é a única fonte de verdade para as strings retornadas por `GET /v3/session/<id>/decision/` e por todos os webhooks da Didit.

***

## Todos os valores de status

> [!NOTE]
>
> Cada status é uma **string exata** retornada pela API e pelos webhooks da Didit. Sempre use comparação estrita de strings (por exemplo, `=== "In Review"`) no seu código: esses valores diferenciam maiúsculas de minúsculas e incluem espaços. O valor `Kyc Expired` também usa apenas o `K` maiúsculo (não `KYC`).

| Status | Valor da string | Descrição |
| - | - | - |
| Não iniciada | `"Not Started"` | Sessão criada, o usuário ainda não abriu o link |
| Em andamento | `"In Progress"` | O usuário está concluindo a verificação |
| Aprovado | `"Approved"` | Todas as verificações foram aprovadas: identidade verificada |
| Recusado | `"Declined"` | Uma ou mais verificações falharam |
| Em revisão | `"In Review"` | Sinalizada para revisão manual de conformidade |
| Aguardando usuário | `"Awaiting User"` | Aguardando que uma ou mais partes concluam a verificação (KYB) |
| Reenviada | `"Resubmitted"` | Foi solicitado ao usuário que refaça etapas específicas |
| Expirado | `"Expired"` | A sessão expirou antes de o usuário abrir o link |
| Abandonado | `"Abandoned"` | O usuário começou, mas não terminou a tempo |
| KYC expirado | `"Kyc Expired"` | Sessão aprovada anteriormente cujo documento verificado expirou |

***

## Status de sessão

> [accordion] Não iniciada — "Not Started"
>
> **Valor na API:** `"Not Started"`
>
> A sessão foi criada pela API, mas o usuário **ainda não abriu o link de verificação**.
>
> * **O que fazer:** aguarde o usuário começar ou envie um lembrete se passar muito tempo.
> * **Muda para:** `"In Progress"`, `"Expired"`

> [accordion] Em andamento — "In Progress"
>
> **Valor na API:** `"In Progress"`
>
> O usuário abriu o link e está **concluindo ativamente as etapas de verificação** (captura do documento, prova de vida etc.).
>
> * **O que fazer:** nenhuma ação é necessária — o usuário está percorrendo o fluxo.
> * **Muda para:** `"Approved"`, `"Declined"`, `"In Review"`, `"Abandoned"`

> [accordion] Aprovada — "Approved"
>
> **Valor na API:** `"Approved"`
>
> Todas as verificações foram **aprovadas com sucesso**. A identidade do usuário foi verificada.
>
> * **O que fazer:** libere o acesso do usuário, atualize o perfil dele e armazene os dados da decisão.
> * **O webhook inclui:** o objeto `decision` completo, com os resultados de todos os recursos.
> * **Muda para:** `"Kyc Expired"` (quando passa a data de validade do documento verificado — o comportamento padrão, a menos que o **Expiration mode** seja **Allow expired** para aquele país e tipo de documento). Um revisor ou o endpoint update-status também pode alterá-la para `"Declined"` ou `"Resubmitted"`.

> [accordion] Recusada — "Declined"
>
> **Valor na API:** `"Declined"`
>
> Pelo menos uma das verificações **falhou**. O usuário não foi aprovado na verificação.
>
> * **O que fazer:** notifique o usuário. Se o problema puder ser corrigido, você pode solicitar um reenvio.
> * **O webhook inclui:** o objeto `decision` completo, com avisos que explicam a falha.
> * **Muda para:** `"Resubmitted"` (se um revisor solicitar). Um revisor ou o endpoint update-status também pode alterá-la para `"Approved"`.

> [accordion] Em revisão — "In Review"
>
> **Valor na API:** `"In Review"`
>
> As verificações automáticas sinalizaram **avisos que precisam de revisão humana**. Um revisor de conformidade deve tomar a decisão final.
>
> * **O que fazer:** um revisor deve abrir a sessão no Console e aprovar, recusar ou solicitar o reenvio.
> * **O webhook inclui:** o objeto `decision` completo, com os avisos.
> * **Muda para:** `"Approved"`, `"Declined"`, `"Resubmitted"`

> [accordion] Aguardando usuário — "Awaiting User"
>
> **Valor na API:** `"Awaiting User"`
>
> Usado em **sessões de KYB (verificação de empresas)** quando a etapa de pessoas-chave (Key People) já enviou a lista de partes e gerou sessões filhas de KYC / KYB. A sessão principal aguarda até que **todas as partes obrigatórias concluam sua verificação individual**.
>
> * **O que fazer:** acompanhe os status das sessões filhas de KYC. Quando todas as partes obrigatórias terminarem (aprovadas, recusadas ou expiradas), a sessão principal recalcula automaticamente seu status final.
> * **O webhook inclui:** a lista atual de partes e os status de suas sessões filhas.
> * **Muda para:** `"Approved"`, `"Declined"`, `"In Review"` (quando todas as sessões filhas estiverem em um status final)
> * **Vem de:** `"In Progress"` (depois que a etapa de pessoas-chave é enviada)
> * **Observação:** se uma sessão filha de KYC for reenviada, a sessão principal volta para `"Awaiting User"` até que a sessão reenviada seja concluída. Uma verificação de registro KYB (KYB Registry Check) com status `"Declined"` tem prioridade sobre `"Awaiting User"`.

> [accordion] Reenviada — "Resubmitted"
>
> **Valor na API:** `"Resubmitted"`
>
> Um revisor solicitou que o usuário **refaça etapas específicas da verificação** (por exemplo, tirar novamente uma foto desfocada do documento).
>
> * **O que fazer:** aguarde o usuário concluir as etapas reenviadas. O sistema fará uma nova avaliação automaticamente.
> * **O webhook inclui:** o objeto `resubmit_info`, com a lista de recursos a refazer e os motivos.
> * **Muda para:** `"Approved"`, `"Declined"`, `"In Review"` ou `"Abandoned"`, quando o prazo da sessão termina antes que a pessoa refaça as etapas.

> [accordion] Expirada — "Expired"
>
> **Valor na API:** `"Expired"`
>
> O tempo da sessão **se esgotou antes de o usuário abrir o link de verificação**.
>
> * **O que fazer:** crie uma nova sessão e envie um novo link ao usuário.
> * **Status final** — não há outras transições.

> [accordion] Abandonada — "Abandoned"
>
> **Valor na API:** `"Abandoned"`
>
> O usuário **começou, mas não concluiu** a verificação dentro do prazo permitido.
>
> * **O que fazer:** envie um lembrete ou crie uma nova sessão.
> * **Sem transições automáticas.** Um revisor, ou `PATCH /v3/session/{sessionId}/update-status/`, ainda pode alterá-la para `"Approved"`, `"Declined"` ou `"Resubmitted"`.

> [accordion] KYC expirado — "Kyc Expired"
>
> **Valor na API:** `"Kyc Expired"`
>
> O documento verificado durante a sessão **ultrapassou a própria data de validade**. O gatilho é essa data, e não um prazo contado a partir da aprovação, e nenhum aviso é enviado antes.
>
> * **O que fazer:** peça ao usuário que faça a reverificação em uma nova sessão. O evento `status.updated` informa a transição, e o resultado da verificação de identidade traz um aviso `DOCUMENT_EXPIRED`.
> * **Controlado por:** o **Expiration mode** daquele país e tipo de documento em *ID verification → Additional settings by country & document type* — **Reject expired** (o padrão) monitora o documento; com **Allow expired**, a sessão nunca chega a este status.
> * **Sem transições automáticas.** Um revisor, ou `PATCH /v3/session/{sessionId}/update-status/`, ainda pode alterá-la para `"Approved"`, `"Declined"` ou `"Resubmitted"`.

***

## Transições de status

| De | Para | Gatilho |
| - | - | - |
| `"Not Started"` | `"In Progress"` | O usuário abre o link de verificação |
| `"Not Started"` | `"Expired"` | O TTL da sessão se esgota antes de o usuário abrir o link |
| `"In Progress"` | `"Approved"` | Todas as verificações automáticas passam |
| `"In Progress"` | `"Declined"` | Uma ou mais verificações falham |
| `"In Progress"` | `"In Review"` | As verificações sinalizam avisos que exigem revisão humana |
| `"In Progress"` | `"Awaiting User"` | A etapa de pessoas-chave do KYB foi enviada; a sessão pai aguarda as partes de KYC filhas |
| `"In Progress"` | `"Abandoned"` | O usuário não conclui dentro do prazo |
| `"Awaiting User"` | `"Approved"` | Todas as partes obrigatórias do KYB concluem a verificação e as verificações agregadas passam |
| `"Awaiting User"` | `"Declined"` | Uma parte obrigatória é recusada ou a verificação no registro de empresas do KYB falha |
| `"Awaiting User"` | `"In Review"` | O resultado agregado do KYB exige revisão manual |
| `"In Review"` | `"Approved"` | O revisor aprova manualmente |
| `"In Review"` | `"Declined"` | O revisor recusa manualmente |
| `"In Review"` | `"Resubmitted"` | O revisor solicita que etapas específicas sejam refeitas |
| `"Declined"` | `"Resubmitted"` | O revisor solicita que etapas específicas sejam refeitas |
| `"Approved"` | `"Resubmitted"` | O revisor solicita que etapas específicas sejam refeitas |
| `"Approved"` | `"Declined"` | O revisor ou a API define a outra decisão |
| `"Declined"` | `"Approved"` | O revisor ou a API define a outra decisão |
| `"Abandoned"`, `"Kyc Expired"` | `"Approved"`, `"Declined"`, `"Resubmitted"` | O revisor ou a API decide uma sessão que terminou sem decisão |
| `"Resubmitted"` | `"Abandoned"` | A janela da sessão termina antes de a pessoa refazer as etapas |
| `"Resubmitted"` | `"Approved"` | As etapas reenviadas passam em todas as verificações |
| `"Resubmitted"` | `"Declined"` | As etapas reenviadas falham |
| `"Resubmitted"` | `"In Review"` | As etapas reenviadas sinalizam novos avisos |
| `"Resubmitted"` (filha de KYB) | `"Awaiting User"` (pai de KYB) | A sessão pai volta ao estado de espera até que a sessão filha seja concluída |
| `"Approved"` | `"Kyc Expired"` | A data de validade do documento verificado é ultrapassada (o modo de expiração é **Reject expired**) |

### Diagrama do ciclo de vida

```mermaid theme={null}
flowchart LR
    NS["Not Started"] --> IP["In Progress"]
    NS --> EX["Expired"]
    IP --> AP["Approved"]
    IP --> DC["Declined"]
    IP --> IR["In Review"]
    IP --> AU["Awaiting User<br/>(KYB only)"]
    IP --> AB["Abandoned"]
    AU --> AP
    AU --> DC
    AU --> IR
    IR --> AP
    IR --> DC
    IR --> RS["Resubmitted"]
    DC --> RS
    AP --> RS
    AP <--> DC
    AB --> AP
    AB --> DC
    AB --> RS
    KE --> AP
    KE --> DC
    KE --> RS
    RS --> AB
    RS --> AP
    RS --> DC
    RS --> IR
    AP --> KE["Kyc Expired"]
```

***

## Terminais e não terminais

| Categoria | Status | Significado |
| - | - | - |
| **Decidido** | `"Approved"`, `"Declined"`, `"Kyc Expired"` | As verificações produziram uma decisão e nada a altera por conta própria, exceto `"Approved"` → `"Kyc Expired"` quando a data de validade do documento verificado vence. Um revisor ou o endpoint de atualização de status ainda pode alterar a decisão. |
| **Não terminal** | `"Not Started"`, `"In Progress"`, `"Resubmitted"`, `"Awaiting User"` | Ainda ativa: aguardando ação do usuário, sessões filhas ou processamento. |
| **Acionável** | `"In Review"` | Exige intervenção manual da sua equipe. |
| **Inativo** | `"Expired"`, `"Abandoned"` | Terminou sem uma decisão de verificação. `"Expired"` nunca muda; um revisor ainda pode decidir uma sessão `"Abandoned"`. |

***

## Tratamento de status no seu código

Use webhooks ou a [API Retrieve Session](https://docs.didit.me/pt-br/sessions-api/retrieve-session.md) para reagir a mudanças de status.

> [!WARNING]
>
> Os status são **strings exatas, que diferenciam maiúsculas de minúsculas e contêm espaços**. Por exemplo, `"In Review"` (e não `"in_review"` ou `"IN_REVIEW"`). Sempre use igualdade estrita (`===`) ao compará-los.

```javascript theme={null}
// All ten possible status string values (StatusChoices, source of truth):
// "Not Started"  | "In Progress" | "Approved"     | "Declined" |
// "In Review"    | "Resubmitted" | "Awaiting User"|
// "Expired"      | "Abandoned"   | "Kyc Expired"

async function handleWebhook(webhook) {
  const { status, vendor_data: vendorData } = webhook;

  switch (status) {
    case "Not Started":
      // Session created but user hasn't opened the link yet
      break;

    case "In Progress":
      // User is actively completing verification steps
      break;

    case "Approved":
      // All checks passed — grant access
      await db.users.update(vendorData, {
        verified: true,
        verifiedAt: new Date(),
        decision: webhook.decision,
      });
      break;

    case "Declined":
      // Verification failed — notify user
      await db.users.update(vendorData, {
        verificationStatus: "declined",
        declineReasons: webhook.decision?.warnings,
      });
      break;

    case "In Review":
      // Needs manual review by compliance team
      await db.users.update(vendorData, {
        verificationStatus: "pending_review",
      });
      break;

    case "Awaiting User":
      // KYB parent waiting for all child KYC parties to finish
      await db.users.update(vendorData, {
        verificationStatus: "awaiting_kyb_parties",
      });
      break;

    case "Resubmitted":
      // User will redo specific steps
      await db.users.update(vendorData, {
        verificationStatus: "resubmission_pending",
        resubmitInfo: webhook.resubmit_info,
      });
      break;

    case "Abandoned":
      // User started but didn't finish — send reminder
      await sendReminderEmail(vendorData);
      break;

    case "Expired":
    case "Kyc Expired":
      // Session expired — create a new one
      await createNewSession(vendorData);
      break;
  }
}
```

***

## Reenvio

O status **Resubmitted** permite que sua equipe de conformidade dê aos usuários uma segunda chance sem criar uma nova sessão.

**1. O revisor inicia o reenvio**

No Console, abra uma sessão `In Review` ou `Declined` e clique em **Solicitar Reenvio**. Selecione quais etapas precisam ser refeitas.

**2. Os dados anteriores são arquivados**

O sistema redefine os recursos selecionados e marca os dados anteriores como `previous_attempt`, preservando a trilha de auditoria completa.

**3. O usuário é notificado**

Se houver um e-mail disponível, o usuário recebe um e-mail localizado com um link direto para retomar.

**4. O usuário refaz etapas específicas**

O usuário repete apenas as etapas que foram sinalizadas, e não a verificação inteira.

**5. O sistema reavalia**

Após a conclusão, a sessão passa automaticamente para `"Approved"`, `"Declined"` ou `"In Review"`.

### Payload do webhook de reenvio

```json theme={null}
{
  "session_id": "uuid-of-the-session",
  "status": "Resubmitted",
  "resubmit_info": {
    "nodes_to_resubmit": [
      { "node_id": "feature_ocr", "feature": "OCR" },
      { "node_id": "feature_liveness", "feature": "LIVENESS" }
    ],
    "reasons": {
      "feature_ocr": "DOCUMENT_EXPIRED",
      "feature_liveness": "LOW_LIVENESS_SCORE"
    }
  }
}
```

`reasons` associa cada `node_id` reenviado ao código de aviso do registro mais relevante daquela etapa (os mesmos códigos que a [decisão](https://docs.didit.me/pt-br/reference/data-models.md) informa), para que você possa associá-lo aos seus próprios textos. Também é o código que a tela de reenvio do fluxo hospedado e o e-mail de reenvio usam para exibir ao usuário uma mensagem no idioma dele, exceto nos avisos que revelariam um sinal de triagem ou de fraude (duplicatas, AML, lista de bloqueio, verificações entre organizações, integridade de localização e similares): nesses casos, a pessoa vê um motivo genérico, e `resubmit_info.reasons` no seu webhook sempre traz o código real. Uma etapa sem aviso registrado não tem entrada.

### Quais recursos podem ser reenviados?

Qualquer recurso com status diferente de aprovado: **Declined**, **In Review**, **Not Finished**, **Not Started** ou **Expired**.

> [!TIP]
>
> Você pode solicitar o reenvio várias vezes na mesma sessão. Cada ciclo arquiva os dados da tentativa anterior, dando a você visibilidade completa do histórico de verificação do usuário.

***

## Boas práticas

> [card] Monitore sessões em revisão
>
> Configure alertas (e-mail ou Slack) no seu Didit Console para ser notificado quando houver sessões que precisam de revisão manual.

> [card] Prefira o reenvio
>
> Se o problema puder ser corrigido (foto desfocada, lado errado do documento), solicite um reenvio em vez de recusar. Isso melhora a conversão.

> [card] Acompanhe os abandonos
>
> Taxas altas de sessões abandonadas ou expiradas podem indicar atrito na experiência do usuário. Considere ajustar o TTL da sessão ou melhorar as orientações ao usuário.

> [card] Handlers idempotentes
>
> Os webhooks podem ser reenviados. Use `session_id` como chave única para garantir que cada mudança de status seja processada apenas uma vez.

> [!WARNING]
>
> Sempre verifique as assinaturas dos webhooks antes de processar os payloads. A Didit oferece três métodos: `X-Signature`, `X-Signature-V2` (recomendado) e o descontinuado `X-Signature-Simple`, que autentica apenas o envelope e nunca o corpo de `decision`. Veja [Webhooks](https://docs.didit.me/pt-br/integration/webhooks.md#verificação-de-assinatura) para mais detalhes.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.