> ## 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.

# 認証ステータス: セッションのライフサイクルとコード

> Diditのセッションステータスを一覧で解説します。承認済み、却下、レビュー中、期限切れ、再提出、放棄、KYC期限切れの各ステータスと、判定・再試行・Webhookの処理方法を紹介します。

すべての認証セッションは、一連のステータスを経て進みます。各ステータスを理解しておくと、ユーザーの進捗の把握、コンプライアンス判定の自動化、コンバージョンの最適化に役立ちます。

この enum は、`GET /v3/session/<id>/decision/`とすべての Didit Webhook で返される文字列の唯一の正式な定義です。

***

## すべてのステータス値

> [!NOTE]
>
> 各ステータスは、Didit APIとWebhookが返す**正確な文字列**です。コードでは必ず厳密な文字列比較(例: `=== "In Review"`)を使用してください。これらの値は大文字と小文字が区別され、スペースを含みます。また、`Kyc Expired`の値は先頭の`K`のみが大文字です(`KYC`ではありません)。

| ステータス | 文字列値 | 説明 |
| - | - | - |
| 未開始 | `"Not Started"` | セッションが作成されたが、ユーザーがまだリンクを開いていない |
| 進行中 | `"In Progress"` | ユーザーが認証を進めている |
| 承認済み | `"Approved"` | すべてのチェックに合格し、本人確認が完了した |
| 却下 | `"Declined"` | 1つ以上のチェックに不合格だった |
| レビュー中 | `"In Review"` | コンプライアンス担当者による手動レビューの対象としてフラグが立てられた |
| ユーザー待ち | `"Awaiting User"` | 1人以上の関係者が認証を完了するのを待っている(KYB) |
| 再提出 | `"Resubmitted"` | ユーザーに特定のステップのやり直しが求められた |
| 期限切れ | `"Expired"` | ユーザーがリンクを開く前にセッションがタイムアウトした |
| 放棄 | `"Abandoned"` | ユーザーが開始したが、制限時間内に完了しなかった |
| KYC期限切れ | `"Kyc Expired"` | 以前に承認されたセッションで、認証済みの書類の有効期限が切れた |

***

## セッションステータス

> [accordion] 未開始（"Not Started"）
>
> **APIの値:** `"Not Started"`
>
> セッションはAPI経由で作成されましたが、ユーザーは**まだ認証リンクを開いていません**。
>
> * **対応:** ユーザーが開始するのを待つか、時間が経ちすぎた場合はリマインダーを送信します。
> * **遷移先:** `"In Progress"`、`"Expired"`

> [accordion] 進行中（"In Progress"）
>
> **APIの値:** `"In Progress"`
>
> ユーザーがリンクを開き、**検証ステップを進めている最中**です（書類の撮影、ライブネスなど）。
>
> * **対応:** 対応は不要です。ユーザーがフローを進めています。
> * **遷移先:** `"Approved"`、`"Declined"`、`"In Review"`、`"Abandoned"`

> [accordion] 承認済み（"Approved"）
>
> **APIの値:** `"Approved"`
>
> すべての検証チェックに**合格しました**。ユーザーの本人確認が完了しています。
>
> * **対応:** ユーザーにアクセスを許可し、プロフィールを更新して、判定データを保存します。
> * **Webhookの内容:** すべての機能の結果を含む完全な`decision`オブジェクト。
> * **遷移先:** `"Kyc Expired"`（検証済み書類の有効期限が過ぎたとき。その国と書類タイプの**Expiration mode**が**Allow expired**でない限り、これがデフォルトの動作です）。レビュアーまたはupdate-statusエンドポイントにより、`"Declined"`または`"Resubmitted"`に設定することもできます。

> [accordion] 却下（"Declined"）
>
> **APIの値:** `"Declined"`
>
> 1つ以上の検証チェックが**失敗**しました。ユーザーは認証に合格しませんでした。
>
> * **対応:** ユーザーに通知します。問題が修正可能な場合は、必要に応じて再提出を依頼します。
> * **Webhookの内容:** 失敗の理由を説明する警告を含む完全な`decision`オブジェクト。
> * **遷移先:** `"Resubmitted"`（レビュアーが依頼した場合）。レビュアーまたはupdate-statusエンドポイントにより、`"Approved"`に設定することもできます。

