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 — eventually.A spend account credits a single balance no matter which address the money arrives at. The VAN data model is built to support more than one active virtual account number per spend account, with exactly one marked primary, so that senders could eventually be separated — payroll versus a specific customer — without splitting the funds.Today, every spend account is provisioned with exactly one VAN, and it is always the primary. There is no API, dashboard, or account-manager path to a second one yet. See Multiple Virtual Account Numbers.

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.

Provisioning

Virtual account numbers are provisioned by Fluz. There is no mutation to create one, and no control in the dashboard to request one. Provisioning happens on Fluz’s side once a spend account becomes eligible; your integration’s job is to read the result, not to trigger it.

Eligibility

A spend account is eligible for a virtual account number when all of the following are true:

Condition	Detail
Program entitlement	VANs are enabled on your program at the sponsor bank. This is a per-program setting agreed during onboarding, not a per-user one. If VANs are not enabled on your program, no spend account under it will receive one. Today VANs are only available for Spend Accounts sponsored by Austin Capital Bank (ACB).
Spend account status	The spend account exists and is active.
Identity verification	The underlying accountholder has cleared CIP — KYC for a consumer, KYB plus beneficial owner verification for a business. A spend account that exists but is pending or under manual review will not carry a VAN.
Accountholder standing	The accountholder is not frozen, restricted, or closed.

Spend account creation is not the trigger.An eligible spend account and a provisioned VAN are two different states. A newly created spend account is usable for gift cards, virtual cards, and internal transfers immediately, but it may not have a VAN yet. Surfacing deposit instructions off the back of spend account creation will show your users an empty screen.

Trigger and timing

Provisioning is automatic and asynchronous. Fluz initiates it once the conditions above are met; the VAN is issued by the sponsor bank and written back to the spend account when the bank returns it. The VAN is not available in the same request that creates the spend account. Treat availability as eventual, and read the VAN at the point the user needs it rather than at account creation. Until the VAN is written back, getSpendAccountVirtualAccountNumbers returns an empty array. It does not error, and it does not return null.

Pending — VAN not yet provisioned

{
  "data": {
    "getSpendAccountVirtualAccountNumbers": []
  }
}

An empty array is ambiguous on its own: it means either not yet provisioned or program not entitled. Resolve it against the spend account’s own status rather than retrying indefinitely.

Recommended integration pattern

Create the spend account

Proceed with your normal flow. Do not block the user on VAN availability.

Read the VAN lazily

Call getSpendAccountVirtualAccountNumbers when the user navigates to a deposit, direct deposit, or account details screen — not eagerly at account creation.

Handle the empty case explicitly

Render a “deposit details are being set up” state rather than an error or a blank field. Re-check on next view.

Cache by ID, not by position

Store virtualAccountNumberId as the stable key. Never key off array index.

API and dashboard behave the same way

Both surfaces read the same underlying object, and neither can create, modify, or remove one.

Operation	API	Dashboard
Create a VAN	Not available	Not available
Read VANs	`getSpendAccountVirtualAccountNumbers`	Spend account detail view
Rename, set primary, deactivate	Not available	Not available
Generate deposit artifacts	`getSpendAccountPaymentInstructions`, `getSpendAccountPaycheckDepositForm`, `getSpendAccountStatusLetter`	—

If the API returns an empty array for a spend account, the dashboard will show no deposit details for that same account. There is no dashboard-only path to a VAN.

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
    achRoutingNumber
    accountNumber
    last4
    nickname
    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.

Multiple Virtual Account Numbers

The query returns a list, and the type carries an isPrimary flag, because the underlying VAN data model is built to support more than one active virtual account number per spend account — for example, a dedicated payroll address and a per-customer address, all crediting the same balance. This is not available today. Every spend account is currently limited to exactly one VAN, and there is no API mutation, dashboard flow, or account-manager request that creates, views, or manages a second one. For Austin Capital Bank (Fluz’s current VAN sponsor), the one-VAN-per-spend-account cap is a global setting on ACB’s side, not a per-program one — so it isn’t something Fluz can configure or enable for an individual integration.

Read-only today, for every program.The read query above (getSpendAccountVirtualAccountNumbers) is the only VAN operation exposed, to every integration, with no exceptions. Support for additional VANs is a future capability, not something you can request or turn on today.

Build for the list anyway

Every spend account has exactly one VAN today, but code against the list shape rather than a single object. The API is already structured this way so that support for additional VANs, if it ships later, won’t be a breaking change for you.

Never index into the array. Do not read result[0]. Select the VAN where isPrimary is true.
Handle 0 explicitly (see Provisioning), even though the non-zero case today is always length 1.
Pass virtualAccountNumberId explicitly to the document queries rather than relying on the primary-VAN default, so your integration won’t need a code change if additional VANs are supported down the line.

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 whose accountholder has cleared CIP.
Your program must be entitled to VANs at the sponsor bank. This is agreed during onboarding and is not something the API can enable.
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, asynchronously, and cannot be created, modified, or deleted through the API or the dashboard. See Provisioning.
Assume a spend account may have zero or one VAN at read time today. Code against the list shape (don’t index into it) since additional VANs may be supported in the future.

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

​Provisioning

​Eligibility

​Trigger and timing

​Recommended integration pattern

​API and dashboard behave the same way

​Supported Rails

​What a Credit Looks Like

​Retrieve a User’s Virtual Account Numbers

​Multiple Virtual Account Numbers

​Build for the list anyway

​Handing the Details to a Third Party

​Requirements

​Related

Spend Accounts

Virtual Account Documents

Deposit Funds

Funding Sources

How It Fits Together

Provisioning

Eligibility

Trigger and timing

Recommended integration pattern

API and dashboard behave the same way

Supported Rails

What a Credit Looks Like

Retrieve a User’s Virtual Account Numbers

Multiple Virtual Account Numbers

Build for the list anyway

Handing the Details to a Third Party

Requirements

Related