Account to Account Transfers

Account to account transfers move funds between two Fluz accounts using the createTransfer mutation. Unlike an internal transfer — which moves money between two of your own spend accounts — an account to account transfer sends money to a different Fluz account: one of your users, your application, or between two of your users.

Every transfer is a two-step flow: first identify the recipient, then create the transfer.

Step	Page	Purpose
Find the recipient	Wallet Transfer Recipient Lookup	Resolve a phone, email, or company name into the recipient's account ID.
Send the funds	Create Wallet Transfer to Another Fluz Account	Move the funds to the recipient with `createTransfer`.

📘
Not the same as an internal transfer.
To move money between your own spend accounts, use Transfer Funds Internally instead. Account to account transfers are for moving funds to a separate Fluz account.

The Three Transfer Directions

The same createTransfer mutation supports three directions. Which one you're performing is determined by your authentication method and whether you provide a destination.

Direction	Auth method	Sender	Typical use
User → Application	Bearer token	The user	Collecting a payment from a user (no `destination` needed — defaults to your app).
Application → User	Basic Auth	Your application	Disbursing funds to a user (`destination` required).
User → User	Bearer token	The user	Moving funds between two of your users (`destination` set to the recipient).

🚧
Account to account transfers require a public application.
Basic Auth (application-as-sender) transfers require your application to be in ACTIVE status. Personal applications cannot send via Basic Auth. The recipient must also be a registered user of your application.

Step 1 — Look Up the RecipientBefore sending, resolve the recipient into an `accountId` using the lookup queries (both require the `QUERY_RECIPIENT` scope):

lookupUser — find an individual by phone number (E.164 format) or email.
lookupBusiness — find a business by company name (case-insensitive exact match; searches both the registered name and DBA).

If you already store the recipient's Fluz accountId — or assigned them an externalReferenceId when you created them — you can skip the lookup and pass that identifier directly in Step 2.

See Wallet Transfer Recipient Lookup for inputs, responses, and error codes.

Step 2 — Create the Transfernd the funds with the `createTransfer` mutation. At a minimum you provide an `idempotencyKey` and an `amount`; the `destination` and funding source depend on the direction.

Identify the recipient by accountId or by the externalReferenceId you assigned — provide one, not both. Optionally target a specific userCashBalanceId on the recipient's account.
Fund the transfer from the sender's cash balance by default, or (Bearer token only) from a linked bankCardId, bankAccountId, or paypalVaultId. Only one funding source per request.
Annotate the transfer with an optional memo, transactionCategory, or attachmentId.

Bearer-token (user-sent) transfers require the MAKE_PAYOUT_TRANSFER_SEND scope.

See Create Wallet Transfer to Another Fluz Account for the full input reference, examples for each direction, and error handling.

Idempotencyy transfer must include a unique, client-generated `idempotencyKey`. If the same key is submitted more than once, the API returns the result of the original request instead of creating a duplicate transfer. Keys are valid for 10 minutes.

Requirements at a Glance

ration	Auth	Scope
Look up a recipient	Bearer token	`QUERY_RECIPIENT`
Create a transfer (user-sent)	Bearer token	`MAKE_PAYOUT_TRANSFER_SEND`
Create a transfer (application-sent)	Basic Auth (Api Key)	Public / `ACTIVE` application

Want to learn more? Speak with our experts for more info or to request a demo.

Not the same as an internal transfer.

The Three Transfer Directions