概览 - Fluz

Fluz 要求客户在进行某些交易之前通过身份验证（KYC），并且验证将解锁更高的交易限额。在客户完成验证之前，平台的部分功能——为钱包充值、提现、以及虚拟卡发行——对其不可用。有两种方式为客户完成验证。选择取决于您希望由 Fluz 主导验证体验，还是由您自己主导。

通过小组件验证

嵌入 Fluz 小组件。验证作为内置步骤处理——Fluz 在其托管的 UI 中直接向客户收集全部信息。您无需收集或存储任何数据。

通过 API 验证

由您自行提交验证。您端到端掌控体验，并可为每位客户选择使用哪种方法。

通过小组件进行验证

如果您已经嵌入了 Fluz 小组件，可能完全不需要构建验证流程。小组件将验证作为闸门：当尚未验证的客户进入小组件时，小组件会引导其完成验证，然后将其返回到先前正在进行的任务。这是投入最少的路径，也是唯一一条身份数据永不接触您系统的路径。参见通过小组件验证。

通过 API 进行验证

如果您直接集成 API，则由您自行提交验证。目前有四种可用方法，它们在您需要向客户收集哪些信息——以及由谁执行验证——方面有所不同。

KYC 自动填充

您无需收集任何信息。Fluz 使用已存档的数据通过 verifyUserPrefillInformation 解析并验证客户身份。

向我们传递 SSN 信息

您收集客户的法定姓名、地址、出生日期和 SSN，然后使用 verifyUserInformation 提交以获得即时决策。

请求 IDV 链接

您使用 requestDocumentVerificationLink 请求一个验证链接。Fluz 返回一个托管 URL；您的客户将其政府签发的身份证件与自拍直接上传至 Fluz。

自带 KYC

您的平台已通过自有提供商运行 KYC。使用 postKycVerification 提交已决策的结果；Fluz 会记录并更新客户状态。

在 API 方法间进行选择

首先要确定由谁执行验证。如果您的平台运营自有、已获批准的 KYC 项目，请使用通过外部提供商验证——它向 Fluz 报告您的决策，而非请求决策，下面的升级阶梯不适用。对于由 Fluz 执行验证的三种方法，大多数集成会在低摩擦尝试未成功时再逐步升级：

先尝试 KYC 自动填充

这是一条无需收集任何字段的同步调用，并且每位客户只运行一次。将其作为默认的首次尝试。

回退到 SSN 验证

如果自动填充被拒，并且您已持有——或可合理要求获取——客户的身份详细信息，请直接提交以获得另一次即时决策。

回退到 IDV 链接

如果 SSN 验证也被拒，请请求一个验证链接并让客户上传其证件与自拍照。这是更高保证的路径，并以异步方式完成。

客户只需通过一次，并且所有方法共享一个验证状态。一旦客户通过任一方法（包括通过小组件）达到 APPROVED，后续由 Fluz 执行的尝试将以 ERROR 状态被拒绝。外部提供商结果是例外：仍会被记录以供审计，但不会更改客户状态。

每种方法都有一份可在本页直接演练的食谱：

食谱：请求 KYC 自动填充

准备 verifyUserPrefillInformation 变更

无需收集输入——客户完全由 access token 标识。

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

const VERIFY_USER_PREFILL_INFORMATION = gql`
  mutation verifyUserPrefillInformation {
    verifyUserPrefillInformation {
      status
      message
    }
  }
`;

准备 GraphQL 客户端

使用为待验证客户生成的用户 access token进行认证。

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

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

处理请求

决策会在同一响应中返回。

const response = await client.request(VERIFY_USER_PREFILL_INFORMATION);

console.log(response);

Response

{
  "data": {
    "verifyUserPrefillInformation": {
      "status": "APPROVED",
      "message": "User verification successful"
    }
  }
}

可复制运行版本：请求 KYC 自动填充。完整字段参考：KYC 自动填充。

食谱：请求用户 KYC 验证

准备 verifyUserInformation 变更

传入要验证的用户信息。

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

const VERIFY_USER_INFORMATION = gql`
  mutation verifyUserInformation($input: VerifyUserInformationInput!) {
    verifyUserInformation(input: $input) {
      status
      message
    }
  }
`;

准备 GraphQL 客户端

使用为待验证客户生成的用户 access token进行认证。

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

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

处理请求

决策会在同一响应中返回。

const response = await client.request(VERIFY_USER_INFORMATION, {
  input: {
    firstName: 'John',
    lastName: 'Smith',
    streetLine1: '123 Main St',
    streetLine2: '',
    city: 'Los Angeles',
    state: 'CA',
    postalCode: '91234',
    country: 'United States',
    dateOfBirth: '01/28/1975',
    ssnLast4: '1234',
  },
});

console.log(response);

Response

{
  "data": {
    "verifyUserInformation": {
      "status": "APPROVED",
      "message": "User verification successful"
    }
  }
}

