概覽 - Fluz

Fluz 要求客戶在進行特定交易前通過身分驗證（KYC），且驗證能解鎖更高的交易限額。客戶在通過驗證之前，平台的部分功能——為錢包加值、提領資金，以及虛擬卡簽發——對他們不可用。取得客戶驗證有兩種方式。選擇取決於您是否希望由 Fluz 主導驗證體驗，或由您自行主導。

透過小工具驗證

嵌入 Fluz 小工具。驗證作為內建步驟處理——Fluz 以 Fluz 代管的 UI 向客戶收集所有資料。您不需收集或儲存任何資訊。

透過 API 驗證

由您自行提交驗證。您可端到端掌控體驗，並為每位客戶選擇要使用的方法。

透過小工具進行驗證

如果您已嵌入 Fluz 小工具，可能完全不需要自行建立驗證流程。小工具將驗證作為閘道：當未驗證的客戶進入時，小工具會引導他們完成驗證，之後再將其帶回原本的操作。這是投入最少的路徑，也是唯一一種身分資料完全不會觸及您系統的方式。參見透過小工具驗證。

透過 API 進行驗證

如果您直接整合 API，將由您自行提交驗證。現有四種方法，它們在您需向客戶收集的資料——以及由誰執行驗證——方面有所不同。

KYC 自動填入

您無需收集任何資料。Fluz 透過既有檔案中的資料以 verifyUserPrefillInformation 解析並驗證客戶身分。

提供 SSN 資訊

您收集客戶的法定姓名、地址、出生日期及 SSN，接著用 verifyUserInformation 提交，以取得即時決策。

請求 IDV 連結

您以 requestDocumentVerificationLink 請求驗證連結。Fluz 回傳代管的 URL；您的客戶會直接向 Fluz 上傳政府核發身分證件與自拍照。

自帶 KYC

您的平台已透過自有供應商執行 KYC。使用 postKycVerification 提交已有決策的結果；Fluz 會記錄並更新客戶狀態。

在各種 API 方法之間做選擇

第一個問題是由誰執行驗證。如果您的平台營運經核准的自有 KYC 計畫，請使用透過外部供應商驗證——它是向 Fluz 回報您的決策，而非請求決策，且下方的升級階梯不適用。對於由 Fluz 執行驗證的三種方法，多數整合會在較低摩擦的嘗試未成功時再逐步升級：

先嘗試 KYC 自動填入

這是單一同步呼叫且無需收集欄位，每位客戶僅執行一次。將其作為預設的首次嘗試。

退回到 SSN 驗證

若自動填入被拒，且您已持有——或可合理要求取得——客戶的身分詳情，請直接提交，以取得另一個即時決策。

再退回到 IDV 連結

若 SSN 驗證也被拒，請求驗證連結並讓客戶上傳其身分證件與自拍照。這是更高保證度的路徑，且以非同步方式完成。

客戶只需通過一次，所有方法共用單一的驗證狀態。一旦客戶達到 APPROVED——無論透過任何方法，包括小工具——之後由 Fluz 執行的嘗試都會以 ERROR 狀態遭到拒絕。外部供應商的結果是例外：仍會被記錄以供稽核，但不會改變客戶的狀態。

每種方法都有可直接在此頁操作的使用範例：

範例流程：請求 KYC 自動填入

準備 verifyUserPrefillInformation mutation

無需收集任何輸入——客戶完全透過存取權杖識別。

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

const VERIFY_USER_PREFILL_INFORMATION = gql`
  mutation verifyUserPrefillInformation {
    verifyUserPrefillInformation {
      status
      message
    }
  }
`;

準備 GraphQL 用戶端

使用為該被驗證客戶產生的使用者存取權杖進行驗證。

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

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

處理請求

決策會在同一個回應中返回。

const response = await client.request(VERIFY_USER_PREFILL_INFORMATION);

console.log(response);

Response

{
  "data": {
    "verifyUserPrefillInformation": {
      "status": "APPROVED",
      "message": "User verification successful"
    }
  }
}

可複製執行版本：請求 KYC 自動填入。完整欄位參考：KYC 自動填入。

範例流程：請求使用者 KYC 驗證

準備 verifyUserInformation mutation

傳入要驗證的使用者資訊。

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

const VERIFY_USER_INFORMATION = gql`
  mutation verifyUserInformation($input: VerifyUserInformationInput!) {
    verifyUserInformation(input: $input) {
      status
      message
    }
  }
`;

準備 GraphQL 用戶端

使用為該被驗證客戶產生的使用者存取權杖進行驗證。

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

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

處理請求

決策會在同一個回應中返回。

const response = await client.request(VERIFY_USER_INFORMATION, {
  input: {
    firstName: 'John',
    lastName: 'Smith',
    streetLine1: '123 Main St',
    streetLine2: '',
    city: 'Los Angeles',
    state: 'CA',
    postalCode: '91234',
    country: 'United States',
    dateOfBirth: '01/28/1975',
    ssnLast4: '1234',
  },
});

console.log(response);

Response

{
  "data": {
    "verifyUserInformation": {
      "status": "APPROVED",
      "message": "User verification successful"
    }
  }
}

可複製執行版本：請求使用者 KYC 驗證。完整欄位參考：透過 SSN 驗證。

範例流程：請求文件驗證連結

