外部收款人 - Fluz

用于将外部银行账户保存为收款人，以便你从 Fluz 现金余额向其转账。

概览

外部收款人是属于他人的美国银行账户，例如承包商、供应商或朋友。你只需在账户上保存一次，之后即可使用其 externalPayeeId 通过 createExternalPayout 向其发送 ACH 付款。为什么要先保存收款人：

银行信息只需输入一次。 完整的路由号码和账号仅在创建收款人时发送，之后使用 externalPayeeId 即可。
不返回敏感数据。 Fluz 会安全存储账号，仅返回最后四位数字。
不会重复。 再次添加相同的路由号码和账号时，会返回已有的收款人。
账户级列表。 收款人归属于 Fluz 账户，因此该账户的所有授权用户看到的是同一份列表。

两个操作用于管理收款人：

createExternalPayee - 将银行账户添加为收款人
externalPayees - 列出账户上的收款人

外部收款人用于向他人的银行账户转账。若要将资金转入用户本人的银行账户，请使用提现。若要向另一个 Fluz 账户转账，请使用账户到账户转账。

createExternalPayee

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

变更（CreateExternalPayeeInput）

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!	收款人的添加时间

示例

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

成功：

{
  "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"
    }
  }
}

输入无效：

{
  "errors": [
    {
      "message": "account_number must contain only digits",
      "extensions": { "code": "ARG-0001" }
    }
  ]
}

错误码

代码	说明
ARG-0002	缺少必填字段
ARG-0001	输入无效，例如路由号码或账号有误。当该银行账户属于用户自己的 Fluz 账户时也会返回此错误。
G-0003	此账户未启用向外部银行账户转账的功能
G-0001	无法添加该银行账户，或发生了服务器错误

externalPayees

列出已认证用户账户上的外部收款人，按最新添加的在前排序。

查询

externalPayees(paginate: OffsetInput): ExternalPayeeConnection!

需要：MAKE_PAYOUT_TRANSFER_SEND 范围。

输入（OffsetInput）

字段	类型	必填	说明
limit	Int	否	每页的收款人数量。默认值和最大值均为 20。
offset	Int	否	要跳过的收款人数量。默认为 0。

响应（ExternalPayeeConnection）

字段	类型	说明
externalPayees	[ExternalPayee]	本页的收款人。字段与 `createExternalPayee` 的响应相同。
totalCount	Int!	账户上的收款人总数
hasNextPage	Boolean!	如果本页之后还有更多收款人，则为 `true`

示例

query {
  externalPayees(paginate: { limit: 10, offset: 0 }) {
    externalPayees {
      externalPayeeId
      holderName
      nickname
      destinationAccountNumberLastFour
    }
    totalCount
    hasNextPage
  }
}

成功：

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

没有收款人：

{
  "data": {
    "externalPayees": {
      "externalPayees": [],
      "totalCount": 0,
      "hasNextPage": false
    }
  }
}

错误码

代码	说明
G-0001	服务器错误

重要说明

createExternalPayee

仅支持可通过 ACH 到达的美国银行账户。账户类型必须是 CHECKING 或 SAVING。
再次添加相同的路由号码和账号时，会返回已有的收款人，不会创建重复项。
如果具有相同路由号码和账号的收款人之前已被移除，再次添加时会以其原始信息恢复。请求中新的姓名、邮箱或昵称不会生效。
你不能添加属于已认证用户自己的 Fluz 账户的银行账户。
部分银行账户无法添加。此时请求会失败，并返回一般性错误。
完整账号永远不会返回。请保存 externalPayeeId，而不是银行信息。

externalPayees

返回整个 Fluz 账户的收款人，而不仅仅是当前用户添加的收款人。
已移除的收款人不会列出。
结果按最新添加的在前排序。

下一步

使用 createExternalPayout，凭 externalPayeeId 和来源现金余额向收款人转账。

​概览

​createExternalPayee

​变更（CreateExternalPayeeInput）

​输入

​响应（ExternalPayee）

​示例

​错误码

​externalPayees

​查询

​输入（OffsetInput）

​响应（ExternalPayeeConnection）

​示例

​错误码

​重要说明

​createExternalPayee

​externalPayees

​下一步

概览

createExternalPayee

变更（CreateExternalPayeeInput）

输入

响应（ExternalPayee）

示例

错误码

externalPayees

查询

输入（OffsetInput）

响应（ExternalPayeeConnection）

示例

错误码

重要说明

createExternalPayee

externalPayees

下一步