> ## 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.

# 註冊與驗證商家

> 商家註冊與 KYB 驗證的端到端流程：事前準備、呼叫順序，以及如何追蹤申請至審核決定。

## Overview

Fluz KYB（Know Your Business，企業認識）可讓你的平台透過自有 UI 將商家導入 Fluz rails。透過一小組操作，你可以：

1. 解析企業實際經營的商業類別與次類別，
2. 送出法人實體資料 — 法定名稱、組織型態、稅號、註冊州、法定地址、帳戶預期用途 — 以及最終受益所有人名單，
3. 完成需要驗證之所有人的身分驗證，並
4. 追蹤最終的 **KYB 案件**至核准或婉拒。

提交本身是一個單一的 mutation，[registerBusiness](/business-registration)。它會立即回傳 `accountId`，且 `kybStatus` 為 `SUBMITTED`。

<Note>
  **註冊是驗證，不是核准。** `success` 回應僅代表傳入資料通過驗證且已開立 KYB 案件。這**不**代表商家已獲核准。請將整合設計為在狀態為核准前，不嘗試為帳戶加值或發卡。
</Note>

### 商家帳戶能解鎖什麼

一旦 KYB 核准，商家帳戶即可用於平台的商務功能：

* 商家消費帳戶與餘額
* 商用虛擬卡，包含大量發卡
* 授權使用者與卡片層級的消費控管
* 卡片、轉帳與報銷的審批流程
* 商家層級的交易報表與費用註記

### 何時使用這些端點

當你希望在自有 UI 蒐集法人與持有人資料，而非將使用者導向 Fluz 代管體驗時，請使用此流程。若你希望由 Fluz 代管資料蒐集與文件上傳，請與你的客戶經理聯繫以採用基於小工具的導入選項。

***

## KYB flow

### Step-by-step

