企業 KYB 狀態

Overview

getBusiness 查詢會回傳某個企業帳戶目前的 KYB 狀態，並附上所有權名冊快照，以及各所有人在身分驗證上的進度。在註冊企業之後，這能幫你回答兩個不同的問題：

企業核准了嗎？ 讀取 kybStatus。
卡在哪裡？ 讀取 owners — 仍在 PENDING_CIP 或 PENDING_INVITE 的所有人通常就是原因。

你也可以訂閱 KYB_STATUS_UPDATE webhook 以接收狀態變更，避免排程讀取。該 webhook 只攜帶企業狀態，因此當你需要所有人名冊時，請呼叫此查詢。請參見追蹤申請。

Required scopes

Property	Value
Endpoint	GraphQL API
Authentication	OAuth Bearer Token，帳戶類型為 `BUSINESS`
Required Scopes	`REGISTER_BUSINESS`

此查詢不接受引數 — 它一律解析為與呼叫權杖之 accountId 綁定的企業。請使用 registerBusiness 為該企業帳戶鑄造的權杖；你用來註冊的消費者權杖將無法使用。

當 Fluz 在註冊期間建立企業的 OAuth 授權時，REGISTER_BUSINESS 會被強制包含在該授權的 scopes 中，因此為新企業帳戶鑄造的權杖一律可以呼叫此查詢。

Basic query structure

query GetBusiness {
  getBusiness {
    accountId
    kybStatus
    owners {
      id
      name
      verificationType
      status
    }
  }
}

Response details

Field	Type	Description
`accountId`	`UUID`	此回應所描述的企業帳戶
`kybStatus`	`ExternalKybStatus`	`PENDING`、`APPROVED` 或 `DECLINED`
`owners`	`[BusinessOwnerStatus]`	目前的名冊快照，包含註冊後新增或更新的所有人

BusinessOwnerStatus

Field	Type	Description
`id`	`UUID`	該所有人的身分 ID，對於尚未接受邀請的受邀所有人則為 `null`。請參見可使用哪些 ID
`name`	`String`	源自連結之身分紀錄的顯示名稱
`verificationType`	`BusinessOwnerVerificationType`	此所有人「預期」要進行的身分驗證方式
`status`	`ExternalBusinessOwnerStatus`	該所有人目前的驗證進度

ExternalKybStatus (enum)

Value	What it means	What your app should do
`PENDING`	個案審查中、等待篩檢結果，或等待某位所有人完成驗證	持續追蹤。不要為帳戶入金或發卡
`APPROVED`	KYB 通過	設立消費帳戶並發卡
`DECLINED`	KYB 未通過	呈現中性訊息並引導使用者聯繫客服。不要自動重試

registerBusiness 會回傳 SUBMITTED，但這不是此列舉的值 — 在這裡，同一時點會呈現為 PENDING。

PENDING 將多個內部狀態折疊為一個值。這在一處會有影響：只有在個案處於特定的內部狀態時，requestOwnerDocumentVerificationLink 才能運作，而 kybStatus 無法告訴你目前是哪一個狀態。

BusinessOwnerVerificationType (enum)

Value	When you see it
`SSN`	所有人以 SSN（CIP）驗證 — 其提交時 `isUsPerson: true`
`DOCUMENTS`	所有人上傳身分文件進行驗證 — 其提交時 `isUsPerson: false`
`NOT_REQUIRED`	不預期需要額外驗證：提供的所有人持股低於 25%，且不是控管人

ExternalBusinessOwnerStatus (enum)

Value	What it means	What your app should do
`PENDING_INVITE`	所有人仍有未接受的邀請	無需動作。Fluz 會寄送電子郵件；沒有用於重寄或代為接受的 API
`PENDING_CIP`	所有人仍需完成預期的身分驗證	對於 `DOCUMENTS` 的所有人，傳送驗證連結給他們
`READY`	該所有人的驗證要求已滿足	無需動作
`FAILED`	為前向相容性而存在於 schema，目前不會回傳	—

cURL Example

curl -X POST https://transactional-graph.staging.fluzapp.com/api/v1/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <BUSINESS_ACCESS_TOKEN>" \
  -d '{
    "query": "query GetBusiness { getBusiness { accountId kybStatus owners { id name verificationType status } } }"
  }'

Example Response

{
  "data": {
    "getBusiness": {
      "accountId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "kybStatus": "PENDING",
      "owners": [
        {
          "id": "3f2a1b0c-9d8e-4f7a-8b6c-5d4e3f2a1b0c",
          "name": "John Doe",
          "verificationType": "SSN",
          "status": "READY"
        },
        {
          "id": "d4e5f6a7-b8c9-0123-def0-234567890123",
          "name": "Jane Smith",
          "verificationType": "DOCUMENTS",
          "status": "PENDING_CIP"
        },
        {
          "id": null,
          "name": "Carol Investor",
          "verificationType": "SSN",
          "status": "PENDING_INVITE"
        }
      ]
    }
  }
}

Jane 需要一個驗證連結。Carol 已受邀，Fluz 將會以電子郵件通知她。在兩者都達到 READY 之前，企業無法獲得核准。

Error Codes

此查詢將所有失敗回傳在最上層的 errors 陣列中 — 不會有 success: false 的 payload。

Code	Name	Description	How to resolve
`AUTH-0002`	InvalidCredentials	使用了基本認證；權杖的帳戶類型不是 `BUSINESS`；權杖缺少 `userId` 或 `accountId`；或該 `accountId` 下不存在企業	使用 `registerBusiness` 回傳之企業 `accountId` 所鑄造的權杖
`AUTH-0031`	InvalidScope	權杖缺少 `REGISTER_BUSINESS` scope	新增該 scope 並重新鑄造權杖
`G-0001`	InternalError	內部錯誤	重試一次。若持續發生，請攜帶 `accountId` 聯絡客服

Best practices

偏好使用 webhook，讀取用於對帳。 訂閱 KYB_STATUS_UPDATE 以獲得低延遲，並在使用者返回你的導覽流程頁面時，或以低頻率的背景排程進行讀取 — 每小時一次，而非每次載入頁面。
在上線前同時滿足兩個訊號。 kybStatus: APPROVED，且每位所有人皆為 READY。
不要將連結請求視為進度。 所有人的 status 只有在實際完成驗證後才會改變，而非當你產生其連結時。

KYB 概覽

狀態生命週期，以及如何追蹤個案至決策。

所有人驗證連結

為被回報為 DOCUMENTS 且 PENDING_CIP 的所有人產生連結。

註冊企業

建立此查詢所讀取之帳戶的 mutation。

​Overview

​Required scopes

​Basic query structure

​Response details

​BusinessOwnerStatus

​ExternalKybStatus (enum)

​BusinessOwnerVerificationType (enum)

​ExternalBusinessOwnerStatus (enum)

​cURL Example

​Example Response

​Error Codes

​Best practices

​Related pages

KYB 概覽

所有人驗證連結

註冊企業

Overview

Required scopes

Basic query structure

Response details

BusinessOwnerStatus

ExternalKybStatus (enum)

BusinessOwnerVerificationType (enum)

ExternalBusinessOwnerStatus (enum)

cURL Example

Example Response

Error Codes

Best practices

Related pages