> ## 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.
# Billeteras y transferencias
> Cómo se mantiene y mueve el dinero en Fluz: tipos de saldo, cuentas de gasto, fondeo desde fuentes externas o números de cuenta virtuales, y cómo leer el libro mayor.
Cada dólar en Fluz se encuentra en un **saldo**. El dinero entra a un saldo desde una fuente de fondos externa o un número de cuenta virtual, se mueve entre saldos mediante transferencias y sale a través de compras o retiros. Esta sección cubre todo eso.
Lo más útil que debes entender primero: **una cuenta no tiene un solo saldo. Tiene varios, y se comportan de manera diferente.** Algunos son retirables, otros no, y uno de ellos —la cuenta de gasto— puede existir muchas veces.
***
## El mapa del dinero
```mermaid theme={null}
flowchart LR
subgraph IN["Money In"]
F1["Bank account (ACH)"]
F2["Bank card"]
F3["PayPal / Apple Pay"]
F4["Virtual account number\nRTP · FedNow · Wire · ACH"]
F5["Fluz gift card redemption"]
F6["Cashback earned"]
end
subgraph BAL["Balances"]
SA1["Spend Account\n'Operations'"]
SA2["Spend Account\n'Team Travel'"]
RW["Rewards Balance"]
GC["Gift Card Balance\nnon-withdrawable"]
RS["Reserve Balance\nnon-withdrawable"]
end
subgraph OUT["Money Out"]
O1["Gift card purchases"]
O2["Virtual card funding"]
O3["Transfers to other\nFluz accounts"]
O4["Withdrawals to\nexternal accounts"]
end
F1 & F2 & F3 --> SA1
F4 --> SA1
F4 --> SA2
F5 --> GC
F6 --> RW
SA1 & SA2 --> O1 & O2 & O3 & O4
RW --> O1 & O4
GC --> O1 & O2
RS -.->|covers failed settlement| O1
```
***
## Tipos de saldo
Una cuenta puede mantener hasta cuatro tipos de saldo. Las cuentas de gasto son las únicas de las que un usuario puede tener más de una.
| Saldo | Retirable | Qué contiene |
| --------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------ |
| **Cuenta de gasto** (saldo en efectivo) | Sí | El saldo operativo principal. Fondea tarjetas de regalo, tarjetas virtuales, transferencias y retiros. |
| **Saldo de recompensas** | Sí | Cashback y recompensas de bonificación ganadas por actividad en Fluz. |
| **Saldo de tarjetas de regalo** | No | Valor prepago utilizable solo para compras de tarjetas de regalo y tarjetas virtuales. |
| **Saldo de reserva** | No | Mantenido por Fluz para cubrir transacciones que no se asientan, manteniendo la cuenta en buen estado. |
La suma de estos es el **saldo disponible de Fluz** de la cuenta: el total que se puede aplicar para fondear un pago.
**El mismo saldo aparece con más de un nombre.**
El saldo de tarjetas de regalo se devuelve como `giftCardCashBalance` en `getWallet` y como `gift_card_prepayment_balance_*` en el tipo `Transaction`. El saldo de recompensas es `rewardsBalance` en `getWallet` y `seat_balance_*` en `Transaction`. Son alias, no fondos separados.
***
## Las cuentas de gasto contienen el saldo
Una [cuenta de gasto](/features/spend-accounts) — `UserCashBalance` en la API — es un contenedor con nombre para efectivo. Un usuario puede abrir varias y asignar a cada una un apodo, para separar fondos por propósito sin abrir cuentas de Fluz por separado.
**Cada cuenta de gasto lleva su propio saldo independiente.** El dinero en una no se puede gastar desde otra hasta que se mueva con una [transferencia interna](/features/transfer-between-spend-accounts).
```mermaid theme={null}
flowchart TD
ACC["Fluz Account"]
ACC --> RW["Rewards Balance\naccount-level, one only"]
ACC --> GC["Gift Card Balance\naccount-level, one only"]
ACC --> RS["Reserve Balance\naccount-level, one only"]
ACC --> SAS["Spend Accounts\none or many"]
SAS --> S1["'Operations'\ntotal · available · lifetime\n+ virtual account numbers"]
SAS --> S2["'Team Travel'\ntotal · available · lifetime\n+ virtual account numbers"]
SAS --> S3["'Marketing'\ntotal · available · lifetime\n+ virtual account numbers"]
S1 <-->|internal transfer| S2
S2 <-->|internal transfer| S3
```
Cada cuenta de gasto rastrea tres cifras, todas devueltas como strings:
| Campo | Significado |
| ---------------------- | ------------------------------------------------------------ |
| `totalCashBalance` | El saldo total actualmente mantenido en la cuenta. |
| `availableCashBalance` | La porción que se puede gastar ahora mismo. |
| `lifetimeCashBalance` | Total acumulado depositado en esta cuenta desde su creación. |
***
## Ingresando fondos
Hay dos direcciones fundamentalmente diferentes por las que el dinero puede entrar a un saldo, y la distinción es importante para cómo construyes.
Tu aplicación llama `depositCashBalance` y Fluz extrae fondos de una **fuente de fondos** que el usuario ya vinculó: una cuenta bancaria, tarjeta bancaria o billetera digital. Tú controlas el momento y el monto.
Un tercero envía dinero a un **número de cuenta virtual** adjunto a una cuenta de gasto. Fluz lo registra como un depósito cuando llega. No controlas el momento ni el monto.
| Ruta | Rieles | Iniciado por | Aterriza en |
| ------------------------------------------------------------------------ | ----------------------------- | -------------------- | ------------------------------------ |
| [Depositar fondos](/features/deposit-from-external-accounts) | ACH pull, tarjeta, PayPal | Tu app | Una cuenta de gasto elegida |
| [Número de cuenta virtual](/features/virtual-account-numbers) | RTP, FedNow, Wire, ACH credit | Un remitente externo | La cuenta de gasto detrás de ese VAN |
| [Canjear una tarjeta de regalo de Fluz](/features/redeem-fluz-gift-card) | — | El usuario | Saldo de tarjetas de regalo |
| Cashback por actividad que califica | — | Fluz | Saldo de recompensas |
**Un número de cuenta virtual es una dirección, no un saldo.**
Cada cuenta de gasto puede tener uno o más números de cuenta virtuales — pares reales de routing y número de cuenta. Cualquier cosa enviada a ellos acredita esa cuenta de gasto. Múltiples VAN en una cuenta alimentan el mismo saldo; existen para que puedas distinguir un abono de nómina de un pago de cliente. Ver [Números de cuenta virtuales](/features/virtual-account-numbers).
***
## Mover y retirar fondos
| Acción | Operación | Alcance |
| ------------------------------------------------------------------------------ | -------------------------- | ---------------- |
| [Transferir entre cuentas de gasto](/features/transfer-between-spend-accounts) | Transferencia interna | `MANAGE_PAYMENT` |
| [Transferir a otra cuenta de Fluz](/features/application-transfer) | Transferencia de billetera | `MANAGE_PAYMENT` |
| [Buscar un destinatario de transferencia](/features/lookup-recipient) | Resolver un `account_id` | — |
| [Retirar a una cuenta externa](/features/withdraw-funds) | Retiro | `MANAGE_PAYMENT` |
**Los saldos de tarjetas de regalo y de reserva no se pueden retirar.** El saldo de tarjetas de regalo solo se puede gastar en compras de tarjetas de regalo y tarjetas virtuales. El saldo de reserva es mantenido por Fluz y no es dirigido por el usuario.
***
## Lectura de saldos
`getWallet` devuelve los saldos de la cuenta en una sola llamada, junto con las fuentes de fondos vinculadas del usuario.
```graphql theme={null}
query getWallet {
getWallet {
balances {
rewardsBalance { availableBalance totalBalance lifetimeBalance }
cashBalance { availableBalance totalBalance pendingBalance lifetimeBalance }
giftCardCashBalance { availableBalance totalBalance pendingBalance lifetimeBalance }
userCashBalances(paginate: { limit: 10, offset: 0 }) {
userCashBalanceId
nickname
totalCashBalance
availableCashBalance
lifetimeCashBalance
status
createdAt
}
}
blockedPaymentTypes
}
}
```
`userCashBalances` es paginado y devuelve cuentas ordenadas por fecha de creación, la más reciente primero. Para obtener una sola cuenta de gasto, usa [`getUserCashBalanceById`](/features/get-spend-accounts).
**Para mostrar el total de efectivo gastable de un usuario, suma `availableCashBalance` a través de `userCashBalances`.** No agregues `cashBalance` además de las cifras de cada cuenta de gasto; hacerlo inflará el total.
El saldo de reserva es mantenido por Fluz en lugar de ser dirigido por el usuario. Su estado actual es visible en cada transacción mediante los campos de snapshot `reserve_balance_available_balance` y `reserve_balance_total_balance` descritos a continuación.
***
## Lectura del libro mayor
Los saldos te dicen dónde están las cosas. `getTransactions` te dice cómo llegaron allí. Para ver el libro mayor de una cuenta de gasto específica, filtra por su ID.
**Scopes requeridos:** `LIST_PAYMENT` **y** `LIST_PURCHASES`
```graphql theme={null}
query spendAccountLedger($userCashBalanceId: [UUID], $limit: Int, $offset: Int) {
getTransactions(
filter: { userCashBalanceId: $userCashBalanceId }
paginate: { limit: $limit, offset: $offset }
) {
transactions {
record_id
transaction_type
amount
source
destination
status
used_user_cash_balance_id
cash_balance_available_balance
created_at
}
totalCount
hasNextPage
}
}
```
```json Variables theme={null}
{
"userCashBalanceId": ["9c1f6b2e-4d7a-4c3b-9f11-2a5e8b0d6c74"],
"limit": 20,
"offset": 0
}
```
Cada transacción también incluye un **snapshot de saldo**: el estado de cada saldo después de que se aplicó esa transacción, más banderas que indican qué saldos tocó la transacción:
| Saldo | Campos de snapshot | Bandera de afectación |
| ----------------- | ----------------------------------------------------------------------------------------------- | ------------------------------- |
| Gasto / efectivo | `cash_balance_available_balance` · `cash_balance_total_balance` | `is_cash_balance_affected` |
| Recompensas | `seat_balance_available_balance` · `seat_balance_total_balance` | `is_seat_balance_affected` |
| Tarjeta de regalo | `gift_card_prepayment_balance_available_balance` · `gift_card_prepayment_balance_total_balance` | `is_gift_card_balance_affected` |
| Reserva | `reserve_balance_available_balance` · `reserve_balance_total_balance` | `is_reserve_balance_affected` |
| Otro efectivo | `other_cash_balance_available_balance` · `other_cash_balance_total_balance` | — |
**Solo las cuentas de gasto pueden filtrarse por ID.** `TransactionFilterInput` expone `userCashBalanceId`, pero no hay un filtro equivalente para los saldos de recompensas, tarjetas de regalo o reserva. Para aislar la actividad en esos, recupera transacciones sobre un rango de fechas y filtra por la bandera `is_..._affected` correspondiente.
`getTransactions` está limitado a **20 registros por página**. Revisa `hasNextPage` y avanza `offset` para paginar. Consulta [Obtener todas las transacciones](/features/get-all-transactions) para la referencia completa de filtros.
***
## Scopes de un vistazo
| Quieres… | Scope |
| ------------------------------------------ | --------------------------------- |
| Leer saldos, cuentas de gasto y VANs | `LIST_PAYMENT` |
| Leer el libro mayor de transacciones | `LIST_PAYMENT` + `LIST_PURCHASES` |
| Crear, editar o cerrar una cuenta de gasto | `MANAGE_PAYMENT` |
| Depositar, transferir o retirar | `MANAGE_PAYMENT` |
***
## A dónde ir después
Crea, renombra y cierra las cuentas que contienen el saldo.
Recibe créditos RTP, FedNow, wire y ACH directamente en una cuenta de gasto.
Ingresa dinero desde una cuenta bancaria o tarjeta vinculada.
Mueve dinero a una cuenta externa.
Mueve saldo entre las propias cuentas de gasto de un usuario.
El libro mayor completo, con filtrado y paginación.
***
**¿Quieres saber más?** Habla con nuestros expertos para obtener más información o solicitar una demo.