Move Money Through a Wallet

This Quickstart runs money through the complete wallet lifecycle: open a purpose-built spend account, fund it, move funds between accounts, send them back out to an external account, and verify the ledger at each step — the plumbing under every card and purchase flow.

Prerequisites

A Fluz account with a staging application — Steps 1–2 of any quickstart, or see Prepare your accounts and API credentials.
A linked test bank account for the deposit and withdrawal legs — your sandbox ships with test funding sources, or add more from Test Bank Accounts.
Every money-moving mutation needs a unique idempotencyKey — see Idempotency.

The full flow

Mint a token with the four wallet scopes

This flow touches four scopes — one per capability:

    {
      "scopes": ["MANAGE_PAYMENT", "LIST_PAYMENT", "MAKE_INTERNAL_TRANSFER", "MAKE_WITHDRAWAL"]
    }

MANAGE_PAYMENT creates accounts and deposits, LIST_PAYMENT reads them, MAKE_INTERNAL_TRANSFER moves funds between your accounts, and MAKE_WITHDRAWAL sends funds out. Minting details: API credentials.

Create a spend account

Spend accounts are named sub-ledgers — “Team Travel”, “Operations”, “Marketing” — that keep budgets separate while living under one Fluz account.

    mutation createUserCashBalance($input: CreateUserCashBalanceInput!) {
      createUserCashBalance(input: $input) {
        userCashBalanceId
        nickname
        availableCashBalance
        status
      }
    }

    { "input": { "nickname": "Team Travel" } }

    {
      "data": {
        "createUserCashBalance": {
          "userCashBalanceId": "f8a3c9e1-7b2d-4f5e-9c8a-1d2e3f4a5b6c",
          "nickname": "Team Travel",
          "availableCashBalance": "0",
          "status": "ACTIVE"
        }
      }
    }

Save the userCashBalanceId — every later step addresses the account by it. Your account also has a default spend account already; you’ll transfer between the two in Step 4.

Deposit into it

Fund the new account from a linked source with depositCashBalance, targeting it via userCashBalanceId:

    mutation depositCashBalance($input: DepositCashBalanceInput!) {
      depositCashBalance(input: $input) {
        cashBalanceDeposits { depositAmount status }
        balances {
          cashBalance { availableBalance totalBalance pendingBalance }
        }
      }
    }

    {
      "input": {
        "idempotencyKey": "3c9e1f8a-2b7d-4e5f-8c9a-6b5a4f3e2d1c",
        "amount": 100.00,
        "depositType": "CASH_BALANCE",
        "userCashBalanceId": "<TEAM_TRAVEL_ACCOUNT_ID>",
        "bankAccountId": "<YOUR_TEST_BANK_ACCOUNT_ID>"
      }
    }

Deposits may settle instantly or within 2–5 business days depending on the source; the returned balances reflect what’s available right now. Funding source IDs come from getWallet — see View Funding Sources.

Transfer between your accounts

Move $25 from the new account into your default one with transferInternalBalance. Internally it’s recorded as two linked movements — a withdraw from the source and a deposit into the destination — and the response returns both:

    mutation transferInternalBalance($input: TransferInternalBalanceInput!) {
      transferInternalBalance(input: $input) {
        withdraw { withdrawId amount status userCashBalanceId }
        cashBalanceDeposit { cashBalanceDepositId depositAmount status }
      }
    }

    {
      "input": {
        "idempotencyKey": "1f1df3e7-5d43-4e3d-83de-31922d4aefb7",
        "amount": 25.00,
        "sourceUserCashBalanceId": "<TEAM_TRAVEL_ACCOUNT_ID>",
        "destinationUserCashBalanceId": "<DEFAULT_ACCOUNT_ID>"
      }
    }

Both IDs must be your own spend accounts, they must differ, and the source needs sufficient available balance. Sending to a different Fluz user is a different operation — Transfer to Another Fluz Account.

Withdraw back out

Complete the round trip by sending funds to an external account with withdrawCashBalance — here via ACH:

    mutation withdrawCashBalance($input: WithdrawCashBalanceInput!) {
      withdrawCashBalance(input: $input) {
        withdraws { withdrawId amount status displayStatus withdrawMethod }
      }
    }

    {
      "input": {
        "idempotencyKey": "550e8400-e29b-41d4-a716-446655440000",
        "amount": 50.00,
        "method": "BANK_ACH",
        "source": "CASH_BALANCE",
        "cashBalanceId": "<TEAM_TRAVEL_ACCOUNT_ID>",
        "bankAccountId": "<YOUR_TEST_BANK_ACCOUNT_ID>"
      }
    }

method also accepts BANK_CARD (push-to-card, bankCardId), PAYPAL (paypalVaultId), and VENMO (venmoAccountId) — each requires its matching ID field. ACH typically settles in 1–3 business days, so expect PENDING / PROCESSING at first. Full reference: Withdraw to External Account.

Verify the ledger

Close the loop by reading the accounts back with getUserCashBalances:

    query {
      getUserCashBalances {
        userCashBalances {
          userCashBalanceId
          nickname
          availableCashBalance
          totalCashBalance
          lifetimeCashBalance
          isDefault
          status
        }
        totalCount
      }
    }

You should see the story in the numbers: “Team Travel” with lifetimeCashBalance of 100.00 and a reduced available balance (25 transferred out, 50 withdrawing), and your default account up 25.00. lifetimeCashBalance only ever grows — it’s the audit trail of everything ever deposited.

You’re done 🎉

You’ve run the complete ledger lifecycle — create, fund, move, pay out, verify. These accounts are the substrate everything else draws on:

Fund a virtual card from this account

Point userCashBalanceId at your new account for clean per-budget card spend.

Send funds to another Fluz user

Look up a recipient and move money wallet-to-wallet.

Manage spend accounts

Rename, close, and administer accounts over time.

Transaction activity

Every movement above, in one filterable feed with memos and categories.

Want to learn more? Contact us at support@fluz.app to speak with our experts or request a demo.

Get started

Fluz Dashboard

Quickstarts

Move Money Through a Wallet

The full flow

You’re done 🎉

Fund a virtual card from this account

Send funds to another Fluz user

Manage spend accounts

Transaction activity

​The full flow

​You’re done 🎉

Fund a virtual card from this account

Send funds to another Fluz user

Manage spend accounts

Transaction activity

The full flow

You’re done 🎉