概览 - Fluz

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

通过小组件验证

嵌入 Fluz 小组件。验证作为内置步骤处理——Fluz 在 Fluz 托管的界面中从客户处收集一切。您无需收集或存储任何数据。

通过 API 验证

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

通过小组件进行验证

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

通过 API 进行验证

如果您直接对接 API，则由您自行提交验证。当前有三种可用方法，它们在您从客户处收集的信息上有所不同。

KYC 自动填充

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

向我们提交 SSN 信息

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

请求 IDV 链接

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

在 API 方法间进行选择

大多数集成仅在低摩擦尝试未成功时再逐步升级：

先尝试 KYC 自动填充

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

回退到 SSN 验证

若自动填充被拒，并且您已持有——或可合理索取——客户的身份详情，则直接提交以获得另一轮即时决策。

回退到 IDV 链接

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

客户只需通过一次，且所有方法共享同一个验证状态。一旦客户达到 APPROVED——无论通过何种方法，包括小组件——后续尝试都会以 ERROR 状态被拒绝。

每种方法都有一份食谱，您可以在此页面上直接逐步完成：

食谱：请求 KYC 自动填充

准备 verifyUserPrefillInformation 变更

无需收集任何输入——客户完全由访问令牌标识。

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

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

准备 GraphQL 客户端

使用为待验证客户生成的用户访问令牌进行认证。

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 客户端

使用为待验证客户生成的用户访问令牌进行认证。

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 变更

客户由访问令牌标识，因此输入仅包含同意与预填标志。

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 客户端

使用为待验证客户生成的用户访问令牌进行认证。

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 对接人开启。

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

层级	含义	授权方式
应用 scope	您的应用被允许发起验证请求。	由 Fluz 在您的应用上启用。
客户授权	单个客户允许由“您的”应用代表其提交验证。	由客户在 OAuth 流程中授予。小组件应用会自动请求。

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

设置 webhook

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

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

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

在开发者门户为您的应用注册一个 HTTPS 端点。
订阅身份验证事件。
在每次投递时，基于原始请求体验证 X-HMAC-Signature 头。
基于 X-Event-ID 去重，并在 30 秒内返回 2xx。

您的应用——以及对于 OAuth 和小组件应用，还包括单个客户的授权——必须持有 VERIFY_KYC 才能接收验证事件。

验证状态

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

状态	消息	描述
`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 进行 最多 3 次 SSN 验证尝试。
文档验证请求有单独的上限。
KYC 自动填充每位客户仅运行一次，无论通过或拒绝。
一旦客户为 APPROVED，不再接受任何后续尝试。

地址格式

所有接收地址的方法都要求在结构化字段中提供客户的居住地址，并保证城市、州和邮政编码一致。格式错误或不匹配的地址是本可通过的客户被判为 DECLINED 的常见原因。

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

支持国际地址。完整规则参见地址格式要求。

测试

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

通过小组件验证

通过 API 验证

​通过小组件进行验证

​通过 API 进行验证

KYC 自动填充

向我们提交 SSN 信息

请求 IDV 链接

​在 API 方法间进行选择

​所需 scope

​设置 webhook

​验证状态

​尝试次数限制

​地址格式

​测试

通过小组件进行验证

通过 API 进行验证

在 API 方法间进行选择

所需 scope

设置 webhook

验证状态

尝试次数限制

地址格式

测试