> ## 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 在账户创建前要求活体检测或完整身份证件验证，提现等敏感操作前再次验证，并可在令牌中返回已验证声明。

Didit Authentication 的已验证身份功能会在您选择的时机请求用户证明其身份：账户注册之前，以及提现等敏感操作之前再次验证。
您的应用会收到验证结果，以及您选择的已验证声明（例如 `over_18` 或已验证的姓名）。验证结果和这些声明包含在用户的 token 中，您的应用不会收到用户的证件或照片。

请在控制台中的 **Authentication > Verified identity** 进行设置，或通过 API 调用 [`verified/`](#通过-api-设置) 进行设置。

![Didit 商业控制台中的已验证身份页面，展示注册时的验证级别及其价格，以及敏感操作前的二次验证规则](https://mintcdn.com/didit-0f962782/RpqZjIB1GnUPdMTN/images/authentication/console-verified-identity.png?fit=max\&auto=format\&n=RpqZjIB1GnUPdMTN\&q=85\&s=98544caeedf5ffaf68484cace19f9b3f)

Authentication > Verified identity：注册时的验证以及敏感操作前的规则。

## 工作原理

每项检查都会作为您应用中的一个验证会话运行，并使用该用户的 `vendor_data` 创建。这意味着该会话会出现在您的验证记录中，并与同一用户的登录和交易归在一起；与其他验证一样，它会进入人工审核，并按该验证的价格计费。

| 检查项 | 用户需要做什么 | 标准价格 |
| - | - | - |
| 活体检测 | 拍摄一张自拍照，并进行活体检测。 | \$0.10 |
| 自拍照登录 | 拍摄一张自拍照，Didit 会将其与该用户已保存的人脸进行比对。 | \$0.10 |
| 完整身份证件验证 | 扫描身份证件并拍摄自拍照：包括证件、活体检测和人脸比对。 | \$0.33 |

Didit 会使用每项检查的默认工作流运行，您也可以为该检查选择自己的工作流。请参阅[定价](https://docs.didit.me/zh/getting-started/pricing.md)，了解所有验证的价格。

## 注册时

选择用户创建账户前必须通过的验证级别：

| 级别 | 值 | 含义 |
| - | - | - |
| 无验证 | `none` | 任何拥有邮箱、手机号或通行密钥的人都可以注册。这是默认值。 |
| 活体检测 | `liveness` | 确认注册者是真人：提交一张自拍照并进行活体检测。 |
| 完整身份验证 | `full_id` | 在账户创建之前完成证件验证、活体检测和人脸比对。 |

新级别只适用于此后注册的用户，不会影响现有账户。

在托管验证页面上，Didit 会在注册期间引导用户完成验证。在您自己的页面上，注册请求会返回 `verification_required` 以及有效期为 30 分钟的 `verification_url`，请将用户引导至该链接。只有在验证通过后，Didit 才会签发登录验证码。

## 敏感操作前的升级验证

只有当操作风险足够高时，升级验证才会要求用户再次验证。
您启用这些规则后，应用会在每次敏感操作前向 Didit 询问是否适用某条规则。

![手机上显示升级验证页面，要求用户通过自拍确认本人身份](https://mintcdn.com/didit-0f962782/RpqZjIB1GnUPdMTN/images/authentication/step-up-preview.png?fit=max\&auto=format\&n=RpqZjIB1GnUPdMTN\&q=85\&s=dd5087d0ba5f20b49bbd4252149ef8ca)

用户在升级验证要求自拍时看到的界面。

| 规则 | 触发条件 | 默认检查 |
| - | - | - |
| `payout` | 提款或转账金额超过您设定的阈值（例如以您的货币计为 500）时。以其他货币提款或转账时始终进行检查。 | 自拍照登录 |
| `device` | 在用户此前任何会话都未使用过的设备上的会话中进行提款或转账。 | 自拍照登录 |
| `bank` | 用户添加或更改银行账户时。 | 完整身份证件验证 |
| `contact` | 用户更改电子邮箱或电话号码时。 | 活体检测 |

您可以将每条规则的检查方式改为活体检测、自拍照登录或完整身份证件验证。
当多条规则同时适用时，Didit 会要求最强的检查方式。
若 Didit 尚未保存该用户的人脸，自拍照登录将改为完整身份证件验证。

### 发起升级验证

您的应用通过用户的访问令牌调用 `POST {issuer}/step-up/`，或调用 SDK 的 `stepUp()` 方法：

```bash theme={null}
curl --fail-with-body "${DIDIT_AUTH_ISSUER}/step-up/" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action": "payout", "amount": "900.00", "currency": "USD", "return_to": "https://app.example.com/payouts/confirm"}'
```

| 字段 | 说明 |
| - | - |
| `action` | `payout`、`bank` 或 `contact`。提款或转账还会应用 `device` 规则。 |
| `amount` | `payout` 时必填，最多两位小数。 |
| `currency` | ISO 4217 代码。默认为您的提款或转账规则所用的货币。 |
| `return_to` | 用户完成验证后返回的地址。当某条规则适用时，该地址必须是您已登记的[重定向 URL](https://docs.didit.me/zh/authentication/overview.md#重定向-url)之一。 |

* `200 {"required": false}`：没有规则适用，可以继续操作。
* `201` 且包含 `verification_url`：将用户引导至该地址。升级验证将保持开放 30 分钟（`expires_in: 1800`）。

### 在后端读取结果

用户返回 `return_to` 时会附加 `step_up=<id>&status=approved`，但这些查询参数不能证明任何事情。
您的后端需使用 `GET {issuer}/step-up/{step_up_id}/` 并携带同一会话的访问令牌读取升级验证结果，且仅当 `status` 为 `approved` 时才执行操作。

| 状态 | 含义 |
| - | - |
| `pending` | 用户尚未完成检查。 |
| `approved` | 用户已通过。可以继续执行操作。 |
| `review` | 检查结果等待贵团队审核。 |
| `declined` | 用户未通过。只要 `verification_url` 仍然有效，该结果就不是最终结果：用户可以重试，升级验证会恢复为 `pending`。 |
| `expired` | 30 分钟已过。请创建新的升级验证。 |
| `superseded` | 另一项检查已取代本次检查，或该结果并非针对本次升级验证。请创建新的升级验证。 |

升级验证绝不会在失败时放行：验证服务不可用时，该操作仍被阻止。
[JavaScript](https://docs.didit.me/zh/authentication/quickstarts/javascript.md#步骤验证与重新认证)、[Next.js](https://docs.didit.me/zh/authentication/quickstarts/nextjs.md#敏感操作前的-step-up-验证) 和 [iOS](https://docs.didit.me/zh/authentication/quickstarts/ios.md#敏感操作前的分步验证) 快速入门展示了 SDK 端的实现，[API 参考](https://docs.didit.me/zh/authentication/api-reference/create-step-up.md)包含完整的接口规范。

## 您的应用将收到的内容

选择将哪些已验证的声明写入用户的 token：

| 声明 | 值 |
| - | - |
| `over_18`, `over_21` | 根据已验证的出生日期，判断用户是否至少年满 18 岁或 21 岁。 |
| `given_name`, `family_name` | 已验证的名字和姓氏。 |
| `birthdate` | 证件上的出生日期，格式为 `YYYY-MM-DD`。 |
| `nationality` | ISO 3166-1 alpha-2 代码。 |
| `country` | 证件所属国家/地区的 ISO 3166-1 alpha-2 代码。 |
| `document_verified` | 是否已验证身份证件。 |
| `liveness` | 是否已通过活体检测。 |

访问 token 和 ID token 会在 `verified` 中携带这些声明，并包含 `level`，即用户已通过的最高等级：`liveness`、`liveness_face_match` 或 `full_id`。
用户尚未通过任何检查时，它为 `{}`，而 `GET /session/` 则返回 `null`。

```json theme={null}
{
  "verified": {
    "level": "full_id",
    "over_18": true,
    "given_name": "Alex",
    "country": "ES"
  }
}
```

* 会话期间通过的检查，会在下一次刷新时同步到 token 中，最长不超过 5 分钟。
* 任何持有 token 的人都可以读取这些声明，包括您的前端，因此请只选择应用所需的个人声明。
* 您的应用获得的只是声明，绝不会获得证件、自拍照或人脸数据。

## 通过 API 设置

在应用的 [认证管理 API](https://docs.didit.me/zh/authentication/set-up-by-api.md) 中，对 `verified/` 执行 `GET` 和 `PATCH`，可以读取和修改与控制台相同的设置：

```bash theme={null}
curl --fail-with-body --request PATCH "${MANAGEMENT_BASE}verified/" \
  -H "x-api-key: $DIDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "signup_level": "liveness",
    "rules": [
      {"rule": "payout", "enabled": true, "method": "selfie", "threshold": "500.00", "currency": "USD"},
      {"rule": "bank", "enabled": true, "method": "full_id"}
    ],
    "claims": ["over_18", "given_name", "country"]
  }'
```

| 字段 | 取值 |
| - | - |
| `signup_level` | `none`、`liveness` 或 `full_id`。 |
| `rules` | 每条要修改的规则对应一个条目：`rule`（`payout`、`device`、`bank` 或 `contact`）、`enabled`、`method`（`liveness`、`selfie` 或 `full_id`），以及仅针对 `payout` 的 `threshold` 和 `currency`。 |
| `claims` | 要放入 token 的声明，取自上表。 |
| `workflows` | 可选：您自己的 `liveness`、`selfie` 或 `full_id` 工作流 ID，或设为 `null` 以使用 Didit 的默认工作流。 |

您未包含的规则将保持其当前设置。


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