> [accordion] レビュー中（"In Review"）
>
> **APIの値:** `"In Review"`
>
> 自動チェックで**人による確認が必要な警告**が検出されました。コンプライアンス担当のレビュアーが最終判定を下す必要があります。
>
> * **対応:** レビュアーがConsoleでセッションを開き、承認、却下、または再提出の依頼を行います。
> * **Webhookの内容:** 警告を含む完全な`decision`オブジェクト。
> * **遷移先:** `"Approved"`、`"Declined"`、`"Resubmitted"`

> [accordion] ユーザー待ち（"Awaiting User"）
>
> **APIの値:** `"Awaiting User"`
>
> **KYB（法人確認）セッション**で、主要人物ステップが関係者のリストを提出し、子KYC/KYBセッションを生成したときに使用されます。親セッションは、**必須の関係者全員が個別の認証を完了する**まで待機します。
>
> * **対応:** 子KYCセッションのステータスを監視します。必須の関係者全員が完了すると（承認済み、却下、または期限切れ）、親セッションは自動的に再集計され、最終ステータスになります。
> * **Webhookの内容:** 現在の関係者リストと、それぞれの子セッションのステータス。
> * **遷移先:** `"Approved"`、`"Declined"`、`"In Review"`（すべての子セッションが終了ステータスになった時点）
> * **遷移元:** `"In Progress"`（主要人物ステップの送信後）
> * **注意:** 子KYCセッションが再提出された場合、親セッションは再提出されたセッションが完了するまで`"Awaiting User"`に戻ります。KYB Registry Checkが`"Declined"`の場合は、`"Awaiting User"`より優先されます。

> [accordion] 再提出（"Resubmitted"）
>
> **APIの値:** `"Resubmitted"`
>
> レビュアーがユーザーに**特定の検証ステップのやり直し**を依頼しました（例: ぼやけた書類写真の撮り直し）。
>
> * **対応:** ユーザーが再提出のステップを完了するのを待ちます。システムが自動的に再評価します。
> * **Webhookの内容:** やり直す機能のリストと理由を含む`resubmit_info`オブジェクト。
> * **遷移先:** `"Approved"`、`"Declined"`、`"In Review"`、または本人がステップをやり直す前にセッションの有効期間が終了した場合は`"Abandoned"`。

> [accordion] 期限切れ（"Expired"）
>
> **APIの値:** `"Expired"`
>
> **ユーザーが認証リンクを開く前に**セッションがタイムアウトしました。
>
> * **対応:** 新しいセッションを作成し、新しいリンクをユーザーに送信します。
> * **終了ステータス**です。これ以上の遷移はありません。

> [accordion] 放棄（"Abandoned"）
>
> **APIの値:** `"Abandoned"`
>
> ユーザーは認証を**開始しましたが、所定の期間内に完了しませんでした**。
>
> * **対応:** リマインダーを送信するか、新しいセッションを作成します。
> * **自動遷移はありません。** ただし、レビュアーまたは`PATCH /v3/session/{sessionId}/update-status/`により、`"Approved"`、`"Declined"`、`"Resubmitted"`に設定することは可能です。

> [accordion] KYC期限切れ（"Kyc Expired"）
>
> **APIの値:** `"Kyc Expired"`
>
> セッション中に検証された書類が、**書類自体の有効期限を過ぎました**。トリガーはその日付であり、承認からの経過期間ではありません。また、事前に警告は送信されません。
>
> * **対応:** 新しいセッションで再検証するようユーザーに依頼します。`status.updated`がこの遷移を配信し、本人確認の結果には`DOCUMENT_EXPIRED`警告が含まれます。
> * **制御方法:** *ID verification → Additional settings by country & document type*にある、その国と書類タイプの**Expiration mode**で制御します。**Reject expired**（デフォルト）では書類の有効期限を監視し、**Allow expired**ではセッションがこのステータスに移行することはありません。
> * **自動遷移はありません。** ただし、レビュアーまたは`PATCH /v3/session/{sessionId}/update-status/`により、`"Approved"`、`"Declined"`、`"Resubmitted"`に設定することは可能です。

