📦 Didit Kyc Onboarding — 端到端KYC身份验证

端到端了解您的客户（KYC）验证。此技能创建KYC工作流，生成一个会话URL，真实用户在该URL完成身份证扫描+自拍+人脸比对，并检索验证决策。

用户体验流程：

• 收到验证链接
• 扫描身份证件（护照、身份证、驾照）
• 进行实时自拍
• 系统自动将自拍与证件照片比对
• 获得批准、拒绝或标记待审核

API参考：

• 工作流：https://docs.didit.me/management-api/workflows/create
• 会话：https://docs.didit.me/sessions-api/create-session
• 决策：https://docs.didit.me/sessions-api/retrieve-session
• 程序化注册：https://docs.didit.me/integration/programmatic-registration
• 完整API概述：https://docs.didit.me/sessions-api/management-api

认证

入门（还没有账户？）

• 注册： POST https://apx.didit.me/auth/v2/programmatic/register/ 包含 {"email": "you@gmail.com", "password": "MyStr0ng!Pass"}
• 检查邮箱 获取6位字符的OTP验证码
• 验证： POST https://apx.didit.me/auth/v2/programmatic/verify-email/ 包含 {"email": "you@gmail.com", "code": "A3K9F2"} → 响应包含api_key

添加积分： GET /v3/billing/balance/ 查看余额，POST /v3/billing/top-up/ 包含 {"amount_in_dollars": 50} 获取Stripe结账链接。请参阅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"
# 1. 创建KYC工作流（一次性设置 — 复用workflow_id用于所有用户）
workflow = requests.post(f"{BASE}/workflows/", headers=headers, json={
    "workflow_label": "KYC Onboarding",
    "workflow_type": "kyc",
    "is_liveness_enabled": True,
    "is_face_match_enabled": True,
    "face_match_score_decline_threshold": 50,
    "max_retry_attempts": 3,
}).json()
workflow_id = workflow["uuid"]
# 2. 为特定用户创建会话
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']}")
# 用户打开此URL → 扫描身份证 → 自拍 → 完成
# 3. 轮询获取决策（或使用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 ("Approved", "Declined", "In Review"):
        break
    time.sleep(10)
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_country']})")

步骤1：创建KYC工作流

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

API参考： https://docs.didit.me/management-api/workflows/create

推荐的KYC配置

响应

{
    "uuid": "d8d2fa2d-c69c-471c-b7bc-bc71512b43ef",
    "workflow_label": "KYC Onboarding",
    "workflow_type": "kyc",
    "features": ["ocr", "liveness", "face_match"],
    "total_price": "0.10",
    "workflow_url": "https://verify.didit.me/..."
}

将uuid保存为您的workflow_id。

步骤2：为每个用户创建会话

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

API参考： https://docs.didit.me/sessions-api/create-session

关键参数

响应

{
    "session_id": "11111111-2222-3333-4444-555555555555",
    "session_token": "abcdef123456",
    "url": "https://verify.didit.me/session/abcdef123456",
    "status": "Not Started",
    "workflow_id": "d8d2fa2d-..."
}

将用户发送到url — 这是他们完成验证的地方（网页或移动端）。

步骤3：获取决策

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

API参考： https://docs.didit.me/sessions-api/retrieve-session

两种方式获知准备就绪

选项A：Webhooks（生产环境推荐） 在Business Console → API & Webhooks配置webhook URL。Didit在决策就绪时发送包含session_id和status的POST请求。

选项B：轮询 每10-30秒轮询一次GET /v3/session/{id}/decision/。检查status — 当状态为Approved、Declined或In Review时停止。

决策响应字段

{
    "session_id": "...",
    "status": "Approved",
    "features": ["ID_VERIFICATION", "LIVENESS", "FACE_MATCH"],
    "id_verifications": [{
        "status": "Approved",
        "document_type": "PASSPORT",
        "issuing_country": "USA",
        "first_name": "John",
        "last_name": "Doe",
        "date_of_birth": "1990-01-15",
        "document_number": "ABC123456",
        "expiry_date": "2030-06-01",
        "gender": "M",
        "nationality": "USA",
        "mrz": "P

关键决策状态

PATCH https://verification.didit.me/v3/session/{sessionId}/update-status/

requests.patch(f"{BASE}/session/{session_id}/update-status/", headers=headers, json={"new_status": "Approved", "comment": "Manual review passed"})

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

requests.post(f"{BASE}/blocklist/add/", headers=headers, json={"session_id": session_id, "blocklist_face": True, "blocklist_document": True})

response = requests.get(f"{BASE}/session/{session_id}/generate-pdf", headers={"x-api-key": API_KEY})

requests.post(f"{BASE}/workflows/", headers=headers, json={
    "workflow_type": "kyc",
    "is_liveness_enabled": True,
    "is_face_match_enabled": True,
    "is_aml_enabled": True,
    "aml_decline_threshold": 80,
})

requests.post(f"{BASE}/workflows/", headers=headers, json={
    "workflow_type": "kyc",
    "is_liveness_enabled": True,
    "is_face_match_enabled": True,
    "is_phone_verification_enabled": True,
    "is_email_verification_enabled": True,
})

requests.post(f"{BASE}/workflows/", headers=headers, json={
    "workflow_type": "kyc",
    "is_liveness_enabled": True,
    "is_face_match_enabled": True,
    "is_nfc_enabled": True,
})

# 需要：pip install requests
export DIDIT_API_KEY="your_api_key"
# 创建KYC工作流（一次性）
python scripts/run_kyc.py setup --label "My KYC" --liveness --face-match
# 为用户创建会话
python scripts/run_kyc.py session --workflow-id  --vendor-data user-123
# 获取决策
python scripts/run_kyc.py decision 
# 完整流程：一次命令创建工作流+会话
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