可复制运行版本：请求用户 KYC 验证。完整字段参考：通过 SSN 验证。

食谱：请求证件验证链接

准备 requestDocumentVerificationLink 变更

客户由 access token 标识，因此输入仅包含同意与预填充标记。

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

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

准备 GraphQL 客户端

使用为待验证客户生成的用户 access token进行认证。

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

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

处理请求

将返回的 verificationUrl 交付给您的客户，并存储 verificationId 以便对账承载结果的 webhook。

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"
    }
  }
}

可复制运行版本：请求证件验证链接。完整字段参考：通过证件验证。

所需 scope

每种验证方法都需要 VERIFY_KYC scope，它允许您的应用代表客户发起身份验证请求。

VERIFY_KYC 不是自助开通。必须由 Fluz 在您的应用上启用——在开始构建之前，请联系您的 Fluz 对接人开通。

权限有两层，且您需要同时具备：

Layer	What it is	How it is granted
Application scope	您的应用被允许发起验证请求。	由 Fluz 在您的应用上启用。
Customer authorization	单个客户授权您的应用代表其提交验证。	在 OAuth 流程中由客户授予。小组件应用会自动请求该授权。

在您生成用于调用的用户 access token时也必须包含该 scope。完整目录参见应用 Scopes。

设置 webhook

在发送首个验证之前注册一个 webhook 端点。验证并非总在 API 响应内完成——尤其是证件验证，会在客户选择完成的任意时间点结束，可能是您请求链接后的几分钟或几天。小组件中的验证完全在您的应用之外完成。Webhook 是您获知结果的方式。

不要轮询验证状态，也不要将未收到 webhook 视为被拒。请注册端点并对事件作出响应。

端点要求、签名校验、重试行为与负载格式参见Webhooks。简而言之：

在开发者门户为您的应用注册一个 HTTPS 端点。使用接收 URL 本身——不要使用其仪表盘或检视视图的地址。
在 webhook 配置中订阅 KYC_STATUS_UPDATE 事件。否则无论您使用哪种验证方法，都不会收到 KYC 状态更新。
在每次投递中，基于原始请求体验证 X-HMAC-Signature 头。
基于 X-Event-ID 去重，并在 30 秒内返回 2xx。

您的应用——以及对于 OAuth 与小组件应用，单个客户的授权——必须具备 VERIFY_KYC 才能接收验证事件。 KYC_STATUS_UPDATE 仅在客户的 KYC 状态实际发生“转换”时触发。对于已验证客户而再次记录的验证，会保留其状态且不触发事件——在该情况下，请以 API 响应为准。负载会携带旧状态与新状态以及验证数据；完整结构见KYC 状态更新。

验证状态

每种方法都会解析为以下状态之一。

Status	Message	Description
`APPROVED`	User verification successful	客户已通过 KYC 验证。
`DECLINED`	Verification declined	客户未通过 KYC 验证。您可以升级到其他方法。
`DUPLICATE`	Duplicate user verification	客户已验证，但其 SSN 与现有 Fluz 客户匹配。
`ERROR`	Error encountered with user verification	请求无法处理。参见尝试次数限制。

DUPLICATE 的判定基于SSN——对于外部提供商结果，还包括证件号码——从不基于地址，因为客户在不同时间点拥有多个地址是合理的。Fluz 不会披露匹配到的其他客户。

当客户已验证、已达到验证尝试上限、或已达到证件验证上限时，将返回 ERROR 状态。

尝试次数限制

为防止客户通过猜测获得通过，验证尝试次数受到限制。

客户可通过 API 以同一用户 ID 尝试 SSN 验证最多3 次。
证件验证请求单独计数并限制。
KYC 自动填充每位客户仅运行一次，无论通过或被拒。
一旦客户为 APPROVED，不再接受进一步尝试。
通过外部提供商验证是例外：您在报告结果而非请求筛查，因此没有尝试上限——且对于已验证客户的提交将记录用于审计而不改变其状态。

地址格式

每种接收地址的方法都期望客户的居住地址以结构化字段填写，且城市、州与邮编一致。地址格式错误或不匹配是导致本可通过的客户被 DECLINED 的常见原因。

邮政信箱（PO box）不被接受为法定地址，会导致验证失败。请提交实体街道地址。

接受国际地址。完整规则见地址格式要求。

测试

在上线前，请使用预发布环境与已公布的测试身份覆盖每条路径，包括有意的拒绝情形。参见测试 KYC 流程。

通过小组件验证

通过 API 验证

​通过小组件进行验证

​通过 API 进行验证

KYC 自动填充

向我们传递 SSN 信息

请求 IDV 链接

自带 KYC

​在 API 方法间进行选择

​所需 scope

​设置 webhook

​验证状态

​尝试次数限制

​地址格式

​测试

通过小组件进行验证

通过 API 进行验证

在 API 方法间进行选择

所需 scope

设置 webhook

验证状态

尝试次数限制

地址格式

测试