外部收款人 - Fluz

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

總覽

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

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

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

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

外部收款人用於向他人的銀行帳戶轉帳。若要將資金轉入使用者本人的銀行帳戶，請使用提領。若要向另一個 Fluz 帳戶轉帳，請使用帳戶對帳戶轉帳。

createExternalPayee

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

Mutation（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

​Mutation（CreateExternalPayeeInput）

​輸入

​回應（ExternalPayee）

​範例

​錯誤碼

​externalPayees

​查詢

​輸入（OffsetInput）

​回應（ExternalPayeeConnection）

​範例

​錯誤碼

​重要事項

​createExternalPayee

​externalPayees

​下一步

總覽

createExternalPayee

Mutation（CreateExternalPayeeInput）

輸入

回應（ExternalPayee）

範例

錯誤碼

externalPayees

查詢

輸入（OffsetInput）

回應（ExternalPayeeConnection）

範例

錯誤碼

重要事項

createExternalPayee

externalPayees

下一步