概覽 - Fluz

Fluz 要求客戶在進行特定交易前通過身分驗證（KYC），而驗證也會解鎖更高的交易限額。在客戶完成驗證之前，平台的部分功能——為錢包加值、提領資金，以及發行虛擬卡——將無法使用。有兩種方式讓客戶完成驗證。選擇取決於您是否希望由 Fluz 掌控驗證體驗，或由您自行掌控。

透過小工具驗證

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

透過 API 驗證

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

透過小工具驗證

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

透過 API 驗證

如果您直接整合 API，則由您自行提交驗證。目前提供三種方法，差異在於您向客戶收集哪些資料。

KYC 自動填入

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

提供 SSN 資訊給我們

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

請求 IDV 連結

您使用 requestDocumentVerificationLink 請求驗證連結。Fluz 會回傳一個代管的 URL；您的客戶會直接上傳其政府核發的身分證件與自拍至 Fluz。

在 API 方法之間做選擇

大多數整合會在低摩擦的嘗試失敗時，才逐步升級：

先嘗試 KYC 自動填入

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

退而求其次使用 SSN 驗證

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

再退一步使用 IDV 連結

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

客戶只需通過一次，且所有方法共用單一驗證狀態。一旦客戶達到 APPROVED——不論使用哪種方法，包括透過小工具——後續嘗試都會以 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。完整目錄請參閱Application Scopes。

設定 webhook

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

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

端點需求、簽章驗證、重送行為與負載格式請參閱 Webhooks。簡而言之：

在 Developer Portal 為您的應用註冊一個 HTTPS 端點。
訂閱身分驗證事件。
在每次遞送時，針對原始請求本文驗證 X-HMAC-Signature 標頭。
以 X-Event-ID 進行去重，並在 30 秒內回應 2xx。

您的應用程式——以及對於 OAuth 與小工具應用，個別客戶的授權——必須持有 VERIFY_KYC 才能接收驗證事件。

驗證狀態

每種方法最終會得到下列其中一種狀態。

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）不被接受為合法地址，將導致驗證失敗。請提交實體街道地址。

可接受國際地址。完整規則請參閱地址格式要求。

測試

在上線前，請使用 Staging 環境與已公布的測試身分來演練各種路徑，包括刻意的拒絕情境。請參閱測試 KYC 流程。

透過小工具驗證

透過 API 驗證

​透過小工具驗證

​透過 API 驗證

KYC 自動填入

提供 SSN 資訊給我們

請求 IDV 連結

​在 API 方法之間做選擇

​必要 scope

​設定 webhook

​驗證狀態

​嘗試次數限制

​地址格式

​測試

透過小工具驗證

透過 API 驗證

在 API 方法之間做選擇

必要 scope

設定 webhook

驗證狀態

嘗試次數限制

地址格式

測試