mcpField
D
didit-kyc-onboarding

didit-kyc-onboarding

github.com/didit-protocolセキュリティ29282 回インストール2 週間前に更新
リポジトリ

didit-kyc-onboarding について

Didit のワークフロー設定、ユーザー検証セッションの作成、判定結果の取得を扱う KYC 導入スキルです。登録フローに本人確認を組み込む開発者向けです。

主な機能

  1. 01再利用可能な KYC ワークフロー設定
  2. 02ユーザー検証セッションの作成
  3. 03ユーザーへの検証 URL 発行
  4. 04ポーリングまたは Webhook による結果取得
  5. 05書類とセルフィーの照合

活用シーン

  1. 01ユーザー登録への本人確認の追加
  2. 02ユーザーへの検証リンク送信
  3. 03完了した確認結果の取得

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/didit-protocol/skills --skill didit-kyc-onboarding

インストール後、Claude Code で/didit-kyc-onboardingを入力して読み込まれたか確認します。

同梱ファイルscripts/run_kyc.py

詳細

Didit で KYC を実行する

エンドツーエンドの顧客確認(KYC)検証です。このスキルでは、KYC ワークフローを作成し、実際のユーザーが ID スキャン+セルフィー+顔照合を完了するセッション URL を生成して、検証結果を取得します。

ユーザーが体験すること:

  1. 検証リンクを受け取ります(またはアプリ内で開きます)
  2. ID 書類(パスポート、ID カード、運転免許証、在留許可証)をスキャンします
  3. ライブセルフィーを撮影します
  4. セルフィーと書類の顔写真が照合されます
  5. 承認、却下、または審査対象の判定を受けます

料金: ワークフローでは、完了した機能ごとに料金が発生します。ID Verification(書類の撮影)は $0.15、Passive Liveness は $0.10、Face Match は $0.05 で、組織ごとに毎月 500 件まで無料で利用できます。Active liveness(ACTIVE_3D または FLASHING)は $0.15、NFC は $0.15、AML Screening は $0.20、Email Verification は $0.03、Phone Verification は $0.04+通信事業者の料金です。これらは 2026 年 11 月 1 日までの定価です。同日、Didit の料金が変更され、毎月 500 件の無料チェックが毎月 $10 分の無料クレジットになります。最新の料金はdidit.me/pricingをご確認ください。

API リファレンス:

関連スキル:didit-sdk-integration(リンクを送信する代わりに、セッションをウェブアプリまたはモバイルアプリに埋め込みます)、didit-case-management(In Review セッションの審査キュー)、didit-verification-management(ウェブフック、ユーザー、請求)。


認証

すべてのリクエストに x-api-key ヘッダーが必要です。Didit Business Console の Developers > API keys からアプリケーションの API キーを使用するか、アカウントとキーをプログラムで作成してください(「はじめに」を参照)。カスタムアクセス権を持つ名前付きキーでワークフローを作成するには Workflows の書き込み権限、セッションを作成するには Sessions の書き込み権限が必要です(権限がない場合、url と session_token は null で返されます)。結果の取得には Decisions の読み取り権限、画像 URL と PDF レポートの取得には Media の読み取り権限が必要です。

はじめに(まだアカウントをお持ちでない場合)

Didit API キーをお持ちでない場合は、2 回の API 呼び出しで作成できます。

  1. 登録: POST https://apx.didit.me/auth/v2/programmatic/register/ に {"email": "[email protected]", "password": "MyStr0ng!Pass"} を送信します
  2. メールを確認: 6 文字の確認コードを確認します
  3. 認証: POST https://apx.didit.me/auth/v2/programmatic/verify-email/ に {"email": "[email protected]", "code": "A3K9F2"} を送信します。キーはレスポンスの application.api_key にあります。

クレジットの追加: 残高を確認するには GET /v3/billing/balance/ を、Stripe のチェックアウトリンクを取得するには {"amount_in_dollars": 50} を指定して POST /v3/billing/top-up/ を実行します。

プラットフォーム管理(ワークフロー、セッション、ユーザー、請求)の詳細については、didit-verification-management スキルをご覧ください。


クイックスタート:3 回の API 呼び出しで KYC を実行

import requests, time

