Manage Virtual Card Funding Sources

Every virtual card draws from something when it is charged. Fluz gives you four sources, and a card can use more than one at a time.

By default, cards draw from three balances, not one.If you set a userCashBalanceId and nothing else, the card can still reach into the rewards balance and the prepayment balance when they have funds. That is the default and it is deliberate — but it means a card you believed was ringfenced to one budget can spend money from elsewhere on the account.To isolate a card to a single spend account, you must explicitly set usePrepaymentBalance: false and useRewardsBalance: false. See Isolating a card.

The two layers

Funding is configured in two independent layers. Getting them confused is the most common source of unexpected declines.

Primary funding source — where money is pulled from

primaryFundingSource is either FLUZ_BALANCE (money already held on the account) or BANK_ACCOUNT (pulled from a linked external bank via ACH). Defaults to FLUZ_BALANCE.

Balance composition — which internal balances can contribute

When the primary source is FLUZ_BALANCE, the card can draw from a specific spend account, the prepayment balance, and the rewards balance. userCashBalanceId, usePrepaymentBalance, and useRewardsBalance control which.

The four options

1. A specific spend account

Spend accounts are named sub-ledgers on the account — “Team Travel”, “Marketing”, “Payouts”. Nominate one with userCashBalanceId and the card draws from that balance rather than the account’s general cash balance.

{
  "primaryFundingSource": "FLUZ_BALANCE",
  "userCashBalanceId": "b1155504-ad30-4b2f-873d-b8795277b128"
}

This is the right default for anything that needs to be budgeted, attributed, or reconciled separately. To create additional spend accounts, see Create Spend Accounts; to list the ones you already have and read their balances, see Get Spend Accounts.

2. An external bank account

Set primaryFundingSource: BANK_ACCOUNT and supply bankAccountId. Fluz pulls from the linked account after the card is spent, so you do not have to pre-fund a balance.

{
  "primaryFundingSource": "BANK_ACCOUNT",
  "bankAccountId": "432bff1b-89b2-4df8-8298-0b6ae5e92945"
}

bankAccountId is required when primaryFundingSource is BANK_ACCOUNT. Omitting it fails the request with ARG-0001.

Bank accounts are linked through Plaid — see Linking Bank Account via Plaid and Manage linked bank accounts. To read the accounts already linked, use View Funding Sources.

3. Prepayment balance

The prepayment balance is a non-withdrawable balance usable toward gift card and virtual card purchases. It contributes automatically unless you switch it off.

{
  "usePrepaymentBalance": false
}

This balance goes by several names. It appears as usePrepaymentBalance on card input, as giftCardCashBalance in the getWallet response, and as “prepaid (gift card) balance” in prose. They are the same pool of money.

4. Rewards balance

Accumulated cashback and bonus rewards. Like the prepayment balance, it contributes by default.

{
  "useRewardsBalance": false
}

Leaving rewards on maximizes the use of money already earned. Switching it off keeps rewards intact for withdrawal and makes card spend attributable to a single budget — which is usually what a business or platform program wants.

Reference table

Field	Type	Default	Controls
`primaryFundingSource`	`VirtualCardFundingSource`	`FLUZ_BALANCE`	Whether the card pulls from Fluz-held funds or an external bank.
`bankAccountId`	`UUID`	—	Which linked bank account. Required when source is `BANK_ACCOUNT`.
`userCashBalanceId`	`UUID`	—	Which spend account the card draws from.
`usePrepaymentBalance`	`Boolean`	`true`	Whether the prepayment balance may contribute.
`useRewardsBalance`	`Boolean`	`true`	Whether the rewards balance may contribute.

Isolating a card to one spend account

The complete configuration for a card that can only ever spend from one nominated budget:

{
  "input": {
    "idempotencyKey": "07df5653-43a8-4532-9881-3ab5857bbe13",
    "offerId": "ed669305-5e43-40a0-9a25-7a15ed174628",
    "spendLimit": 150.00,
    "primaryFundingSource": "FLUZ_BALANCE",
    "userCashBalanceId": "b1155504-ad30-4b2f-873d-b8795277b128",
    "usePrepaymentBalance": false,
    "useRewardsBalance": false
  }
}

All three of userCashBalanceId, usePrepaymentBalance: false, and useRewardsBalance: false are required for true isolation. Setting the spend account alone is not enough.

Reading what is available

Before issuing, check that the source you are about to nominate actually has funds. getWallet returns every balance and linked funding source in one call.

query {
  getWallet {
    bankAccounts { bankAccountId }
    balances {
      rewardsBalance { availableBalance }
      cashBalance { availableBalance }
      giftCardCashBalance { availableBalance }
      userCashBalances(paginate: { limit: 20, offset: 0 }) {
        userCashBalanceId
        nickname
        availableCashBalance
        status
      }
    }
  }
}

Use availableCashBalance rather than totalCashBalance — the total can include funds that are pending and not yet spendable.

Changing funding after issuance

editVirtualCard accepts primaryFundingSource and bankAccountId, so you can move a card between Fluz balance and an external bank, or swap which bank account it pulls from.

{
  "input": {
    "idempotencyKey": "d3b07384-d9a0-4f1e-9b2c-7a5e8c1f2d64",
    "virtualCardId": "07df5653-43a8-4532-9881-3ab5857bbe11",
    "primaryFundingSource": "BANK_ACCOUNT",
    "bankAccountId": "432bff1b-89b2-4df8-8298-0b6ae5e92945"
  }
}

Balance composition appears to be set at issuance only. userCashBalanceId, usePrepaymentBalance, and useRewardsBalance are not in the published EditVirtualCardInput. If you need a card pointed at a different spend account, plan to issue a replacement rather than edit the existing card.

Account-level defaults are a different thing

Fluz also has an account-wide primary and backup payment method, set with setPrimaryFundingSource and setBackupFundingSource. These are not the same as per-card funding:

	Scope	Set with
Per-card funding	One virtual card	`createVirtualCard` / `editVirtualCard`
Account primary/backup	Account-wide default, used when nothing more specific applies	`setPrimaryFundingSource` / `setBackupFundingSource`

The backup payment method exists to cover the case where the primary source cannot be charged. See Primary & Backup Funding.

Create Spend Accounts

Add a new spend account to fund cards from.

Link Bank Accounts via Plaid

Connect an external bank account for BANK_ACCOUNT funding.

Check Account Balance

Read every balance and linked source before issuing.

Open Loop Card Funding

How funding differs on hosted open-loop cards.

​The two layers

​The four options

​1. A specific spend account

​2. An external bank account

​3. Prepayment balance

​4. Rewards balance

​Reference table

​Isolating a card to one spend account

​Reading what is available

​Changing funding after issuance

​Account-level defaults are a different thing

Create Spend Accounts

Link Bank Accounts via Plaid

Check Account Balance

Open Loop Card Funding

The two layers

The four options

1. A specific spend account

2. An external bank account

3. Prepayment balance

4. Rewards balance

Reference table

Isolating a card to one spend account

Reading what is available

Changing funding after issuance

Account-level defaults are a different thing