準備 requestDocumentVerificationLink mutation

客戶由存取權杖識別，因此輸入只需包含同意與預填旗標。

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

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

準備 GraphQL 用戶端

使用為該被驗證客戶產生的使用者存取權杖進行驗證。

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

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

處理請求

將回傳的 verificationUrl 提供給您的客戶，並儲存 verificationId，以便對應承載結果的 webhook。

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

可複製執行版本：請求文件驗證連結。完整欄位參考：透過文件驗證。

必要的 scope

每種驗證方法都需要 VERIFY_KYC scope，允許您的應用程式代表客戶發起身分驗證請求。

VERIFY_KYC 無法自行啟用。必須由 Fluz 在您的應用程式上啟用——請聯絡您的 Fluz 窗口，在開始建置前將其開通。

權限分為兩層，您需要同時具備：

Layer	What it is	How it is granted
Application scope	您的應用程式被允許發起驗證請求。	由 Fluz 在您的應用程式上啟用。
Customer authorization	個別客戶允許「您的」應用程式代表其提交驗證。	由客戶在 OAuth 流程中授予。小工具應用程式會自動請求。

當您產生用於呼叫的使用者存取權杖時，也必須包含此 scope。完整目錄請參見應用程式 Scopes。

設定 webhook

在發送第一個驗證之前，先註冊一個 webhook 端點。驗證不一定會在 API 回應中即時完成——特別是文件驗證，會在客戶選擇完成的時間點結束，可能是請求連結後的數分鐘或數天。小工具的驗證則完全在您的應用之外完成。Webhook 是您獲知結果的方式。

請勿輪詢驗證狀態，也不要將未收到 webhook 視為拒絕。請註冊端點並對事件做出反應。

端點需求、簽章驗證、重試行為與酬載格式請參見 Webhooks。重點如下：

在開發者平台為您的應用程式註冊 HTTPS 端點。請使用實際的接收 URL——而非其儀表板或檢視頁面。
在 webhook 設定中訂閱 KYC_STATUS_UPDATE 事件。否則無論您使用哪種驗證方法，都不會收到 KYC 狀態更新。
對每次送達，使用原始請求本文驗證 X-HMAC-Signature 標頭。
以 X-Event-ID 去重，並在 30 秒內回應 2xx。

您的應用程式——以及對於 OAuth 與小工具應用，個別客戶的授權——必須持有 VERIFY_KYC 才能接收驗證事件。只有當客戶的 KYC 狀態實際發生「轉換」時，KYC_STATUS_UPDATE 才會觸發。若對已驗證的客戶記錄了一次驗證，會保留其狀態且不會發出事件——此時以 API 回應作為您的確認。酬載會包含先前與新的狀態以及驗證資料；完整格式請參見 KYC status update。

驗證狀態

每種方法會解析為以下其中一種狀態。

Status	Message	Description
`APPROVED`	User verification successful	客戶已通過 KYC 驗證。
`DECLINED`	Verification declined	客戶未通過 KYC 驗證。您可升級至其他方法。
`DUPLICATE`	Duplicate user verification	客戶已驗證，但其 SSN 與既有 Fluz 客戶相符。
`ERROR`	Error encountered with user verification	請求無法處理。參見嘗試次數限制。

DUPLICATE 係以「SSN」判定——而外部供應商結果亦會以「證件號碼」判定——從不以地址判定，因為客戶在不同時間點可能正當地擁有多個地址。Fluz 不會透露相符的另一位客戶。

當客戶已完成驗證、達到驗證嘗試次數上限、或達到文件驗證次數上限時，會回傳 ERROR 狀態。

嘗試次數限制

為防止客戶以嘗試猜測方式取得通過，驗證嘗試次數會被限制。

透過 API，每個使用者 ID 最多可嘗試 SSN 驗證「3 次」。
文件驗證請求的次數限制獨立計算。
「每位客戶」的 KYC 自動填入僅執行一次，無論結果為通過或拒絕。
一旦客戶為 APPROVED，不再接受任何進一步嘗試。
透過外部供應商驗證是例外：您是在回報結果而非請求篩查，故無嘗試次數限制——且若提交對象已為已驗證客戶，會記錄以供稽核，但不會改變其狀態。

地址格式

所有接受地址的方式都期望以結構化欄位提供客戶的「居住」地址，且城市、州別與郵遞區號需一致。格式錯誤或不一致的地址，是原本有效的客戶被判為 DECLINED 的常見原因。

郵政信箱（PO Box）不被視為合法地址，將導致驗證失敗。請提交實際的街道地址。

接受國際地址。完整規則請見地址格式規範。

測試

在上線前，請使用測試環境與已發布的測試身分，演練每條路徑（包含刻意的拒絕案例）。參見測試 KYC 流程。

透過小工具驗證

透過 API 驗證

​透過小工具進行驗證

​透過 API 進行驗證

KYC 自動填入

提供 SSN 資訊

請求 IDV 連結

自帶 KYC

​在各種 API 方法之間做選擇

​必要的 scope

​設定 webhook

​驗證狀態

​嘗試次數限制

​地址格式

​測試

透過小工具進行驗證

透過 API 進行驗證

在各種 API 方法之間做選擇

必要的 scope

設定 webhook

驗證狀態

嘗試次數限制

地址格式

測試