透過文件驗證

請求 IDV URL 是保證度更高的 API 方法，亦是在傳遞 SSN 資訊給我們未獲核准時的後備機制。您不需自行蒐集身分文件；改為向 Fluz 請求一個託管的驗證連結，再交給您的客戶。Fluz 會直接蒐集並審查文件。

先決條件

Fluz 為您的應用程式啟用 VERIFY_KYC 範圍。請參閱必要範圍。
為要驗證的客戶產生的使用者存取權杖，其範圍包含 VERIFY_KYC。
已註冊的 webhook 端點。文件驗證必須具備此項 — 結果不會出現在 API 回應中。請參閱驗證客戶。

運作方式

您識別客戶並請求連結

使用為該客戶產生的使用者存取權杖呼叫 requestDocumentVerificationLink。此權杖用於告知 Fluz 這筆驗證屬於哪位客戶。

Fluz 回傳驗證連結

回應包含 verificationUrl 與 verificationId。請儲存 verificationId — 您將以此對應日後的 webhook 與此次請求。

您將連結交付給您的客戶

依您的產品情境傳送：電子郵件、SMS、推播通知，或應用程式內導向。客戶可在任一時間完成驗證。

您的客戶上傳其文件

在託管頁面上，客戶需拍攝政府核發證件的正反面（駕照、護照、州身分證、或軍人證），並自拍以進行生物特徵比對。

Fluz 通知您結果

客戶完成後，Fluz 會審查提交內容，並將 APPROVED 或 DECLINED 結果傳送至您的 webhook 端點。

驗證連結僅對單一客戶與單次驗證嘗試有效。切勿在不同客戶間重複使用、將其記錄於共用系統、或曝光於非目標客戶可能看到之處 — 該連結可存取一個身分提交工作階段。

請求

Field	Type	Required	Description
`gaveConsent`	Boolean	Yes	客戶是否同意進行身分驗證。必須為 `true`，否則請求會被拒絕。
`prefillData`	Boolean	Yes	是否以 Fluz 既有的身分資訊預先填入驗證表單。當為 `true` 時，您無需傳送以下欄位。
`firstName`	String	No	客戶的法定名字。
`lastName`	String	No	客戶的法定姓氏。
`streetLine1`	String	No	居住街道地址。
`streetLine2`	String	No	公寓、套房或單位。
`city`	String	No	城市。
`region`	String	No	州或地區。
`postalCode`	String	No	郵遞區號。
`country`	String	No	國家，使用 ISO 3166-1 alpha-2 格式。
`dateOfBirth`	String	No	出生日期，格式為 `YYYY-MM-DD`。
`emailAddress`	String	No	客戶的電子郵件地址。
`phoneNumber`	String	No	客戶的電話號碼，E.164 格式。

在將 gaveConsent: true 設定於請求前，您必須先取得並紀錄客戶的同意。您所傳遞的任何資料都會用來預先填入表單 — 客戶可在提交前檢視並更正，因此請將這些欄位視為便利性資料，而非最終要被驗證的值。

請注意與SSN 驗證的欄位命名差異：此 mutation 使用 region，而另一個使用 state；且此處 dateOfBirth 期望為 YYYY-MM-DD，而非 MM/DD/YYYY。

範例

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

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

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

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

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

此回應中的 status（OK）僅確認連結已發出 — 並非驗證決定。最終決定會稍後透過 webhook 抵達。

回應欄位

Field	Type	Description
`userId`	UUID	進行此驗證的 Fluz 客戶。
`verificationType`	String	永遠為 `DOCUMENT_VERIFICATION`。
`verificationId`	String	此次驗證嘗試的識別碼。請儲存以對應 webhook。
`verificationUrl`	String	要交付給客戶的託管連結。
`status`	String	當連結成功發出時為 `OK`。
`message`	String	人類可讀的詳細訊息。

客戶所見內容

託管流程會預先填入已知資訊供客戶檢視，接著要求他們：

拍攝一張受支援的政府核發照片證件的正反面。
拍攝自拍照，並與證件照進行生物特徵比對。

在回傳決定前，系統會檢查文件真實性、是否遭竄改，以及生物特徵比對結果。

接收結果

由於客戶可能在您發出連結後很久才完成驗證，結果會傳送至您的 webhook 端點。請將收到的事件與您儲存的 verificationId 進行比對，然後依結果採取動作：

APPROVED — 客戶已通過驗證。請解鎖相關功能。
DECLINED — 客戶未通過驗證。文件驗證是升級流程中的最後一步；在此被拒通常需要人工覆核，而非再進行一次自動化嘗試。

每位客戶的文件驗證請求次數有限。達到上限後，後續請求會回傳 ERROR，並帶有 Exceeded document verification limit。

測試

在階段環境中，您可以使用範例駕照與測試身分完成整個文件流程。文件真偽及其他安全功能在階段環境中不會強制檢查，您也可以重複使用正面影像作為反面拍攝。請參閱測試 KYC 流程。

​運作方式

​請求

​範例

​回應欄位

​客戶所見內容

​接收結果

​測試

運作方式

請求

範例

回應欄位

客戶所見內容

接收結果

測試