API_KEY = "your_api_key"
headers = {"x-api-key": API_KEY, "Content-Type": "application/json"}
BASE = "https://verification.didit.me/v3"
TERMINAL = {"Approved", "Declined", "In Review", "Expired", "Kyc Expired", "Abandoned"}

# 1. Create a KYC workflow (one-time setup: reuse the workflow id for all users)
workflow = requests.post(f"{BASE}/workflows/", headers=headers, json={
    "workflow_label": "KYC Onboarding",
    "max_retry_attempts": 3,
    "features": [
        {"feature": "OCR"},
        {"feature": "LIVENESS", "config": {"face_liveness_method": "PASSIVE"}},
        {"feature": "FACE_MATCH", "config": {"face_match_score_decline_threshold": 50}},
    ],
}).json()
workflow_id = workflow["uuid"]

# 2. Create a session for a specific user
session = requests.post(f"{BASE}/session/", headers=headers, json={
    "workflow_id": workflow_id,
    "vendor_data": "user-abc-123",
    "callback": "https://yourapp.com/verification-done",
    "language": "en",
}).json()

print(f"Send user to: {session['url']}")
# User opens this URL, scans their ID, takes a selfie

# 3. Poll for the decision (or use webhooks)
while True:
    decision = requests.get(
        f"{BASE}/session/{session['session_id']}/decision/",
        headers={"x-api-key": API_KEY},
    ).json()
    status = decision["status"]
    if status in TERMINAL:
        break
    time.sleep(15)

print(f"Result: {status}")
if status == "Approved":
    id_data = decision["id_verifications"][0]
    print(f"Name: {id_data['first_name']} {id_data['last_name']}")
    print(f"DOB: {id_data['date_of_birth']}")
    print(f"Document: {id_data['document_type']} ({id_data['issuing_state']})")

ステップ 1:KYC ワークフローを作成する

ワークフローでは、実行するチェックを定義します。ユースケースごとに 1 つ作成し、すべてのユーザーに再利用してください。アプリケーションごとに最大 50 個のワークフローを作成できます。各呼び出しで新しいワークフローが作成されます。

POST https://verification.didit.me/v3/workflows/

API リファレンス: https://docs.didit.me/management-api/workflows/create

リクエストボディ

ボディで受け付けるのは以下のキーのみです。それ以外のキー(workflow_typeを含む)を指定すると、400が返されます。

フィールド型デフォルト説明
featuresarray必須実行順のステップ:{"feature": "...", "config": {...}, "label": "..."}
workflow_labelstring"ID Verification"表示名。最大50文字
max_retry_attemptsinteger 0-103拒否後に許可される再試行回数。0の場合、最初の拒否後にブロックされます
retry_window_daysinteger 1-365 or null7再試行回数をカウントするローリング期間。nullの場合、全期間が対象です
session_expiration_timeinteger 3600-2419200604800(7日)未完了のセッションが期限切れになるまでの秒数
face_liveness_max_attemptsinteger 1-33セッションごとのライブネス提出回数
face_match_max_attemptsinteger 1-33セッションごとの顔照合提出回数
is_defaultboolean-アプリケーションのデフォルトワークフローに設定します
statusdraft or publishedpublished省略すると、直ちに公開されます
is_white_label_enabledbooleanfalseホワイトラベルのカスタマイズを適用します
is_desktop_allowedbooleanfalseデスクトップブラウザーでフローを実行できるようにします
KYC 機能と主な設定
feature設定備考
OCRdocuments_allowed、methods、duplicated_user_action、年齢とリスクに関するアクションID書類の撮影。後続のステップでデータを使用できるよう、最初に配置してください
LIVENESSface_liveness_method:PASSIVE、ACTIVE_3D(3Dアクションとフラッシュ)、またはFLASHING(3Dフラッシュ)アクティブ方式はActive Livenessとして課金されます($0.15)
FACE_MATCHface_match_score_decline_threshold、face_match_score_review_threshold(0-100)OCRの後に配置する必要があります
NFCallow_nfc_skip、skip_nfc_action、unverified_chip_actionOCRの後に配置する必要があります。チップはネイティブiOS/Android SDKで読み取られ、ウェブブラウザーではスキップされます
AMLaml_score_review_threshold、aml_score_approve_threshold先にOCRを配置する必要があります
PHONE_VERIFICATION、EMAIL_VERIFICATION機能設定を参照連絡先の認証

