以文件驗證 - Fluz

請求 IDV URL 是較高保證的 API 方法，且當傳遞 SSN 資訊給我們未獲核准時可作為後備方案。您不需要自行蒐集身分文件，而是向 Fluz 請求一個託管驗證連結，然後交給您的客戶。Fluz 會直接收集並審查這些文件。

先決條件

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

運作方式

您識別客戶並請求連結

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

Fluz 回傳一組驗證連結

回應中包含 verificationUrl 與 verificationId。請儲存 verificationId — 您將以此對應最終送達 webhook 的事件與此次請求。

您將連結交付給客戶

依產品合適的方式傳送：電子郵件、簡訊、推播通知，或在 App 內重新導向。客戶可隨時完成驗證。

您的客戶上傳他們的文件

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

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	人類可讀的詳細資訊。

客戶所見

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

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

在回傳決策前，會對文件真偽、是否被竄改，以及生物特徵比對結果進行全面審查。

接收結果

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

APPROVED — 客戶已通過驗證。開放相應功能。
DECLINED — 客戶未通過驗證。文件驗證是升級路徑中的最後一步；此處被拒通常需要人工審查，而非再進行另一個自動化嘗試。

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

測試

在測試環境中，您可以使用示例駕照與測試身分完成整個文件流程。測試環境不會強制執行文件真偽與其他安全特徵，您也可以在背面擷取時重複使用正面的影像。請參閱測試 KYC 流程。

​運作方式

​請求

​範例

開啟示範配方

​回應欄位

​客戶所見

​接收結果

​測試

運作方式

請求

範例

回應欄位

客戶所見

接收結果

測試