由外部供應商進行驗證

如果您的平台已使用自有的身分驗證供應商執行 KYC，您的客戶就不應該需要驗證兩次。使用 postKycVerification 將已決策的結果提交給 Fluz。不同於其他 API 方法，Fluz 在此不會自行篩核身分 — 決策由您負責。Fluz 只會驗證與記錄結果，並相應更新客戶的狀態。

先決條件

由 Fluz 核准、適用於您應用的外部 KYC 計畫。請在使用此方法前聯絡您的客戶經理。
Fluz 為您的應用啟用 VERIFY_KYC 範圍。請參閱必要範圍。
為待驗證客戶產生的使用者存取權杖，其範圍包含 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 自動填入，且您提交的任何值都會被覆寫。

Field	Type	Required	Description
`schemaVersion`	String	Yes	承載合約的版本。目前為 `"1.0"`。
`externalVerificationProvider`	String	Yes	`IDOLOGY`、`OSCILAR`、`PERSONA` 或 `CUSTOM`。
`externalVerificationId`	String	Yes	您供應商對此嘗試的全球唯一 ID — 冪等性鍵。
`decision`	String	Yes	`PASSED` 或 `FAILED`。
`decisionReason`	String	No	產生此決策的人類可讀原因或規則。
`decisionedAt`	String	No	決策的 ISO 8601 時戳。預設為匯入時間。
`person`	JSON	Yes	由供應商所建立的已驗證身分。
`verifications`	JSON	Yes	支撐決策的供應商驗證 — 至少需包含 `document`、`ssn` 或 `database` 其中一項。
`externalProviderData`	JSON	No	供稽核使用的自由格式供應商情境資料。

完整欄位參考（包含 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"
    }
  }
}

處理回應

Status	What to do
`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 會抓取並儲存這些影像。

​運作方式

​請求

​範例

​處理回應

​測試

運作方式

請求

範例

處理回應

測試