設定内のアクションには、DECLINE、REVIEW、NO_ACTIONを指定します。その他の機能(IP_ANALYSIS、PROOF_OF_ADDRESS、DATABASE_VALIDATION、QUESTIONNAIRE、AGE_ESTIMATION、DOCUMENT_AI)とすべての設定キーについては、機能設定のリファレンスを参照してください。

レスポンス(201)

レスポンスにはワークフロー設定全体(約190個のフィールド)が含まれます。主なフィールド:

{
  "uuid": "c3d4e5f6-7890-12cd-ef34-333333333333",
  "workflow_id": "c3d4e5f6-7890-12cd-ef34-333333333333",
  "workflow_label": "KYC Onboarding",
  "features": "OCR + LIVENESS + FACE_MATCH",
  "total_price": 0.3,
  "min_price": 0.3,
  "max_price": 0.3,
  "workflow_url": "https://verify.didit.me/u/w9TkPOx8RWG3UAz5ZRQGVQ",
  "max_retry_attempts": 3,
  "retry_window_days": 7,
  "session_expiration_time": 604800,
  "status": "published",
  "version": 1
}

uuid(workflow_idと同じ値)を保存してください。featuresは" + "で連結された1つの文字列です。価格はUSDのJSON数値で、有効化された機能をお客様の料金で合計した金額です。


ステップ2:各ユーザーのセッションを作成する

各ユーザーに、固有の認証URLを持つ専用セッションを作成します。

POST https://verification.didit.me/v3/session/

APIリファレンス: https://docs.didit.me/sessions-api/create-session

主要なパラメーター
パラメーター型必須説明
workflow_iduuidはいステップ 1 で取得します
vendor_datastring推奨ユーザー ID です。ユーザーごとにセッションをグループ化し、重複検出に使用します。同じワークフローバージョンで同じ vendor_data を持つ未完了のセッションがある場合、新しいセッションではなくそのセッションが返されます
callbackurl推奨検証後のリダイレクト先です。Didit はクエリパラメーターとして verificationSessionId と status を追加します
callback_methodstringいいえinitiator、completer、または both(コールバックに従うデバイス)
languagestringいいえUI 言語(ISO 639-1)です。省略した場合は自動検出されます
contact_detailsobjectいいえemail、send_notification_emails、email_lang、phone(E.164)
expected_detailsobjectいいえfirst_name、last_name、date_of_birth(YYYY-MM-DD)、gender、nationality、id_country、identification_number、expected_document_types、... 不一致があると *_MISMATCH_WITH_PROVIDED 警告が追加されます
metadataany JSONいいえセッションとともに保存され、レスポンスと Webhook で返されます。任意の JSON 値を指定できますが、オブジェクトを推奨します
レスポンス(201)
{
  "session_id": "11111111-2222-3333-4444-555555555555",
  "session_number": 43762,
  "session_token": "3FaJ9wLqX2Mz",
  "url": "https://verify.didit.me/session/3FaJ9wLqX2Mz",
  "vendor_data": "user-abc-123",
  "metadata": null,
  "status": "Not Started",
  "workflow_id": "c3d4e5f6-7890-12cd-ef34-333333333333",
  "workflow_version": 1,
  "callback": "https://yourapp.com/verification-done"
}

ユーザーを url に誘導してください(ウェブまたはモバイル)。または、SDK を使用してセッションを埋め込んでください(didit-sdk-integration スキル)。session_token は秘密情報として扱ってください。これを保持する人は誰でも検証を完了できます。


ステップ 3:判定結果を取得する

GET https://verification.didit.me/v3/session/{sessionId}/decision/

API リファレンス: https://docs.didit.me/sessions-api/retrieve-session

完了を確認する 2 つの方法

方法 A:Webhook(本番環境に推奨) Business Console(Webhooks)で送信先を追加するか、POST /v3/webhook/destinations/(label、url、webhook_version: "v3"、subscribed_events: ["status.updated"])を使用します。Didit は署名付き POST を送信します。これには session_id、status、およびステータスが Approved、Declined、In Review、Abandoned の場合は完全な decision が含まれます。署名を検証し(didit-verification-management を参照)、ハンドラーで event_id に基づく冪等性を確保してください。

