由外部提供商进行验证

如果您的平台已经通过自己的身份提供商运行 KYC，您的客户不应需要验证两次。使用 postKycVerification 将已决策的结果提交给 Fluz。与其他 API 方法不同，Fluz 在此不会自行筛查身份——决策由您做出。Fluz 只会对其进行验证和记录，并相应更新客户状态。

先决条件

由 Fluz 为您的应用批准的外部 KYC 方案。请在针对该方法进行开发之前与您的客户经理沟通。
Fluz 在您的应用上启用的 VERIFY_KYC scope。参见所需 scope。
为待验证客户生成的用户访问令牌，其 scopes 中包含 VERIFY_KYC。
为您的环境提供的专用安全摄取端点，会上线时提供。

将此 mutation 发送到专用安全摄取端点，而不是标准 API 主机。该端点会在传输过程中安全地将 person.ssn 等 PII 数据进行代币化。若请求中的 SSN 或其他 PII 数据未代币化即到达，将被拒绝。请始终将参数作为 GraphQL 变量传递；内联到查询文档中的值无法被代币化。

Staging: https://secure.transactional-graph.staging.fluzapp.com/api/v1/graphql
Production: 上线时提供

工作原理

postKycVerification mutation 是同步的。您提交已验证的身份以及支撑您决策的提供商验证，Fluz 会在响应体中返回 APPROVED、DECLINED、DUPLICATE 或 ERROR。无客户交互步骤。以下行为是该方法特有的：

仅限已决策结果。 decision 必须为 PASSED 或 FAILED。不要发送待定或未决策的验证。
幂等性。 提交以 externalVerificationId（您提供商针对该尝试的唯一 id）为幂等键。重放某个 id 会返回原始结果且不写入；已重新作出决策的验证必须以新的 id 提交。
状态转换。 PASSED 结果会将未验证客户变为已验证。若客户已通过任何方法完成验证，该验证仍会被记录以供审计，但其状态不会被更改；响应消息会注明保留了现有状态。FAILED 结果会被记录且不会改变状态。
无尝试次数限制。 因为您是报告结果而非请求筛查，此方法没有尝试次数限制，也不计入通过 SSN 验证或 KYC 自动填充的限制。

请求

客户通过 Authorization 头中的用户访问令牌进行标识——person.userId 和您的应用身份由 Fluz 填充，且会覆盖任何提交的值。

字段	类型	必填	说明
`schemaVersion`	String	是	载荷契约的版本。目前为 `"1.0"`。
`externalVerificationProvider`	String	是	`IDOLOGY`、`OSCILAR`、`PERSONA` 或 `CUSTOM`。
`externalVerificationId`	String	是	您提供商针对本次尝试的全局唯一 id——幂等键。
`decision`	String	是	`PASSED` 或 `FAILED`。
`decisionReason`	String	否	产生该决策的人类可读原因或规则。
`decisionedAt`	String	否	决策的 ISO 8601 时间戳。默认为摄取时间。
`person`	JSON	是	由提供商确立的已验证身份。
`verifications`	JSON	是	支撑该决策的提供商验证——至少包含 `document`、`ssn` 或 `database` 之一。
`externalProviderData`	JSON	否	供审计使用的自由格式提供商上下文。

参见 postKycVerification 获取完整字段参考，包括 person 与 verifications 对象结构。

示例

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

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

const POST_KYC_VERIFICATION = gql`
  mutation postKycVerification(
    $schemaVersion: String!
    $externalVerificationProvider: String!
    $externalVerificationId: String!
    $decision: String!
    $decisionReason: String
    $person: JSON!
    $verifications: JSON!
  ) {
    postKycVerification(
      schemaVersion: $schemaVersion
      externalVerificationProvider: $externalVerificationProvider
      externalVerificationId: $externalVerificationId
      decision: $decision
      decisionReason: $decisionReason
      person: $person
      verifications: $verifications
    ) {
      status
      verificationId
      message
    }
  }
`;

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

const response = await client.request(POST_KYC_VERIFICATION, {
  schemaVersion: '1.0',
  externalVerificationProvider: 'PERSONA',
  externalVerificationId: 'inq_gCf28LrXY9wrxDoZbnbEqTrn',
  decision: 'PASSED',
  decisionReason: 'All checks passed',
  person: {
    firstName: 'JANE Q',
    lastName: 'SAMPLE',
    dateOfBirth: '1990-01-01',
    ssn: '900-98-7654',
    ssnLast4: '7654',
    address: {
      streetLine1: '123 EXAMPLE STREET',
      city: 'SAMPLETOWN',
      subdivision: 'CA',
      postalCode: '90001',
      countryCode: 'US',
    },
  },
  verifications: {
    document: {
      verificationId: 'ver_p8qmKydzkQwyLKbaAJRvADi9',
      status: 'PASSED',
      documentClass: 'DRIVER_LICENSE',
      documentNumber: 'X90000000000001',
      issuingCountryCode: 'US',
      photos: { front: 'https://files.provider.example/front.jpg' },
      checks: [{ name: 'id_expired_detection', status: 'PASSED' }],
    },
    ssn: {
      verificationId: 'ver_tin_snW2CvL2x4kTdZjbmGBjqcuV',
      status: 'PASSED',
      source: 'TIN_DATABASE',
    },
  },
});

console.log(response);

Response

{
  "data": {
    "postKycVerification": {
      "status": "APPROVED",
      "verificationId": "4b99e8c5-4201-45fd-a5dc-1c3b88e4f6c7",
      "message": "User verification successful"
    }
  }
}

处理响应

状态	应对措施
`APPROVED`	验证已记录。若客户此前未验证，则现已验证；若其已验证，`message` 会注明保留了现有状态。
`DECLINED`	已记录 `FAILED` 结果。客户状态不变。
`DUPLICATE`	验证已记录，但 SSN 或证件号码与另一位 Fluz 客户匹配。该账户将被置于审查状态——请先在您侧调查后再继续。Fluz 不会披露匹配到的是哪位客户。
`ERROR`	检查 `message`——最常见为未通过契约校验的载荷。未记录任何内容。

测试

使用伪造身份对 staging 端点进行测试——因为决策由您做出，因此不像其他方法那样存在提供商测试身份要求。使用 900-XX-XXXX 范围（从未签发）的 SSN，每次尝试生成一个新的 externalVerificationId（重放某个 id 会返回原始结果，而非触发新的执行），并确保您发送的任何照片 URL 可被获取——Fluz 会拉取并存储这些图像。

​工作原理

​请求

​示例

​处理响应

​测试

工作原理

请求

示例

处理响应

测试