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

在已认证用户的账户上，将外部银行账户添加为收款人。

#### 变更（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.