方法 B:ポーリング 10~30 秒ごとに GET /v3/session/{sessionId}/decision/ をポーリングします。終端ステータス(Approved、Declined、In Review、Expired、Kyc Expired、Abandoned)になったら停止します。手動レビュー後に In Review が変わることがあるため、その場合に備えて Webhook も維持してください。

判定レスポンスのフィールド

各機能には、それぞれ独自の status、node_id、warnings を持つ配列があります。トップレベルに warnings キーはありません。

{
  "session_id": "11111111-2222-3333-4444-555555555555",
  "session_number": 43762,
  "status": "Approved",
  "workflow_id": "c3d4e5f6-7890-12cd-ef34-333333333333",
  "features": ["ID_VERIFICATION", "LIVENESS", "FACE_MATCH"],
  "vendor_data": "user-abc-123",
  "metadata": null,
  "id_verifications": [{
    "node_id": "ocr",
    "verification_method": "document",
    "status": "Approved",
    "document_type": "Passport",
    "document_number": "ABC123456",
    "issuing_state": "USA",
    "issuing_state_name": "United States",
    "first_name": "Alex",
    "last_name": "Sample",
    "full_name": "Alex Sample",
    "date_of_birth": "1990-01-15",
    "age": 36,
    "expiration_date": "2030-06-01",
    "gender": "M",
    "nationality": "USA",
    "mrz": {"surname": "SAMPLE", "name": "ALEX", "document_type": "P", "document_number": "ABC123456", "birth_date": "900115", "expiry_date": "300601", "sex": "M"},
    "portrait_image": "https://<media-host>/...",
    "warnings": []
  }],
  "liveness_checks": [{
    "node_id": "liveness",
    "status": "Approved",
    "method": "PASSIVE",
    "score": 92.5,
    "warnings": []
  }],
  "face_matches": [{
    "node_id": "face_match",
    "status": "Approved",
    "score": 97.3,
    "warnings": []
  }],
  "aml_screenings": [],
  "created_at": "2026-05-17T10:30:00Z"
}

フィールドに関する注記:

  • document_type は表示名です:Passport、Identity Card、Driver's License、Residence Permit、...
  • issuing_state と nationality は ISO 3166-1 alpha-3 です。日付は YYYY-MM-DD 形式、MRZ の日付は未加工の YYMMDD 形式です。mrz はオブジェクトで、MRZ が読み取られなかった場合は null です。
  • 機能のステータス(Approved、Declined、In Review、Not Finished、...)は、セッションの status とは独立しています。
  • id_verifications の verification_method は document、id_lookup、または wallet です。
  • 警告:{feature, risk, additional_data, log_type, short_description, long_description, node_id}。didit-id-document-verification スキルと https://docs.didit.me/core-technology/id-verification/warnings-id-verification を参照してください。
セッションのステータス
ステータス意味アクション
Not Startedセッションは作成されていますが、リンクはまだ開かれていません待機するか、ユーザーにリマインドします
In Progressユーザーが手順を進めています待機します
Awaiting Userビジネス(KYB)セッションが、関係者のKYCセッションを待っています待機します
Resubmittedユーザーに特定の手順のやり直しを依頼しました新しい結果を待ちます
Approvedすべてのチェックに合格しましたユーザーは認証済みです
Declined1つ以上のチェックに失敗しました各機能の warnings を確認します
In Review手動レビューが必要ですコンソールでレビューするか、以下のAPIで判断します
Expired完了前にセッションの有効期限が切れました(デフォルトは7日、session_expiration_time)新しいセッションを作成します
Abandonedユーザーが開始しましたが、時間内に完了しませんでした新しいセッションを作成します
Kyc Expired以前に承認されたセッションが、KYCの有効期限ポリシーを過ぎましたユーザーを再認証します

値は大文字と小文字を区別する完全一致の文字列です(Kyc Expired の大文字のKは1つです)。


オプション:判定後のアクション

手動で承認または却下する
PATCH https://verification.didit.me/v3/session/{sessionId}/update-status/

APIリファレンス: https://docs.didit.me/sessions-api/update-status