***

## ステータスの遷移

| 遷移元 | 遷移先 | トリガー |
| - | - | - |
| `"Not Started"` | `"In Progress"` | ユーザーが認証リンクを開く |
| `"Not Started"` | `"Expired"` | ユーザーがリンクを開く前にセッションのTTLが経過する |
| `"In Progress"` | `"Approved"` | すべての自動チェックに合格する |
| `"In Progress"` | `"Declined"` | 1つ以上のチェックが不合格になる |
| `"In Progress"` | `"In Review"` | チェックで人によるレビューが必要な警告が検出される |
| `"In Progress"` | `"Awaiting User"` | KYBの主要人物ステップが送信され、親セッションが子KYC当事者の完了を待機する |
| `"In Progress"` | `"Abandoned"` | ユーザーが期限内に完了しない |
| `"Awaiting User"` | `"Approved"` | 必須のKYB当事者全員が完了し、集約されたチェックに合格する |
| `"Awaiting User"` | `"Declined"` | 必須の当事者が却下されるか、KYBの法人登記チェックが不合格になる |
| `"Awaiting User"` | `"In Review"` | 集約されたKYBの結果に手動レビューが必要になる |
| `"In Review"` | `"Approved"` | レビュアーが手動で承認する |
| `"In Review"` | `"Declined"` | レビュアーが手動で却下する |
| `"In Review"` | `"Resubmitted"` | レビュアーが特定のステップのやり直しをリクエストする |
| `"Declined"` | `"Resubmitted"` | レビュアーが特定のステップのやり直しをリクエストする |
| `"Approved"` | `"Resubmitted"` | レビュアーが特定のステップのやり直しをリクエストする |
| `"Approved"` | `"Declined"` | レビュアーまたはAPIがもう一方の判定を設定する |
| `"Declined"` | `"Approved"` | レビュアーまたはAPIがもう一方の判定を設定する |
| `"Abandoned"`, `"Kyc Expired"` | `"Approved"`, `"Declined"`, `"Resubmitted"` | 判定なしで終了したセッションに対し、レビュアーまたはAPIが判定を下す |
| `"Resubmitted"` | `"Abandoned"` | 本人がステップをやり直す前にセッションの有効期間が終了する |
| `"Resubmitted"` | `"Approved"` | 再提出されたステップがすべてのチェックに合格する |
| `"Resubmitted"` | `"Declined"` | 再提出されたステップが不合格になる |
| `"Resubmitted"` | `"In Review"` | 再提出されたステップで新たな警告が検出される |
| `"Resubmitted"`(KYBの子セッション) | `"Awaiting User"`(KYBの親セッション) | 子セッションが完了するまで、親セッションが再び待機状態に入る |
| `"Approved"` | `"Kyc Expired"` | 検証済み書類の有効期限が過ぎる(有効期限モードが**Reject expired**の場合) |

### ライフサイクル図

```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"]
```

***

## 終了ステータスと非終了ステータス

| 区分 | ステータス | 意味 |
| - | - | - |
| **決定済み** | `"Approved"`, `"Declined"`, `"Kyc Expired"` | チェックにより判定が出ており、検証済み書類の有効期限が過ぎた場合の`"Approved"` → `"Kyc Expired"`を除き、判定が自動的に変わることはありません。レビュアーまたはステータス更新エンドポイントによって判定を変更することは引き続き可能です。 |
| **非終了** | `"Not Started"`, `"In Progress"`, `"Resubmitted"`, `"Awaiting User"` | まだアクティブな状態です。ユーザーのアクション、子セッション、または処理を待機しています。 |
| **要対応** | `"In Review"` | チームによる手動対応が必要です。 |
| **非アクティブ** | `"Expired"`, `"Abandoned"` | 検証の判定なしで終了しました。`"Expired"`が変わることはありません。`"Abandoned"`のセッションは、レビュアーが引き続き判定できます。 |

