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

# 外部收款人

用於將外部銀行帳戶儲存為收款人，讓你可以從 Fluz 現金餘額向其轉帳。

### 總覽

外部收款人是屬於他人的美國銀行帳戶，例如承包商、供應商或朋友。你只需在帳戶上儲存一次，之後即可使用其 `externalPayeeId`，透過 `createExternalPayout` 向其發送 ACH 付款。

為什麼要先儲存收款人：

* **銀行資訊只需輸入一次。** 完整的路由號碼和帳號僅在建立收款人時傳送，之後使用 `externalPayeeId` 即可。
* **不會回傳敏感資料。** Fluz 會安全地儲存帳號，僅回傳最後四碼。
* **不會重複。** 再次新增相同的路由號碼和帳號時，會回傳既有的收款人。
* **帳戶層級的清單。** 收款人隸屬於 Fluz 帳戶，因此該帳戶的所有授權使用者看到的是同一份清單。

兩個操作用於管理收款人：

* `createExternalPayee` - 將銀行帳戶新增為收款人
* `externalPayees` - 列出帳戶上的收款人

> [!NOTE]
>
> 外部收款人用於向**他人**的銀行帳戶轉帳。若要將資金轉入使用者本人的銀行帳戶，請使用 [提領](https://docs.fluz.app/features/move-funds-with-external-accounts.md)。若要向另一個 Fluz 帳戶轉帳，請使用 [帳戶對帳戶轉帳](https://docs.fluz.app/features/account-to-account-transfers.md)。

***

### createExternalPayee

在已驗證使用者的帳戶上，將外部銀行帳戶新增為收款人。

#### Mutation（CreateExternalPayeeInput）

```graphql theme={null}
createExternalPayee(input: CreateExternalPayeeInput!): ExternalPayee
```

**需要**：`MAKE_PAYOUT_TRANSFER_SEND` 範圍。

#### 輸入

| 欄位 | 類型 | 必填 | 說明 |
| :- | :- | :- | :- |
| routingNumber | String! | 是 | 目標銀行的 9 位數 ABA 路由號碼。必須是有效的 ABA 號碼。 |
| accountNumber | String! | 是 | 目標帳號。僅限數字，4 至 17 位。傳送前請移除空格和連字號。 |
| holderName | String! | 是 | 目標帳戶上的戶名。最多 255 個字元。必須至少包含一個字母或數字。 |
| holderType | ExternalPayeeHolderType! | 是 | `INDIVIDUAL` 或 `BUSINESS`。 |
| emailAddress | String! | 是 | 帳戶持有人的電子郵件地址。Fluz 會用它來檢查該目標帳戶是否屬於某個 Fluz 帳戶。 |
| accountType | DepositAccountType | 否 | `CHECKING` 或 `SAVING`。預設為 `CHECKING`。 |
| nickname | String | 否 | 用來取代戶名顯示的標籤。最多 255 個字元。 |

#### 回應（ExternalPayee）

| 欄位 | 類型 | 說明 |
| :- | :- | :- |
| externalPayeeId | ID! | 收款人 ID。在 `createExternalPayout` 中將其用作 `externalPayeeId`。 |
| holderName | String! | 目標帳戶上的戶名 |
| holderType | ExternalPayeeHolderType! | `INDIVIDUAL` 或 `BUSINESS` |
| nickname | String | 標籤（如果已設定） |
| depositAccountType | DepositAccountType! | `CHECKING` 或 `SAVING` |
| achRoutingNumber | String! | ABA 路由號碼 |
| destinationAccountNumberLastFour | String! | 帳號的最後四碼 |
| emailAddress | String | 帳戶持有人的電子郵件地址 |
| createdAt | DateTime! | 收款人的新增時間 |

#### 範例

```graphql theme={null}
mutation {
  createExternalPayee(
    input: {
      routingNumber: "021000021"
      accountNumber: "123456789"
      holderName: "Jane Doe"
      holderType: INDIVIDUAL
      emailAddress: "jane@example.com"
      accountType: CHECKING
      nickname: "Jane - rent"
    }
  ) {
    externalPayeeId
    holderName
    nickname
    depositAccountType
    achRoutingNumber
    destinationAccountNumberLastFour
    createdAt
  }
}
```

**成功：**

```json theme={null}
{
  "data": {
    "createExternalPayee": {
      "externalPayeeId": "3f1c2b7e-8d4a-4c1e-9f2a-6b5d4e3c2a10",
      "holderName": "Jane Doe",
      "nickname": "Jane - rent",
      "depositAccountType": "CHECKING",
      "achRoutingNumber": "021000021",
      "destinationAccountNumberLastFour": "6789",
      "createdAt": "2026-10-20T15:30:00.000Z"
    }
  }
}
```

**輸入無效：**

```json theme={null}
{
  "errors": [
    {
      "message": "account_number must contain only digits",
      "extensions": { "code": "ARG-0001" }
    }
  ]
}
```

#### 錯誤碼

| 代碼 | 說明 |
| :- | :- |
| ARG-0002 | 缺少必填欄位 |
| ARG-0001 | 輸入無效，例如路由號碼或帳號有誤。當該銀行帳戶屬於使用者自己的 Fluz 帳戶時也會回傳此錯誤。 |
| G-0003 | 此帳戶未啟用向外部銀行帳戶轉帳的功能 |
| G-0001 | 無法新增該銀行帳戶，或發生了伺服器錯誤 |

***

### externalPayees

列出已驗證使用者帳戶上的外部收款人，依新增時間由新到舊排序。

#### 查詢

```graphql theme={null}
externalPayees(paginate: OffsetInput): ExternalPayeeConnection!
```

**需要**：`MAKE_PAYOUT_TRANSFER_SEND` 範圍。

#### 輸入（OffsetInput）

| 欄位 | 類型 | 必填 | 說明 |
| :- | :- | :- | :- |
| limit | Int | 否 | 每頁的收款人數量。預設值和上限均為 20。 |
| offset | Int | 否 | 要略過的收款人數量。預設為 0。 |

#### 回應（ExternalPayeeConnection）

| 欄位 | 類型 | 說明 |
| :- | :- | :- |
| externalPayees | \[ExternalPayee] | 本頁的收款人。欄位與 `createExternalPayee` 的回應相同。 |
| totalCount | Int! | 帳戶上的收款人總數 |
| hasNextPage | Boolean! | 如果本頁之後還有更多收款人，則為 `true` |

#### 範例

```graphql theme={null}
query {
  externalPayees(paginate: { limit: 10, offset: 0 }) {
    externalPayees {
      externalPayeeId
      holderName
      nickname
      destinationAccountNumberLastFour
    }
    totalCount
    hasNextPage
  }
}
```

**成功：**

```json theme={null}
{
  "data": {
    "externalPayees": {
      "externalPayees": [
        {
          "externalPayeeId": "3f1c2b7e-8d4a-4c1e-9f2a-6b5d4e3c2a10",
          "holderName": "Jane Doe",
          "nickname": "Jane - rent",
          "destinationAccountNumberLastFour": "6789"
        }
      ],
      "totalCount": 1,
      "hasNextPage": false
    }
  }
}
```

**沒有收款人：**

```json theme={null}
{
  "data": {
    "externalPayees": {
      "externalPayees": [],
      "totalCount": 0,
      "hasNextPage": false
    }
  }
}
```

#### 錯誤碼

| 代碼 | 說明 |
| :- | :- |
| G-0001 | 伺服器錯誤 |

***

### 重要事項

#### createExternalPayee

* 僅支援可透過 ACH 到達的美國銀行帳戶。帳戶類型必須是 `CHECKING` 或 `SAVING`。
* 再次新增相同的路由號碼和帳號時，會回傳既有的收款人，不會建立重複項目。
* 如果具有相同路由號碼和帳號的收款人先前已被移除，再次新增時會以其原始資料還原。請求中新的姓名、電子郵件或暱稱不會生效。
* 你不能新增屬於已驗證使用者自己的 Fluz 帳戶的銀行帳戶。
* 部分銀行帳戶無法新增。此時請求會失敗，並回傳一般性錯誤。
* 完整帳號永遠不會回傳。請儲存 `externalPayeeId`，而不是銀行資訊。

#### externalPayees

* 回傳整個 Fluz 帳戶的收款人，而不僅是目前使用者新增的收款人。
* 已移除的收款人不會列出。
* 結果依新增時間由新到舊排序。

#### 下一步

使用 [`createExternalPayout`](https://docs.fluz.app/features/external-payouts)，憑 `externalPayeeId` 和來源現金餘額向收款人轉帳。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.