セッションのステータスは Approved、Declined、In Review、Kyc Expired、Abandoned、Resubmitted のいずれかである必要があります。また、新しいステータスは現在のステータスと異なる必要があります(そうでない場合は 400)。

requests.patch(f"{BASE}/session/{session_id}/update-status/",
    headers=headers,
    json={"new_status": "Approved", "comment": "Manual review passed"})
再提出を依頼する

ID写真が不鮮明な場合は、その手順だけをやり直すようユーザーに依頼します。判定から node_id を取得します。このAPIで作成したワークフローでは ocr、liveness、face_match のようなIDが使用され、コンソールで作成したワークフローでは feature_ocr のようなIDが使用されます。

decision = requests.get(f"{BASE}/session/{session_id}/decision/", headers=headers).json()
ocr_node = decision["id_verifications"][0]["node_id"]

requests.patch(f"{BASE}/session/{session_id}/update-status/",
    headers=headers,
    json={
        "new_status": "Resubmitted",
        "nodes_to_resubmit": [{"node_id": ocr_node, "feature": "OCR"}],
        "send_email": True,
        "email_address": "[email protected]",
    })

nodes_to_resubmit を省略すると、試行済みで Declined、In Review、Not Finished、Expired のいずれかであるすべての手順が再提出対象になります(NFCとIP分析は自動選択されません)。それらの手順で取得したデータは削除され、有効期限が再開し、元の認証URLが再び使用できるようになります。

不正なユーザーをブロックする

Lists APIを使って、セッションの顔または書類をシステムのブロックリストに追加します(各エントリータイプにつき、アプリケーションごとに1つのブロックリストがあります)。

lists = requests.get(f"{BASE}/lists/", headers=headers,
                     params={"list_type": "blocklist", "entry_type": "face"}).json()
list_uuid = lists["results"][0]["uuid"]
requests.post(f"{BASE}/lists/{list_uuid}/entries/",
    headers=headers,
    json={"reference_session_id": session_id})

APIリファレンス: https://docs.didit.me/management-api/lists/create-entry

PDFレポートを生成する

Approved、Declined、In Review、Kyc Expired のセッションで利用できます。application/pdf のバイトデータを返します。

response = requests.get(f"{BASE}/session/{session_id}/generate-pdf/",
    headers={"x-api-key": API_KEY})
with open("report.pdf", "wb") as f:
    f.write(response.content)

APIリファレンス: https://docs.didit.me/sessions-api/generate-pdf

エラーレスポンス
コード意味アクション
400リクエストが無効ですレスポンス本文のフィールドエラーを確認します
401APIキーの有効期限が切れていますDevelopers > API keys でキーをローテーションするか、新しいキーを作成します
403APIキーがない、誤っている、または取り消されている、スコープ付きキーにこのエンドポイントへのアクセス権がない、キーのIP許可リスト外からのリクエスト、またはクレジット不足detail または error のメッセージを確認し、x-api-key ヘッダーまたはキーのアクセス権を修正するか、クレジットを追加します
404セッションが見つかりません(またはスコープ付きキーのワークフロー対象外です)sessionId を確認します
429レート制限:キーあたり毎分300件のPOST/PATCH/DELETEリクエスト、および600件のGETリクエストRetry-After の秒数だけ待ってから再試行します

KYCワークフローのバリエーション

KYC + AMLスクリーニング
requests.post(f"{BASE}/workflows/", headers=headers, json={
    "workflow_label": "KYC + AML",
    "features": [
        {"feature": "OCR"},
        {"feature": "LIVENESS", "config": {"face_liveness_method": "PASSIVE"}},
        {"feature": "FACE_MATCH"},
        {"feature": "AML"},
    ],
})
KYC + 電話番号 + メールアドレス
requests.post(f"{BASE}/workflows/", headers=headers, json={
    "workflow_label": "KYC + Contact",
    "features": [
        {"feature": "OCR"},
        {"feature": "LIVENESS", "config": {"face_liveness_method": "PASSIVE"}},
        {"feature": "FACE_MATCH"},
        {"feature": "PHONE_VERIFICATION"},
        {"feature": "EMAIL_VERIFICATION"},
    ],
})
KYC + NFC(チップの読み取り)

