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

# Shopify KYC 应用 - 身份与年龄验证

> Didit 提供即插即用的 Shopify 应用，可在结账时完成身份验证、年龄限制与 KYC。无需编码即可设置，每次完整 KYC 检查 $0.33 起，每月 $10 免费额度，无合约。

在几分钟内为您的 Shopify 店铺添加 Didit 身份验证和年龄门控功能。
**Didit Verify** Shopify 应用会安装一个主题模块，您可以将其放置在任意页面（账户页、结账页、自定义落地页等），并在服务器端创建验证会话。您的 API 密钥保留在嵌入式应用内，绝不会暴露给店铺前台。
验证结果会直接显示在 Shopify 后台应用的 **验证** 标签页中，无需单独的后端。对于自行运营后端的商家，结果也可通过 [Webhook](https://docs.didit.me/zh/integration/webhooks.md) 和 [Didit API](https://docs.didit.me/zh/sessions-api/retrieve-session.md) 获取。
您无需登录 Didit Business Console，即可访问通过 Shopify 收集的验证数据。

## 前提条件

* 一个 Shopify 店铺（任意套餐）
* 一个 [Didit Console](https://business.didit.me) 账户，且至少拥有一个工作流

***

### 步骤 1 - 安装应用

1. 打开安装链接：

   [[https://admin.shopify.com/oauth/install?client\_id=cafa0d15227fb59bd47470b23eae7469](https://admin.shopify.com/oauth/install?client_id=cafa0d15227fb59bd47470b23eae7469)](https://admin.shopify.com/oauth/install?client_id=cafa0d15227fb59bd47470b23eae7469)

2. 选择您的店铺（如果您有多个店铺）

3. 点击 **Install** 将应用添加到您的店铺

> [!NOTE]
>
> 应用仅请求一项权限范围 `read_customers`，只有在启用 **Allow customer-approved prefill** 且已登录的客户勾选可选的共享复选框时，才会用于预填和交叉核对详细信息。

***

### 步骤 2 - 配置 Didit 凭证

安装完成后，Didit Verify 会在 Shopify 后台中打开。请使用 **设置** 将应用连接到您的 Didit 账户。

#### 获取 API 密钥

1. 登录 [Didit Business Console](https://business.didit.me)
2. 在左侧边栏中进入 **API 和 Webhook**
3. 复制您的 API 密钥

![如何从 Didit Business Console 获取 API 密钥](https://mintcdn.com/didit-0f962782/gKLcMCmiLycklBol/images/shopify-how-to-get-api-key.jpg?fit=max\&auto=format\&n=gKLcMCmiLycklBol\&q=85\&s=9027ca685cc296a400e78d320a566453)

4. 将 API 密钥粘贴到 Shopify 偏好设置中的 **Didit API Key** 字段

#### 获取工作流 ID

1. 在 Didit Business Console 中进入 **工作流**
2. 选择您要使用的工作流（或创建新工作流）
3. 复制 **工作流 ID**（格式为 UUID，例如 `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`）

![如何从 Didit Business Console 获取工作流 ID](https://mintcdn.com/didit-0f962782/gKLcMCmiLycklBol/images/shopify-how-to-get-workflow-id.jpg?fit=max\&auto=format\&n=gKLcMCmiLycklBol\&q=85\&s=529dc681169efc0a6cdc96d6c0e0a605)

4. 将工作流 ID 粘贴到 **Didit Workflow ID** 字段

#### 保存设置

保存前，请先在 **数据保留** 下选择保留期限。该期限适用于现有和未来的店铺验证，因此请选择您的店铺所需的时长。
点击 **Save Settings**。您应该会看到一条成功消息：

![Shopify 设置已成功保存](https://mintcdn.com/didit-0f962782/gKLcMCmiLycklBol/images/shopify-settings-saved-successfuly.jpg?fit=max\&auto=format\&n=gKLcMCmiLycklBol\&q=85\&s=93dcf3469f902876ae831075da75a628)

***

### 步骤 3 - 将验证按钮添加到您的主题

1. 在 Shopify 后台中，进入 **Online Store** → **Themes**
2. 在当前启用的主题上点击 **自定义**
3. 进入您希望显示验证按钮的页面（例如账户页或自定义页面）
4. 点击 **添加部分** 或 **Add block**
5. 进入 **应用** 标签页
6. 选择 **Didit Verify**

验证按钮将出现在您的主题中。您可以拖动它，在该部分内重新定位。

***

## 访问验证数据

Shopify 应用审核要求（要求 5.1.5）规定，通过 Shopify 托管流程收集的数据必须能在 **Shopify 后台或应用上下文中**供商户访问，而不能只存在于外部仪表板中。
Didit Verify 应用开箱即满足此要求：无需后端、Webhook 接收端或自定义界面。

### 验证标签页 (默认, 无需编码)

在 Shopify 后台中打开 **应用** → **Didit Verify** → **验证**，即可查看通过您的店铺前台收集的每个验证会话，包括状态、客户、国家/地区和时间戳，且数据仅限于您的店铺。
选择某个会话，即可查看其决策概览、身份字段、各项验证检查、警告以及可用的证据。
您无需离开 Shopify 后台，即可在 **设置**、**验证**、**隐私** 和 **人工审核** 之间切换。
保存设置后，这些标签页仍然可用。

> [!NOTE]
>
> 只有从 Shopify 后台打开应用时，验证标签页才会加载数据。如果您看到提示要求重新打开页面，请从 Shopify 后台侧边栏返回 **应用** → **Didit Verify**。

Didit Business Console（`business.didit.me`）是用于配置的独立管理界面（API 密钥、工作流、Webhook 目标）。
请勿指导商户使用它查看通过 Shopify 收集的验证数据，因为这不符合 Shopify 的数据访问要求。
Console 仅在初始设置和获取凭证时需要使用。

### 适用于自有后端的商户 (可选)

如果您有自己的后端，并希望在那里保存一份验证数据副本（例如用于触发履约逻辑），除上述验证标签页外，Didit 还可通过 Webhook 和按需 API 提供结果。

**1. 创建验证会话**

Shopify 应用使用您的 Didit API 密钥在服务器端创建会话。客户在主题模块（弹窗或嵌入式）中完成验证流程。

**2. 通过 Webhook 投递结果**

会话到达终态后，Didit 会将已签名的 `status.updated` Webhook 发送到您在 Didit Business Console 的 **API 和 Webhook** 下配置的目标。
对于 `Approved`、`Declined`、`In Review` 和 `Abandoned` 状态，Webhook 请求体包含完整的 [决策对象](https://docs.didit.me/zh/integration/webhooks.md#payload-结构)，其结构与 `GET /v3/session/{id}/decision/` 返回的相同。
其他终态（例如 `Expired`、`Kyc Expired`）只投递状态变更，不包含决策 payload；如需查看会话状态，请调用 API。

**3. 按需获取（可选）**

您的后端也可以随时调用 [`GET /v3/session/{sessionId}/decision/`](https://docs.didit.me/zh/sessions-api/retrieve-session)，获取完整的决策 payload（身份字段、活体检测、AML、人脸比对等）。

#### 为 Shopify 配置 Webhook

1. 在 [Didit Business Console](https://business.didit.me) 中，进入 **API 和 Webhook** → **Webhook**
2. 创建一个指向您的后端 endpoint 的 Webhook 目标（必须为 HTTPS，且可公开访问）
3. 至少订阅 `status.updated` 和 `data.updated` 事件
4. 保存返回的 `secret_shared_key`，用于验证传入 Webhook 的 HMAC-SHA256 签名

有关完整协议、Node.js、Python 和 PHP 的签名验证示例以及重试行为，请参阅 [Webhook 指南](https://docs.didit.me/zh/integration/webhooks.md)。

#### 通过 API 获取会话决策

```bash theme={null}
curl https://verification.didit.me/v3/session/<SESSION_ID>/decision/ \
  -H "x-api-key: <YOUR_API_KEY>"
```

响应包含 `session_kind`、`status` 以及所有功能数组（`id_verifications`、`liveness_checks`、`face_matches`、`aml_screenings` 等）。完整的响应结构和字段说明，请参阅 [获取会话](https://docs.didit.me/zh/sessions-api/retrieve-session.md)。

***

## 配置选项

### 偏好设置页面中的设置

以下设置在应用偏好设置中配置（可从 Shopify 后台的 **应用** → **Didit Verify** 进入）：

| 设置 | 说明 |
| - | - |
| **API 密钥** | 您的 Didit API 密钥（必填） |
| **工作流 ID** | 要使用的验证工作流（必填） |
| **供应商数据** | 会话如何在 Didit Console 中与用户关联：**客户 ID**（以 `shopify-<customer-id>` 形式发送）、**客户邮箱**、**商店 + 客户 ID**（以 `<shop-domain>-<customer-id>` 形式发送）或 **无**。仅在客户已登录时生效。 |
| **回调 URL** | 可选。验证完成后将用户重定向到的 URL。Didit 会将 `verificationSessionId` 和 `status` 作为查询参数附加到该 URL。 |
| **回调方法** | 由哪台设备处理重定向：**默认（发起方）**、**发起方**、**完成方** 或 **两者** |
| **语言** | 验证界面语言（自动检测或指定语言） |
| **要求客户登录** | 启用后，只有已登录的客户才能进行验证。 |
| **允许客户同意后预填** | 提供一个可选复选框，供客户共享其已登录账户的姓名、邮箱、电话和地址，用于预填和身份检查。只有客户勾选该复选框时，才会发送这些信息。 |
| **在指定天数后自动删除** | 选择店铺需要保留验证记录的时长。所选时长适用于该店铺现有和未来的记录。删除不可撤销。 |

### 客户隐私选择

店铺前台模块提供一个可选复选框，用于共享账户信息以进行预填和身份检查。
如果不勾选，客户可自行输入这些信息。

在 **验证选项** 下，已登录的客户可以请求人工审核，或撤回同意并请求删除其验证数据。
人工审核会暂停自动验证，并在 **应用 → Didit Verify → 人工审核** 中添加一项请求。
在完成该请求之前，请先联系客户并安排合适的替代方案。
完成人工审核请求并不会批准验证或购买。

撤回同意后，现有验证链接会立即失效，并且在删除处理期间不允许新的验证。
店铺前台仅确认已收到请求，不会声称删除已经完成。

## 履行隐私请求

打开 **应用 → Didit Verify → 隐私**，跟踪从 Shopify 或店铺前台收到的客户导出和删除请求。

* **客户导出：** 下载准备好的 ZIP 文件，通过您的安全客户支持流程提供给客户，然后选择 **我已提供此导出**。
* **客户删除：** 在该客户与店铺关联的验证记录、上传文件和人工审核请求全部删除之前，请求将保持进行中状态。
* **需要处理：** 按照请求中的说明解决缺失的客户 ID；如果资料包含来自其他店铺或其他用途的数据，请联系 Didit 支持。

导出内容包括与发起请求的店铺和客户相关的验证记录、上传文件和人工审核请求。
临时下载将在七天后失效；如有需要，请使用 **解决后重试** 重新生成新的下载文件。
下载的导出文件必须按照您自己的客户支持和数据保护流程进行处理。

在 **设置 → 数据保留** 中设置保留期限。
超过保留期限的旧验证数据将被自动删除；较新的验证数据仍可使用。
未选择店铺专属保留期限时，应用级别的现有保留策略继续适用。
请检查 **隐私** 中是否有需要处理的保留请求。

删除请求显示 **已删除** 后，删除操作不可逆，被删除的媒体文件将无法再获取。
已消耗的额度和单独管理的黑名单条目不受影响。

## 主题模块设置

在 Shopify 主题编辑器中选择 Didit Verify 模块时，可以配置以下设置：

#### 连接

| 设置 | 说明 |
| - | - |
| **模式** | **应用工作流**（推荐）使用应用设置中保存的工作流。**UniLink 工作流** 使用所连接 Didit 账户中的公开工作流链接。两种模式都会创建与店铺关联的会话，结果可在应用中查看。 |
| **UniLink URL** | 仅在 UniLink 模式下使用。请使用应用设置中所连接 Didit 账户的有效链接。客户必须登录其店铺账户。 |

#### 显示

| 设置 | 说明 |
| - | - |
| **显示模式** | **弹窗**：在弹出的覆盖层中打开验证。**内嵌**：在按钮下方以内嵌形式显示验证。 |
| **显示关闭按钮** | 显示或隐藏用于关闭验证弹窗的 X 按钮 |
| **退出确认对话框** | 关闭验证前要求用户确认 |
| **完成后自动关闭** | 验证完成后自动关闭弹窗 |
| **调试日志** | 启用浏览器控制台日志，用于排查问题 |

#### 按钮外观

| 设置 | 说明 |
| - | - |
| **按钮文本** | 按钮上显示的文本（默认值："验证您的身份"） |
| **成功文本** | 验证成功后显示的文本（默认值："身份已验证 ✓"） |
| **背景颜色** | 按钮背景颜色 |
| **文本颜色** | 按钮文本颜色 |
| **圆角半径** | 按钮圆角大小（0–50px） |
| **垂直内边距** | 上下内边距（0–40px） |
| **水平内边距** | 左右内边距（0–60px） |
| **字号** | 按钮文本字号（10–32px） |

***

## 推荐设置

对于大多数店铺，我们推荐以下设置：

* **模式：** 应用工作流（使用应用设置中保存的工作流）
* **显示模式：** 弹窗（在所有场景下都可正常使用，不会出现布局问题）
* **要求客户登录：** 启用（将验证与客户账户关联）
* **允许客户同意后预填：** 启用（由客户选择是否分享其店铺资料）

***

## 测试

1. 预览您的主题或访问您的店铺
2. 进入带有 Didit Verify 按钮的页面
3. 点击 **验证您的身份**
4. 完成验证流程
5. 检查您的后端是否收到 Webhook 投递，或调用 [GET /v3/session/{id}/decision/](https://docs.didit.me/zh/sessions-api/retrieve-session.md) 获取验证结果

> [!NOTE]
>
> 沙盒免费（每个沙盒应用每 24 小时可创建 500 个测试会话），因此您可以零成本测试完整流程。在正式模式下，免费套餐每月包含 \$10 的额度。

***

## 故障排除

### 点击按钮没有反应

* 请确认您已在偏好设置中保存 API 密钥和 Workflow ID
* 检查 Workflow ID 是否属于与您的 API 密钥相同的应用
* 在模块设置中启用 **调试日志**，并在浏览器控制台中检查错误

### 出现 "未配置 Didit 凭据" 错误

* 该店铺的应用中没有保存 API 密钥或 Workflow ID。打开 **应用** → **Didit Verify**，填写这两个字段，然后点击 **保存设置**

### 出现 "您必须登录才能验证身份" 提示

* **要求客户登录** 已启用（默认设置）。客户需要先登录其店铺账户。如果您需要允许访客验证，请在应用偏好设置中关闭该设置

### 设置无法保存

* "API 密钥验证失败"：请从 [Didit Business Console](https://business.didit.me) 重新复制 API 密钥，并确保没有多余的空格
* "此工作流不属于您的应用"：该 Workflow ID 属于与您的 API 密钥不同的 Didit 应用。请从同一个应用中复制这两项内容

## 支持 (24/7)

我们的团队随时为您提供帮助，助您快速上手。

> [card] [电子邮件](mailto:hello@didit.me)
>
> 请发送邮件至 [hello@didit.me](mailto:hello@didit.me) 与我们联系。


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