Virtual Account Numbers

A virtual account number (VAN) is a real, bank-issued routing number and account number that points at one of a user’s spend accounts. Anyone outside Fluz — an employer, a bank, a customer, a marketplace — can send money to that routing and account pair, and the funds land in the spend account as a deposit. The VAN does not hold money. The spend account holds the balance. A VAN is simply another address that routes into it.

One balance, many addresses.A spend account can have more than one active virtual account number, and exactly one of them is marked primary. Every VAN on the account credits the same balance — they exist so you can separate senders, such as payroll versus a specific customer, without splitting the funds.

How It Fits Together

Money in arrives through a VAN. Money out still leaves the spend account the same way it always has — gift card and virtual card funding, internal transfers, and withdrawals to a linked external account.

Supported Rails

Credits sent to a virtual account number are accepted over four rails:

Rail	Direction	Typical availability	Notes
RTP	Credit (in)	Near-instant, 24/7	Sender’s bank must participate in The Clearing House RTP.
FedNow	Credit (in)	Near-instant, 24/7	Sender’s bank must be a FedNow participant.
Wire	Credit (in)	Same business day	Domestic wires. Sending bank fees are set by the sender.
ACH	Credit (in)	1–2 business days	Standard ACH credit, including payroll direct deposit.

ACH debit (pull) is not supported yet.A virtual account number can currently only receive funds. You cannot use the VAN’s routing and account number to originate an ACH debit — a third party cannot pull money out of a spend account using these credentials. Support for ACH debit is coming soon.To move money out today, use Withdraw Funds to an External Account or an internal transfer.

What a Credit Looks Like

When funds arrive at a virtual account number, Fluz records a standard deposit against the destination spend account. The deposit’s funding source is the virtual account — not a bank card, bank account, or PayPal — because the money originated outside Fluz and was pushed in rather than pulled from a linked payment method. This means:

The credit appears in the same transaction and deposit history as any other deposit.
There is no linked funding source object to reconcile against, and no backup card hold, because nothing was debited from the user.
The deposit is attributable to the specific VAN that received it, so you can distinguish a payroll credit from a customer payment when a spend account has multiple VANs.

Retrieve a User’s Virtual Account Numbers

Use getSpendAccountVirtualAccountNumbers to list the active VANs on a spend account. It returns every active VAN, one of which is flagged as primary. Scope required: LIST_PAYMENT

query getSpendAccountVirtualAccountNumbers($userCashBalanceId: UUID!) {
  getSpendAccountVirtualAccountNumbers(userCashBalanceId: $userCashBalanceId) {
    virtualAccountNumberId
    routingNumber
    accountNumber
    accountType
    bankName
    isPrimary
    status
    createdAt
  }
}

Variables

{
  "userCashBalanceId": "9c1f6b2e-4d7a-4c3b-9f11-2a5e8b0d6c74"
}

Argument	Type	Required	Description
`userCashBalanceId`	`UUID!`	Yes	The spend account whose virtual account numbers you want.

Returns [SpendAccountVirtualAccountNumber!]!. See the type reference for the full field list.

Displaying account numbers.A VAN’s full account number is sensitive. Mask it in list views and reveal the full value only on an explicit user action, the same way you would treat a card PAN. When a user needs to hand the details to a third party, prefer the generated PDF artifacts described in Virtual Account Documents over free-form copy.

Handing the Details to a Third Party

Rather than asking a user to transcribe a routing and account number into a payroll portal or send it to a counterparty by email, Fluz generates PDF artifacts on demand:

Document	Query	Use case
Payment instructions	`getSpendAccountPaymentInstructions`	Give a customer or partner the details needed to send a wire or ACH credit.
Paycheck deposit form	`getSpendAccountPaycheckDepositForm`	Pre-filled direct deposit form for an employer’s payroll department.
Account status letter	`getSpendAccountStatusLetter`	Proof of account, optionally showing the current balance.

All three default to the spend account’s primary VAN when virtualAccountNumberId is omitted, and all three require the LIST_PAYMENT scope. See Virtual Account Documents for the full reference.

Requirements

The user must have at least one active spend account.
Reading virtual account numbers and generating documents both require the LIST_PAYMENT scope on the user access token.
Virtual account numbers are provisioned by Fluz. They are not created through the API.

Spend Accounts

The account that actually holds the balance.

Virtual Account Documents

Payment instructions, deposit forms, and status letters.

Deposit Funds

Pull funds in from a linked bank account or card.

Funding Sources

How Fluz classifies the money moving in.

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

​How It Fits Together

​Supported Rails

​What a Credit Looks Like

​Retrieve a User’s Virtual Account Numbers

​Handing the Details to a Third Party

​Requirements

​Related

Spend Accounts

Virtual Account Documents

Deposit Funds

Funding Sources

How It Fits Together

Supported Rails

What a Credit Looks Like

Retrieve a User’s Virtual Account Numbers

Handing the Details to a Third Party

Requirements

Related