<Steps>
  <Step title="Step 0 — 滿足先決條件">
    這些不屬於流程的一部分，但在呼叫 `registerBusiness` 前都必須成立。每列皆鏈接到下方細節。見[先決條件](#prerequisites)
  </Step>

  <Step title="解析商業類別與次類別">
    呼叫 [getBusinessCategories](/business-categories)，讓使用者選擇一個類別與該類別的一個次類別。
  </Step>

  <Step title="上傳授權簽署人文件（若適用）">
    僅在申請人持股少於 25% 且不是控制人時需要。先上傳文件，接著將回傳的 URL 傳入 `authorizedSignerDocumentUrl`。見[提交商家文件](/submit-business-documents)。
  </Step>

  <Step title="提交 registerBusiness mutation">
    以單次呼叫送出完整法人資料、持有人聲明，以及所有持有人。驗證錯誤會出現在回應 payload 中 — 見[回應細節](/business-registration#response-details)。
  </Step>

  <Step title="讓其餘持有人完成驗證">
    讀取 [getBusiness](/business-status) 以查看每位持有人所需的驗證類型與當前進度。對於走文件驗證路徑的持有人，以 [requestOwnerDocumentVerificationLink](/owner-verification-link) 產生連結並傳送給他們。被邀請的持有人會由 Fluz 寄送 email，並自行完成驗證。
  </Step>

  <Step title="等待 KYB 決定，然後佈建">
    申請最初為審核中。請向使用者呈現此狀態，而非暗示已就緒。狀態變為 `APPROVED` 後，再建立消費帳戶並發卡。
  </Step>
</Steps>

### 端到端序列

```mermaid theme={null}
sequenceDiagram
    autonumber
    participant App as Your Application
    participant API as Fluz GraphQL API
    participant Files as Fluz File Upload (REST)
    participant KYB as Fluz Compliance / KYB
    participant Owner as Business Owner

    Note over App,API: Step 0 — the applicant is already a verified Fluz user
    App->>API: query getBusinessCategories
    API-->>App: businessCategoryId + businessSubCategoryId values

    opt Applicant is an authorized signer
        App->>Files: Upload authorization document
        Files-->>App: document URL
    end

    Note over App,API: Step 1 — submit the business
    App->>API: mutation registerBusiness(input)
    alt Validation fails
        API-->>App: success false, with error code and message
        App->>App: Correct the field and resubmit
    else Validation passes
        API-->>App: accountId plus kybStatus SUBMITTED
        API->>KYB: Open KYB case
    end

    Note over App,Owner: Step 2 — owners verify identity
    opt Owner must verify by document
        App->>API: requestOwnerDocumentVerificationLink
        API-->>App: verificationLink
        App->>Owner: Forward the link
        Owner->>KYB: Completes verification
    end

    Note over KYB,App: Step 3 — asynchronous review
    KYB->>KYB: Entity, tax ID, address, and owner checks
    KYB-->>API: Decision (or request for more documentation)
    App->>API: KYB_STATUS_UPDATE webhook, or query getBusiness
    API-->>App: Updated KYB status and owner roster

    Note over App,API: Step 4 — go live
    App->>API: Create spend accounts and issue cards
```

***

## Prerequisites

| Prerequisite                                                         | If missing  |
| -------------------------------------------------------------------- | ----------- |
| 你的應用程式請求了 [`REGISTER_BUSINESS` 權限範圍](#application-permission-scopes) | `AUTH-0031` |
| 申請人已[授權你的應用程式](#applicant-authorization)取得其請求的商家權限範圍                 | `AUTH-0008` |
| 申請人[已完成 CIP 驗證](#the-applicant-must-already-be-identity-verified)    | `ARG-0001`  |
| 申請人[沒有進行中的 KYB 申請](#one-open-application-per-user)                   | `BS-0007`   |
| 你持有[每個操作所需帳戶型態的 Bearer 權杖](#access-tokens)                           | `AUTH-0002` |
| 若申請人為授權簽署人，已上傳授權簽署人文件                                                | `ARG-0001`  |
| 商家的法定地址為真實且可驗證的地址                                                    | `BS-0002`   |

### Application permission scopes

在 Fluz dashboard 的應用程式權限範圍中選擇 **`REGISTER_BUSINESS`**。所有 KYB 操作皆需要此範圍，而權杖僅能攜帶你的應用程式被設定可請求的範圍。見 [Application Scopes](/fluz-dashboard/application-scopes)。

訂閱 [`KYB_STATUS_UPDATE` webhook](#tracking-an-application) 亦需要相同的範圍。

### Applicant authorization

申請人必須完成你應用程式的 OAuth 授權，且該授權必須涵蓋你應用程式所請求的每個商家範圍。若之後新增範圍，既有使用者必須重新授權才能註冊商家 — 否則註冊會以 `AUTH-0008` 失敗。

### The applicant must already be cip-verified

Bearer 權杖標識的是**申請人**：提交申請的使用者。名冊中必須有且僅有一位持有人與權杖使用者以**email**（不分大小寫）或**電話號碼**相符，且該持有人不可標記為 `isInvited: true`。

KYB 會驗證商家與「其他」持有人，不會驗證申請人，因此申請人必須事先達到已驗證狀態。你為其送出的 `isUsPerson` 值決定套用哪種檢查：

| Applicant `isUsPerson` | 註冊前必須達到的狀態            |
| ---------------------- | --------------------- |
| `true`                 | 該使用者已留存成功的 SSN（CIP）驗證 |
| `false`                | 成功的文件驗證               |

身分驗證發生在 KYB 之外，需具備 `VERIFY_KYC` 範圍，使用 `verifyUserInformation`、`verifyUserPrefillInformation`，或 `requestDocumentVerificationLink`。見[身分驗證（KYC）](/docs/user-kyc-verification)。若該人尚無任何 Fluz 帳戶，請先以 [registerUser](/user-registration) 建立。

### One open application per user

在既有申請仍開啟時，使用者不得啟動新的註冊 — 否則回傳 `BS-0007`。

<Warning>
  沒有冪等性鍵，也沒有可取消進行中申請的 API。被拒絕的申請不會留下任何紀錄，可重新提交；但**成功**的申請會在結案前阻擋該使用者再次註冊。請在提交前先行驗證，若案件似乎停滯，請以 `accountId` 聯絡你的客戶經理。
</Warning>

### Access tokens

每個操作都需要特定帳戶型態的 Bearer 權杖：

| Operation                                                        | Token account type | Required scope      |
| ---------------------------------------------------------------- | ------------------ | ------------------- |
| [getBusinessCategories](/business-categories)                    | `CONSUMER`         | `REGISTER_BUSINESS` |
| [registerBusiness](/business-registration)                       | `CONSUMER`         | `REGISTER_BUSINESS` |
| [getBusiness](/business-status)                                  | `BUSINESS`         | `REGISTER_BUSINESS` |
| [requestOwnerDocumentVerificationLink](/owner-verification-link) | `BUSINESS`         | `REGISTER_BUSINESS` |

<Note>
  使用 `generateUserAccessToken` 產生 Mint Bearer 權杖 — 請參閱 API 參考的 Authentication 章節。
</Note>

***

## KYB status lifecycle

```mermaid theme={null}
stateDiagram-v2
    [*] --> SUBMITTED: registerBusiness returns accountId
    SUBMITTED --> PENDING: Case under review
    PENDING --> PENDING: Owners still verifying, or more documentation requested
    PENDING --> APPROVED: Entity and ownership checks cleared
    PENDING --> DECLINED: Checks not cleared
    APPROVED --> [*]: Business can transact
    DECLINED --> [*]: New submission required
```

| Status      | 意義                                           | 你的應用應該做什麼                  |
| ----------- | -------------------------------------------- | -------------------------- |
| `SUBMITTED` | 僅由 `registerBusiness` 回傳。提交已被接受，且已開立 KYB 案件。 | 儲存 `accountId`。顯示「審核中」狀態。  |
| `PENDING`   | 由 `getBusiness` 回報。案件審核中、等待篩檢結果，或等待某位持有人驗證。  | 持續追蹤。不要嘗試為帳戶加值或發卡。         |
| `APPROVED`  | KYB 通過。商家帳戶可用。                               | 佈建消費帳戶、發卡、解鎖你的商家 UI。       |
| `DECLINED`  | KYB 未通過。                                     | 呈現中性訊息並引導使用者聯繫支援。不要自動重試提交。 |

<Note>
  `SUBMITTED` 僅會由 `registerBusiness` 回傳。[getBusiness](/business-status) 回報三值狀態，而註冊後緊接的狀態在那裡會顯示為 `PENDING` — 兩者描述的是同一時點但用詞不同。
</Note>

***

## Tracking an application

有兩種方式追蹤申請至最終狀態。選擇最符合你基礎架構者；許多整合同時使用 webhook 以降低延遲，並偶爾讀取以對帳。

<Tabs>
  <Tab title="Webhook">
    在 Fluz dashboard 訂閱 **`KYB_STATUS_UPDATE`** 事件：註冊你的回呼 URL 並選取該事件。你的應用需要 `REGISTER_BUSINESS` 範圍才能訂閱。

    當商家 KYB 狀態變更時，Fluz 會對你的端點發出 `POST`。

    ```json theme={null}
    {
      "accountId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "previousStatus": "PENDING",
      "newStatus": "APPROVED",
      "externalReferenceId": "your-partner-user-id-123"
    }
    ```

    | 欄位                    | 類型       | 說明                                                  |
    | --------------------- | -------- | --------------------------------------------------- |
    | `accountId`           | `UUID`   | 狀態變更的商家帳戶 — 即 `registerBusiness` 回傳的同一個 `accountId` |
    | `previousStatus`      | `String` | 變更前狀態：`PENDING`、`APPROVED` 或 `DECLINED`             |
    | `newStatus`           | `String` | 變更後狀態：`PENDING`、`APPROVED` 或 `DECLINED`             |
    | `externalReferenceId` | `String` | 若於註冊時提供，則為你的自有參考；否則省略                               |

    需處理兩件事：

    * **將傳遞視為至少一次。** 讓你的處理器具備冪等性，以 `accountId` 加上 `newStatus` 作為鍵。
    * **你可能收到 `previousStatus` 等於 `newStatus` 的事件。** 案件在內部狀態間移動，但外顯狀態相同。將這些視為 no-op。

    <Note>
      載荷僅攜帶商家狀態 — 不包含持有人名冊。當你需要查看個別持有人進度時，請呼叫 [getBusiness](/business-status)。
    </Note>
  </Tab>

  <Tab title="直接讀取狀態">
    使用商家帳戶權杖呼叫 [getBusiness](/business-status)。它會回傳相同的 `kybStatus` 與當前持有人名冊，這是唯一能看見個別持有人是否仍需驗證的方式。

    ```graphql theme={null}
    query GetBusiness {
      getBusiness {
        accountId
        kybStatus
        owners {
          id
          name
          verificationType
          status
        }
      }
    }
    ```

    當使用者返回你的商家導入畫面時讀取一次，並以低頻背景排程讀取 — 每小時一次，而非每次載入頁面。持續進行，直到 `kybStatus` 為最終狀態，且每位持有人皆回報為 `READY`。
  </Tab>
</Tabs>

<Info>
  一般審查會在一至兩個工作天內完成，但若需補件或某位持有人尚未完成身分驗證，時間可能更長。若案件似乎停滯，請以 `accountId` 聯絡你的客戶經理，而非重新提交 — 第二次提交會被 `BS-0007` 擋下。
</Info>

***

## Identifying businesses with `externalReferenceId`

Fluz 以在註冊時產生的 UUID `accountId` 識別商家。`externalReferenceId` 則是你可選擇提供的識別碼，讓你能用自家系統已使用的 ID 與 Fluz 互動。

於 [registerBusiness](/business-registration) 一次性傳入：

```json theme={null}
{ "externalReferenceId": "your-partner-user-id-123" }
```

它會儲存在商家帳戶上，帶來三項好處：

* **免存 Fluz ID 的權杖簽發。** 以外部參考來簽發商家帳戶存取權杖，而非用 `userId` 與 `accountId`。
* **Webhook 對應。** 每個 [`KYB_STATUS_UPDATE`](#tracking-an-application) 事件都會附帶此參考值，讓你不需查表即可將事件對應到自家紀錄。

它是可選的。若你省略它，一切仍可運作 — 你只需要自行儲存 `accountId`，無論如何都建議這麼做。

### 規則

| 情境               | 結果                           |
| ---------------- | ---------------------------- |
| 省略               | 建立商家帳戶時不含外部參考                |
| 提供，且未被使用         | 該參考會儲存於新商家帳戶                 |
| 提供，但已在申請人的消費者帳戶上 | 該參考會自消費者帳戶移至新商家帳戶，之後會解析至該商家  |
| 提供，但已在另一個商家上     | 註冊以 `AUTH-0008` 失敗。既有商家保留該參考 |

<Warning>
  **每個商家使用一個唯一值。** 參考只能指向一個商家帳戶，將同一值重用於兩個商家會使第二次註冊失敗。請以你的主鍵衍生，而非可重用的資訊（如 email）。
</Warning>

<Note>
  這裡涉及兩個不同的參考值，容易混淆。**你的存取權杖已攜帶的參考值**用於定位申請人既有的授權；而 **`registerBusiness` 輸入中的參考值** 會寫入新的商家帳戶。兩者用途不同。
</Note>

***

## Related pages

<CardGroup cols={2}>
  <Card title="註冊商家" icon="building" href="/business-registration">
    `registerBusiness` mutation：完整參數參考、持有人規則與錯誤代碼。
  </Card>

  <Card title="商業類別" icon="list" href="/business-categories">
    取得 mutation 所需的類別與次類別 ID。
  </Card>

  <Card title="提交商家文件" icon="file-arrow-up" href="/submit-business-documents">
    上傳授權文件並回應 KYB 補件要求。
  </Card>

  <Card title="商家 KYB 狀態" icon="arrows-rotate" href="/business-status">
    讀取 KYB 狀態與持有人逐一驗證進度。
  </Card>

  <Card title="持有人驗證連結" icon="id-card" href="/owner-verification-link">
    為持有人產生可分享的身分驗證連結。
  </Card>

  <Card title="註冊客戶" icon="user-plus" href="/user-registration">
    建立將作為申請人的 Fluz 使用者。
  </Card>
</CardGroup>