通过证件验证

请求 IDV URL 是更高保障的 API 方法，也是当向我们传递 SSN 信息未获批准时的回退方案。与其自行收集身份文件，不如从 Fluz 请求一个托管验证链接并交给您的客户。Fluz 将直接收集并筛查这些文件。

先决条件

由 Fluz 在您的应用上启用 VERIFY_KYC 范围。参见所需范围。
为待验证客户生成的用户访问令牌，其范围中包含 VERIFY_KYC。
已注册的 webhook 端点。文档验证必须使用 webhook —— 结果不会在 API 响应中返回。参见验证客户。

工作原理

您识别客户并请求链接

使用为该客户生成的用户访问令牌调用 requestDocumentVerificationLink。该令牌用于告知 Fluz 此次验证归属哪个客户。

Fluz 返回验证链接

响应包含 verificationUrl 和 verificationId。请保存 verificationId —— 它用于将最终的 webhook 与本次请求对应起来。

您将链接发送给客户

根据产品适配的方式发送：电子邮件、短信、推送通知，或应用内跳转。客户可在任何时间完成验证。

您的客户上传其证件

在托管页面上，客户拍摄政府签发证件（驾照、护照、州身份证或军人证）的正反面，并拍摄自拍以进行生物特征比对。

Fluz 通知您结果

当客户完成后，Fluz 对提交内容进行筛查，并将 APPROVED 或 DECLINED 结果发送到您的 webhook 端点。

该验证链接唯一对应于一个客户的一次验证尝试。切勿在客户之间复用链接、将其记录在共享系统中，或在非目标客户是唯一阅读者的场所暴露它 —— 它可授予对身份提交会话的访问权限。

请求

Field	Type	Required	Description
`gaveConsent`	Boolean	Yes	客户是否同意进行身份验证。必须为 `true`，否则请求将被拒绝。
`prefillData`	Boolean	Yes	是否使用 Fluz 已持有的身份信息预填验证表单。当为 `true` 时，无需发送下列字段。
`firstName`	String	No	客户的法定名。
`lastName`	String	No	客户的法定姓。
`streetLine1`	String	No	住宅街道地址。
`streetLine2`	String	No	公寓、套房或单元。
`city`	String	No	城市。
`region`	String	No	州或地区。
`postalCode`	String	No	邮编或邮政编码。
`country`	String	No	国家，ISO 3166-1 alpha-2 格式。
`dateOfBirth`	String	No	出生日期，格式为 `YYYY-MM-DD`。
`emailAddress`	String	No	客户的电子邮箱地址。
`phoneNumber`	String	No	客户的电话号码，E.164 格式。

在设置 gaveConsent: true 前，您必须获取并记录客户的同意。您传递的任何内容都会用于预填表单 —— 客户可在提交前查看并更正，因此请将这些字段视为便利项，而非将被验证的最终值。

请注意与SSN 验证在字段命名上的差异：本次变更使用 region，而另一个使用 state；并且期望 dateOfBirth 为 YYYY-MM-DD，而非 MM/DD/YYYY。

示例

import { GraphQLClient, gql } from 'graphql-request';

const API_URL = 'https://transactional-graph.fluzapp.com/api/v1/graphql';

const REQUEST_DOC_VERIFICATION = gql`
  mutation RequestDocumentVerificationLink($input: RequestDocumentVerificationLinkInput!) {
    requestDocumentVerificationLink(input: $input) {
      userId
      verificationType
      verificationId
      verificationUrl
      status
      message
    }
  }
`;

const client = new GraphQLClient(API_URL, {
  headers: {
    Authorization: `Bearer <<USER_ACCESS_TOKEN>>`,
    'Content-Type': 'application/json',
  },
});

const response = await client.request(REQUEST_DOC_VERIFICATION, {
  input: {
    gaveConsent: true,
    prefillData: true,
  },
});

console.log(response);

Response

{
  "data": {
    "requestDocumentVerificationLink": {
      "userId": "eb910e93-5e39-4f53-99b9-0b033dd8e54b",
      "verificationType": "DOCUMENT_VERIFICATION",
      "verificationId": "idv_9MpDJC8aotDaxw",
      "verificationUrl": "https://verify.fluz.app/idv/idv_9MpDJC8aotDaxw?key=27f09ec042881c2c56945680c53108a4",
      "status": "OK",
      "message": "Verification link request successful"
    }
  }
}

此响应中的 status（OK）仅确认链接已签发 —— 并非验证决策。最终决策将通过 webhook 到达。

响应字段

Field	Type	Description
`userId`	UUID	此次验证所属的 Fluz 客户。
`verificationType`	String	始终为 `DOCUMENT_VERIFICATION`。
`verificationId`	String	此次验证尝试的标识符。请保存以用于对账 webhook。
`verificationUrl`	String	要发送给客户的托管链接。
`status`	String	当链接成功签发时为 `OK`。
`message`	String	人类可读的详细信息。

客户所见

托管流程会为客户预填已知信息以供复核，然后要求他们：

拍摄一张受支持的政府签发照片证件的正反面。
拍一张自拍照，并与证件照片进行生物特征比对。

在返回决策之前，会对证件的真实性、是否被篡改以及生物特征匹配进行全面筛查。

接收结果

由于客户可能在您签发链接后很久才完成验证，结果会发送到您的 webhook 端点。将传入事件与您保存的 verificationId 进行匹配，然后根据结果采取行动：

APPROVED — 客户已通过验证。解锁相关功能。
DECLINED — 客户未通过验证。文档验证是升级路径中的最后一步；此处被拒通常需要人工审核，而非再次进行自动尝试。

每位客户的文档验证请求都有上限。一旦达到上限，后续请求将返回 ERROR，并包含 Exceeded document verification limit。

测试

在预生产环境中，您可以使用示例驾照和测试身份完成完整的文档流程。预生产环境不会强制执行证件真伪和其他安全特性，您可以将正面图片重复用于反面拍摄。参见测试 KYC 流程。

​工作原理

​请求

​示例

​响应字段

​客户所见

​接收结果

​测试

工作原理

请求

示例

响应字段

客户所见

接收结果

测试