> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fluz.app/llms.txt
> Use this file to discover all available pages before exploring further.

# 以 SSN 驗證

> 提交客戶的法定姓名、地址、出生日期及 SSN 後四碼，以立即取得身分驗證決策。

將 SSN 資訊提供給 Fluz 是兩種 API 方法中較直接的一種。你從客戶蒐集少量身分欄位並提交，Fluz 會在同一個回應中傳回決策。

若你已擁有 — 或可合理向客戶索取 — 客戶的身分詳細資料，請優先使用此 API。若遭到拒絕，請升級為[請求 IDV URL](/verify-customers-by-documents)。

<Info>
  **必要條件**

  * Fluz 於你的應用程式上啟用 `VERIFY_KYC` 範圍。請參閱[必要的 scope](/user-kyc-verification#required-scope)。
  * 為要驗證的客戶產生的[使用者存取權杖](/recipes/generate-user-access-token)，且其 scopes 包含 `VERIFY_KYC`。
  * 已註冊的 webhook 端點。請參閱[Verify Customers](/user-kyc-verification#set-up-a-webhook)。
</Info>

## 運作方式

`verifyUserInformation` mutation 為同步作業。你提交客戶資訊後，Fluz 會對照檔案中的身分資料進行比對，並於回應主體中回傳 `APPROVED`、`DECLINED`、`DUPLICATE` 或 `ERROR`。無需任何客戶介面步驟，客戶也無需完成任何操作。

Fluz 也會將驗證事件發送至你的 webhook 端點，因此你可以用單一處理程序一致地處理所有驗證方法的結果。

## 請求

被驗證的客戶由 `Authorization` 標頭中的使用者存取權杖識別 — 你不需要在輸入中傳遞使用者 ID。

| 欄位            | 類型     | 必填 | 說明                     |
| :------------ | :----- | :- | :--------------------- |
| `firstName`   | String | 是  | 客戶的法定名。                |
| `lastName`    | String | 是  | 客戶的法定姓。                |
| `streetLine1` | String | 是  | 住宅街道地址。                |
| `streetLine2` | String | 否  | 公寓、套房或單位。未使用時傳空字串。     |
| `city`        | String | 是  | 城市。                    |
| `state`       | String | 是  | 州或地區。                  |
| `postalCode`  | String | 是  | 郵遞區號或郵政編碼。             |
| `country`     | String | 是  | 國家。                    |
| `dateOfBirth` | String | 是  | 出生日期，格式為 `MM/DD/YYYY`。 |
| `ssnLast4`    | String | 是  | 客戶 SSN 的後四碼。           |

<Note>
  Fluz 接受完整 SSN 或僅後四碼。建議只提交後四碼 — 能產生相同決策，同時減少你需要蒐集與儲存的資料。
</Note>

<Warning>
  請提交客戶的**住宅**地址，而非帳單或郵寄地址。郵政信箱將被拒絕。地址不相符是誤拒最常見的原因 — 請參閱[地址格式要求](/concepts/address-formatting-requirements)。
</Warning>

## 範例

```javascript theme={null}
import { GraphQLClient, gql } from 'graphql-request';

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

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

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);
```

```json Response theme={null}
{
  "data": {
    "verifyUserInformation": {
      "status": "APPROVED",
      "message": "User verification successful"
    }
  }
}
```

<Card title="開啟教學範例" icon="code" horizontal href="/recipes/verify-user-kyc">
  可直接複製並執行的示例，方便你調整後整合到系統中。
</Card>

## 處理回應

| 狀態          | 後續動作                                                                         |
| :---------- | :--------------------------------------------------------------------------- |
| `APPROVED`  | 客戶已通過驗證。開放相關功能。                                                              |
| `DECLINED`  | 升級為[文件驗證](/verify-customers-by-documents)。不要以相同資訊重新提交。                       |
| `DUPLICATE` | 客戶已通過驗證，但其 **SSN** 與另一位 Fluz 客戶相符。視為已驗證，並在你的系統中檢視是否有重複帳戶。Fluz 不會揭露相符的是哪一位客戶。 |
| `ERROR`     | 檢視 `message`。客戶可能已通過驗證，或已用盡嘗試次數。                                             |

<Note>
  客戶最多可嘗試 SSN 驗證**3 次**。第三次之後，後續請求將回傳 `ERROR`，訊息為 `Exceeded user verification limit`。請改以文件驗證處理，而非重試。
</Note>

## 測試

Staging 測試身分會回傳特定且可重現的結果代碼，讓你能在不使用真實資料的情況下，測試各種拒絕情境——例如地址不符、身故名單、資料稀薄、無效 SSN 等。請參閱[測試 KYC 流程](/test-kyc-flows)。

<Warning>
  請勿修改測試身分的資料。任何未與預期測試值相符的欄位，都會回傳不相符結果，而非你要測試的結果代碼。
</Warning>