***

## コードでのステータスの処理

ステータスの変化に対応するには、Webhookまたは[セッション取得API](https://docs.didit.me/ja/sessions-api/retrieve-session.md)を使用します。

> [!WARNING]
>
> ステータスは**スペースを含み、大文字と小文字を区別する正確な文字列**です。たとえば、`"In Review"`であり、`"in_review"`や`"IN_REVIEW"`ではありません。照合する際は必ず厳密等価演算子(`===`)を使用してください。

```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;
  }
}
```

***

## 再提出

**再提出済み**ステータスを使うと、コンプライアンスチームは新しいセッションを作成せずに、ユーザーにもう一度機会を与えることができます。

**1. レビュアーが再提出を開始する**

コンソールで`In Review`または`Declined`のセッションを開き、**Request Resubmission**をクリックします。やり直しが必要なステップを選択します。

**2. 以前のデータがアーカイブされる**

システムは選択された機能をリセットし、以前のデータを`previous_attempt`としてマークします。これにより監査証跡全体が保持されます。

**3. ユーザーに通知される**

メールアドレスがある場合、ユーザーは再開するための直接リンクを含むローカライズされたメールを受け取ります。

**4. ユーザーが特定のステップをやり直す**

ユーザーはフラグが付いたステップのみを繰り返します。検証全体をやり直す必要はありません。

**5. システムが再評価する**

完了すると、セッションは自動的に`"Approved"`、`"Declined"`、または`"In Review"`に遷移します。

### 再提出のWebhookペイロード

```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`は、再提出された各`node_id`を、そのステップで最も関連性の高いログの警告コード([判定](https://docs.didit.me/ja/reference/data-models.md)が報告するものと同じコード)に対応付けます。そのため、独自の文言に対応付けることができます。これは、ホスト型フローの再提出画面と再提出メールがユーザー向けにローカライズするコードでもあります。ただし、スクリーニングや不正のシグナルを明かしてしまう警告(重複、AML、ブロックリスト、組織間チェック、位置情報の整合性など)は例外です。これらの場合、本人には一般的な理由が表示されますが、Webhookの`resubmit_info.reasons`には常に実際のコードが含まれます。警告が記録されていないステップにはエントリがありません。

### 再提出できる機能

承認済み以外のステータスを持つ機能はすべて再提出できます。対象は**却下**、**レビュー中**、**Not Finished**、**Not Started**、**期限切れ**です。

> [!TIP]
>
> 同じセッションで再提出を複数回リクエストできます。サイクルごとに以前の試行データがアーカイブされるため、ユーザーの検証履歴をすべて把握できます。

***

## ベストプラクティス

> [card] レビュー中を監視する
>
> Didit Consoleでアラート(メールまたはSlack)を設定し、セッションが手動レビューを必要とする際に通知を受け取れるようにします。

> [card] 再提出を優先する
>
> 問題が修正可能な場合(写真のぼやけや書類の表裏の誤りなど)は、却下せずに再提出をリクエストしてください。これによりコンバージョン率が向上します。

> [card] 離脱を追跡する
>
> 放棄や期限切れの割合が高い場合は、ユーザー体験上の障壁がある可能性があります。セッションのTTLの調整やユーザーへの案内の改善を検討してください。

> [card] 冪等なハンドラー
>
> Webhookは再試行される場合があります。`session_id`を一意のキーとして使用し、各ステータス変更を一度だけ処理するようにしてください。

> [!WARNING]
>
> ペイロードを処理する前に、必ずWebhookの署名を検証してください。Diditは3つの方法を提供しています。`X-Signature`、`X-Signature-V2`(推奨)、そしてエンベロープのみを認証し`decision`の本文は一切認証しない非推奨の`X-Signature-Simple`です。詳しくは[Webhook](https://docs.didit.me/ja/integration/webhooks.md#署名検証)を参照してください。


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