通过外部提供商验证

如果你的平台已经使用自有的身份提供商运行 KYC，你的客户不应当被要求重复验证。使用 postKycVerification 将已决策的结果提交给 Fluz。与其他 API 方法不同，此处 Fluz 不对身份本身进行筛查——决策由你做出。Fluz 仅进行校验与记录，并相应更新客户状态。

先决条件

一个已获 Fluz 批准、可用于你应用的外部 KYC 方案。请在集成此方法前先与客户经理沟通。
你的应用在 Fluz 侧已启用 VERIFY_KYC scope。参见所需 scope。
为待验证客户生成的用户访问令牌，其 scopes 中包含 VERIFY_KYC。
为你的环境提供的专用安全接入端点，会上线时提供。

将此 mutation 发送到专用安全接入端点，而不是标准 API 主机。该端点可在传输过程中安全地对 person.ssn 等 PII 数据进行代币化。若请求中的 SSN 或其他 PII 数据未被代币化，系统将拒绝请求。务必将参数作为 GraphQL variables 传递；内联到查询文档的值无法被代币化。

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	否	供审计使用的自由格式提供商上下文。

完整字段参考（包括 person 与 verifications 对象结构）参见 postKycVerification。

示例

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`——最常见为载荷未通过契约校验。未记录任何内容。

当提交导致客户的 KYC 状态发生变化时，Fluz 也会向你注册的 webhook 发布 KYC_STATUS_UPDATE 事件——这是所有验证方法都会触发的相同事件。你的 webhook 配置需包含该事件才能接收，且仅在状态发生变更时触发；参见设置 webhook。

测试

使用伪造身份对 staging 端点进行测试——因为决策由你方给出，无需像其他方法那样满足提供商的测试身份要求。使用 900-XX-XXXX 区间（从未签发）的 SSN，每次尝试生成新的 externalVerificationId（重放同一 id 会返回原结果，而非触发新的流程），并确保你发送的任何照片 URL 可被访问——Fluz 会获取并存储这些图片。

​工作原理

​请求

​示例

​处理响应

​测试

工作原理

请求

示例

处理响应

测试