チップ搭載のパスポートとeIDに対する、最も高い保証レベルです。ネイティブのiOS/Android SDKが必要です。WebフローではNFCはスキップされます。

requests.post(f"{BASE}/workflows/", headers=headers, json={
    "workflow_label": "KYC + NFC",
    "features": [
        {"feature": "OCR"},
        {"feature": "NFC"},
        {"feature": "LIVENESS", "config": {"face_liveness_method": "PASSIVE"}},
        {"feature": "FACE_MATCH"},
    ],
})
より厳格なライブネス検出とセッション設定
requests.post(f"{BASE}/workflows/", headers=headers, json={
    "workflow_label": "KYC High Assurance",
    "max_retry_attempts": 1,
    "retry_window_days": 30,
    "session_expiration_time": 86400,
    "face_liveness_max_attempts": 2,
    "features": [
        {"feature": "OCR"},
        {"feature": "LIVENESS", "config": {"face_liveness_method": "FLASHING"}},
        {"feature": "FACE_MATCH", "config": {"face_match_score_decline_threshold": 60}},
    ],
})
国ごとの非書類照会とデジタル ID ウォレット

OCR 機能の config.methods では、ISO 3166-1 alpha-3 の国ごとに、ユーザーが利用できる ID 検証方法を選択します。方法には、書類の撮影、政府登録簿やその他の信頼できる情報源への照会(ユーザーが国民 ID 番号を入力)、デジタル ID ウォレットがあります。省略した国では、書類の撮影のみが利用できます。各方法とウォレットは、その国の機能カタログ(コンソールの Countries タブ)で利用可能としてマークされている必要があります。そうでない場合、保存全体が拒否されます。

requests.post(f"{BASE}/workflows/", headers=headers, json={
    "workflow_label": "KYC with lookup",
    "features": [
        {"feature": "OCR", "config": {"methods": {
            "ZAF": {
                "document": {"enabled": True},
                "id_lookup": {"enabled": True, "max_attempts": 2,
                              "on_no_match": "fallback_to_document"},
            },
        }}},
        {"feature": "LIVENESS", "config": {"face_liveness_method": "PASSIVE"}},
        {"feature": "FACE_MATCH"},
    ],
})
キーデフォルト値
<ISO3>.document.enabledtrue撮影した書類を受け付けます
<ISO3>.id_lookup.enabledfalse照会を提示します
<ISO3>.id_lookup.max_attempts1回答済みの照会を 1~5 回
<ISO3>.id_lookup.skip_liveness_and_face_matchtrue情報源から顔写真が返され、セルフィーと一致した場合、その後の Liveness/Face Match をスキップします
<ISO3>.id_lookup.on_partial_match / on_no_match / on_provider_errorfallback_to_documentまたは decline
<ISO3>.wallet.enabledfalseウォレットでのサインインを提示します
<ISO3>.wallet.providers[]その国で受け付けるカタログ上のウォレット ID(例:["mitid"])。順位付けではなく、許可リストです
<ISO3>.wallet.on_failurefallback_to_documentまたは decline

照会は国ごと、ウォレットは検証完了ごとに料金が発生し、無料の書類チェック 500 件には含まれません。https://docs.didit.me/core-technology/id-verification/non-doc-lookup および https://docs.didit.me/core-technology/id-verification/digital-id-wallets を参照してください。


ユーティリティスクリプト

run_kyc.py:コマンドラインからの KYC 設定全体
# Requires: pip install requests
export DIDIT_API_KEY="your_api_key"

# Create a KYC workflow (one-time)
python scripts/run_kyc.py setup --label "My KYC" --liveness --face-match
python scripts/run_kyc.py setup --label "KYC + AML" --aml --liveness-method FLASHING

# Create a session for a user
python scripts/run_kyc.py session --workflow-id <uuid> --vendor-data user-123

# Get the decision (or poll until a terminal status)
python scripts/run_kyc.py decision <session_id>
python scripts/run_kyc.py decision <session_id> --poll --interval 15

# Full flow: create workflow + session in one command
python scripts/run_kyc.py full --vendor-data user-123 --callback https://myapp.com/done

インポートして使用することもできます。

from scripts.run_kyc import setup_kyc_workflow, create_kyc_session, get_decision, poll_decision

コメント