> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fluz.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Move Money Through a Wallet

> The full ledger lifecycle — create a spend account, deposit into it, transfer between accounts, withdraw back out, and verify every balance.

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.

<Info>
  **Prerequisites**

  * A **Fluz account with a staging application** — Steps 1–2 of any quickstart, or see [Prepare your accounts](/get-started/prepare-accounts) and [API credentials](/get-started/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](/test-adding-bank-accounts).
  * Every money-moving mutation needs a unique `idempotencyKey` — see [Idempotency](/concepts/idempotency).
</Info>

## The full flow

Money enters from an external funding source, moves between spend accounts inside Fluz, and leaves the same way it came. Each arrow is one mutation, and each needs its own scope.

```mermaid theme={null}
flowchart LR
    EXT[External bank account<br/>or card]
    NEW[New spend account<br/>Team Travel]
    DEF[Default spend account]

    EXT -->|depositCashBalance<br/>MAKE_DEPOSIT| NEW
    NEW -->|transferInternalBalance<br/>MAKE_INTERNAL_TRANSFER| DEF
    NEW -->|withdrawCashBalance<br/>MAKE_WITHDRAWAL| EXT

    style EXT fill:#e8e8e8,stroke:#888
    style NEW fill:#d4edda,stroke:#5a9
    style DEF fill:#d4edda,stroke:#5a9
```

Transfers between your own spend accounts settle immediately. Deposits and withdrawals involve an external institution, so they land as `PENDING` and settle on the network's timetable.

<Steps>
  <Step title="Mint a token with the five wallet scopes" icon="key">
    This flow touches five scopes — one per capability:

    ```json theme={null}
        {
          "scopes": ["MANAGE_PAYMENT", "LIST_PAYMENT", "MAKE_DEPOSIT", "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](/get-started/api-credentials).
  </Step>

  <Step title="Create a spend account" icon="wallet">
    Spend accounts are named sub-ledgers — "Team Travel", "Operations", "Marketing" — that keep budgets separate while living under one Fluz account.

    <CodeGroup>
      ```graphql Mutation theme={null}
          mutation createUserCashBalance($input: CreateUserCashBalanceInput!) {
            createUserCashBalance(input: $input) {
              userCashBalanceId
              nickname
              availableCashBalance
              status
            }
          }
      ```

      ```json Variables theme={null}
          { "input": { "nickname": "Team Travel" } }
      ```

      ```json Response theme={null}
          {
            "data": {
              "createUserCashBalance": {
                "userCashBalanceId": "f8a3c9e1-7b2d-4f5e-9c8a-1d2e3f4a5b6c",
                "nickname": "Team Travel",
                "availableCashBalance": "0",
                "status": "ACTIVE"
              }
            }
          }
      ```
    </CodeGroup>

    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.
  </Step>

  <Step title="Deposit into it" icon="banknote-arrow-down">
    Fund the new account from a linked source with `depositCashBalance`, targeting it via `userCashBalanceId`:

    <CodeGroup>
      ```graphql Mutation theme={null}
          mutation depositCashBalance($input: DepositCashBalanceInput!) {
            depositCashBalance(input: $input) {
              cashBalanceDeposits { depositAmount status }
              balances {
                cashBalance { availableBalance totalBalance pendingBalance }
              }
            }
          }
      ```

      ```json Variables theme={null}
          {
            "input": {
              "idempotencyKey": "3c9e1f8a-2b7d-4e5f-8c9a-6b5a4f3e2d1c",
              "amount": 100.00,
              "depositType": "CASH_BALANCE",
              "userCashBalanceId": "<TEAM_TRAVEL_ACCOUNT_ID>",
              "bankAccountId": "<YOUR_TEST_BANK_ACCOUNT_ID>"
            }
          }
      ```
    </CodeGroup>

    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](/features/view-funding-sources).
  </Step>

  <Step title="Transfer between your accounts" icon="arrow-left-right">
    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:

    <CodeGroup>
      ```graphql Mutation theme={null}
          mutation transferInternalBalance($input: TransferInternalBalanceInput!) {
            transferInternalBalance(input: $input) {
              withdraw { withdrawId amount status userCashBalanceId }
              cashBalanceDeposit { cashBalanceDepositId depositAmount status }
            }
          }
      ```

      ```json Variables theme={null}
          {
            "input": {
              "idempotencyKey": "1f1df3e7-5d43-4e3d-83de-31922d4aefb7",
              "amount": 25.00,
              "sourceUserCashBalanceId": "<TEAM_TRAVEL_ACCOUNT_ID>",
              "destinationUserCashBalanceId": "<DEFAULT_ACCOUNT_ID>"
            }
          }
      ```
    </CodeGroup>

    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](/features/transfer-to-another-fluz-wallet).
  </Step>

  <Step title="Withdraw back out" icon="banknote-arrow-up">
    Complete the round trip by sending funds to an external account with `withdrawCashBalance` — here via ACH:

    <CodeGroup>
      ```graphql Mutation theme={null}
          mutation withdrawCashBalance($input: WithdrawCashBalanceInput!) {
            withdrawCashBalance(input: $input) {
              withdraws { withdrawId amount status displayStatus withdrawMethod }
            }
          }
      ```

      ```json Variables theme={null}
          {
            "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>"
            }
          }
      ```
    </CodeGroup>

    `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](/features/withdraw-to-external-account).
  </Step>

  <Step title="Verify the ledger" icon="list-checks">
    Close the loop by reading the accounts back with `getUserCashBalances`:

    ```graphql theme={null}
        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.
  </Step>
</Steps>

## 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:

<CardGroup cols={2}>
  <Card title="Fund a virtual card from this account" icon="credit-card" href="/quickstart/create-and-spend-with-a-virtual-card">
    Point `userCashBalanceId` at your new account for clean per-budget card spend.
  </Card>

  <Card title="Send funds to another Fluz user" icon="send" href="/features/account-to-account-transfers">
    Look up a recipient and move money wallet-to-wallet.
  </Card>

  <Card title="Manage spend accounts" icon="settings" href="/features/edit-spend-accounts">
    Rename, close, and administer accounts over time.
  </Card>

  <Card title="Transaction activity" icon="receipt" href="/features/get-all-transactions">
    Every movement above, in one filterable feed with memos and categories.
  </Card>
</CardGroup>

<Note>
  **Want to learn more?** Contact us at [support@fluz.app](mailto:support@fluz.app) to speak with our experts or request a demo.
</Note>