External payees

Used to save an external bank account as a payee, so you can send money to it from a Fluz cash balance.

Overview

An external payee is a US bank account that belongs to someone else, for example a contractor, a vendor, or a friend. You save it once on the account, then send ACH payouts to it with createExternalPayout using its externalPayeeId. Why payees are saved first:

Enter bank details once. The full routing and account number are sent only when you create the payee. After that you use the externalPayeeId.
Sensitive data is not returned. Fluz stores the account number securely and returns only the last four digits.
No duplicates. Adding the same routing and account number again returns the existing payee.
Account-level list. Payees belong to the Fluz account, so every authorized user of that account sees the same list.

Two operations manage payees:

createExternalPayee - Add a bank account as a payee
externalPayees - List the payees on the account

External payees are for sending money to other people’s bank accounts. To move money to the user’s own bank account, use withdrawals. To send money to another Fluz account, use Account to Account Transfers.

createExternalPayee

Add an external bank account as a payee on the authenticated user’s account.

Mutation (CreateExternalPayeeInput)

createExternalPayee(input: CreateExternalPayeeInput!): ExternalPayee

Requires: MAKE_PAYOUT_TRANSFER_SEND scope.

Input

Field	Type	Required	Description
routingNumber	String!	Yes	The 9-digit ABA routing number of the destination bank. Must be a valid ABA number.
accountNumber	String!	Yes	The destination account number. Digits only, 4 to 17 digits. Remove spaces and dashes before sending.
holderName	String!	Yes	The name on the destination account. Maximum 255 characters. Must contain at least one letter or digit.
holderType	ExternalPayeeHolderType!	Yes	`INDIVIDUAL` or `BUSINESS`.
emailAddress	String!	Yes	The account holder’s email address. Fluz uses it to check if the destination belongs to a Fluz account.
accountType	DepositAccountType	No	`CHECKING` or `SAVING`. Defaults to `CHECKING`.
nickname	String	No	A label shown in place of the holder name. Maximum 255 characters.

Response (ExternalPayee)

Field	Type	Description
externalPayeeId	ID!	The payee ID. Use it as `externalPayeeId` in `createExternalPayout`.
holderName	String!	The name on the destination account
holderType	ExternalPayeeHolderType!	`INDIVIDUAL` or `BUSINESS`
nickname	String	The label, if one was set
depositAccountType	DepositAccountType!	`CHECKING` or `SAVING`
achRoutingNumber	String!	The ABA routing number
destinationAccountNumberLastFour	String!	The last four digits of the account number
emailAddress	String	The account holder’s email address
createdAt	DateTime!	When the payee was added

Example

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

Success:

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

Invalid input:

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

Error Codes

Code	Description
ARG-0002	A required field is missing
ARG-0001	Invalid input, for example a bad routing number or account number. Also returned when the bank account belongs to the user’s own Fluz account.
G-0003	Sending money to external bank accounts is not enabled on this account
G-0001	The bank account could not be added, or a server error occurred

externalPayees

List the external payees on the authenticated user’s account, newest first.

Query

externalPayees(paginate: OffsetInput): ExternalPayeeConnection!

Requires: MAKE_PAYOUT_TRANSFER_SEND scope.

Input (OffsetInput)

Field	Type	Required	Description
limit	Int	No	Number of payees per page. Default and maximum is 20.
offset	Int	No	Number of payees to skip. Defaults to 0.

Response (ExternalPayeeConnection)

Field	Type	Description
externalPayees	[ExternalPayee]	The payees on this page. Same fields as the `createExternalPayee` response.
totalCount	Int!	Total number of payees on the account
hasNextPage	Boolean!	`true` if more payees are available after this page

Example

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

Success:

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

No payees:

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

Error Codes

Code	Description
G-0001	Server error

Important Notes

createExternalPayee

Only US bank accounts reachable by ACH are supported. The account type must be CHECKING or SAVING.
Adding the same routing and account number again returns the existing payee. No duplicate is created.
If a payee with the same routing and account number was removed earlier, adding it again restores it with its original details. New name, email, or nickname values in the request are not applied.
You cannot add a bank account that belongs to the authenticated user’s own Fluz account.
Some bank accounts cannot be added. In that case the request fails with a general error.
The full account number is never returned. Store the externalPayeeId, not the bank details.

externalPayees

Returns payees for the whole Fluz account, not only those added by the current user.
Removed payees are not listed.
Results are sorted newest first.

Next step

Send money to a payee with createExternalPayout, using the externalPayeeId and a source cash balance.

​Overview

​createExternalPayee

​Mutation (CreateExternalPayeeInput)

​Input

​Response (ExternalPayee)

​Example

​Error Codes

​externalPayees

​Query

​Input (OffsetInput)

​Response (ExternalPayeeConnection)

​Example

​Error Codes

​Important Notes

​createExternalPayee

​externalPayees

​Next step

Overview

createExternalPayee

Mutation (CreateExternalPayeeInput)

Input

Response (ExternalPayee)

Example

Error Codes

externalPayees

Query

Input (OffsetInput)

Response (ExternalPayeeConnection)

Example

Error Codes

Important Notes

createExternalPayee

externalPayees

Next step