> ## 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. # Resumen > Los cuatro saldos de Fluz, cómo las cuentas de gasto particionan el saldo en efectivo y todas las formas en que el dinero entra, se mueve y sale. Una billetera de Fluz son dos cosas: un conjunto de **saldos** que almacenan valor y un conjunto de **vínculos a cuentas externas** que mueven valor dentro y fuera. Todas las tarjetas, compras y pagos del resto del API en última instancia se basan en esto. Tres preguntas deciden casi todo lo que construirás aquí: * **¿En cuál saldo está el dinero?** Tienen reglas diferentes: algunos se pueden retirar, otros solo se pueden gastar. * **¿En qué cuenta de gasto dentro del saldo en efectivo?** El efectivo se particiona en sublibros contables con nombre, y elegir el equivocado es la fuente más común de fallas sorpresa. * **¿El dinero se mueve hacia dentro, alrededor o hacia fuera?** Cada dirección es una mutación diferente con un alcance distinto. *** ## Los cuatro saldos | Saldo | Financiado por | Gastable | Retirable | Campo de API | | :----------------------- | :--------------------------------------------------------- | :------: | :-------: | :-------------------- | | **Saldo en efectivo** | Depósitos desde fuentes de fondos externas | ✓ | ✓ | `cashBalance` | | **Saldo de recompensas** | Cashback ganado en compras | ✓ | ✓ | `rewardsBalance` | | **Saldo de prepago** | Depósitos a `GIFT_CARD_BALANCE`, Fluz Gift Cards canjeadas | ✓ | ✗ | `giftCardCashBalance` | | **Saldo de reserva** | Depósitos a `RESERVE_BALANCE` | — | ✗ | — | ### Saldo en efectivo El saldo operativo. Financiado por depósitos, gastado en tarjetas de regalo y tarjetas virtuales, y retirable a una cuenta externa. No es un solo fondo: es el **agregado de tus cuentas de gasto**, que es la siguiente sección. ### Saldo de recompensas Cashback ganado en compras. Totalmente retirable y totalmente gastable. A diferencia de los saldos en efectivo y de prepago, no tiene monto pendiente, porque las recompensas se registran una vez ganadas en lugar de liquidarse con el tiempo. Retira de él pasando `source: "REWARDS_BALANCE"` — el único saldo además de efectivo que acepta `withdrawCashBalance`. ### Saldo de prepago **Un saldo, cuatro nombres.** El producto lo llama **saldo de prepago**. El campo del API es `giftCardCashBalance`, el enum de depósito es `GIFT_CARD_BALANCE`, y algunas páginas todavía lo llaman "saldo de tarjeta de regalo". Todo es lo mismo. Solo para gastar. Puedes fondearlo de dos maneras — un depósito con `depositType: "GIFT_CARD_BALANCE"`, o canjeando un código de Fluz Gift Card — y puedes gastarlo en compras, pero **nunca se puede retirar a una cuenta externa.** El dinero que entra al saldo de prepago solo sale al ser gastado. Ese es el objetivo de diseño, no una limitación: es valor prepagado, así que trata un depósito en él como un compromiso. Si podrías necesitar los fondos de vuelta, deposítalos en el saldo en efectivo en su lugar. ### Saldo de reserva Financiado depositando con `depositType: "RESERVE_BALANCE"`, y mantenido en reserva. No retirable. *** ## Cuentas de gasto Una **cuenta de gasto** es un sublibro contable con nombre del saldo en efectivo — "Operaciones", "Viajes del equipo", "Cliente A" — cada uno con su propio saldo, bajo una sola cuenta de Fluz. **"Cuenta de gasto", "saldo en efectivo" y `UserCashBalance` son el mismo objeto.** El producto lo muestra como una cuenta de gasto; el tipo del API es `UserCashBalance`, por lo que los campos son `userCashBalanceId`, `availableCashBalance`, etc. No lo confundas con `bankAccountId`, que se refiere a una cuenta bancaria vinculada *externa*. Cada cuenta tiene una cuenta de gasto **predeterminada**. Los depósitos, compras y fondeos de tarjetas que no nombran una cuenta se resuelven a la que esté marcada como `isDefault`. **Si tienes más de una cuenta de gasto, nómbrala explícitamente en cada operación.** Confiar en la predeterminada es la causa más común de fallas inesperadas por fondos insuficientes: un nuevo depósito enrutado a otro lugar, o un cambio en qué cuenta está marcada como predeterminada, redirige silenciosamente de dónde viene el dinero mientras tu código permanece idéntico. ### Los tres números Cada cuenta de gasto rastrea tres montos, y responden preguntas diferentes: | Campo | Pregunta que responde | | :--------------------- | :------------------------------------------------------------------------------- | | `availableCashBalance` | ¿Qué puedo gastar **ahora mismo**? | | `totalCashBalance` | ¿Qué hay en la cuenta, incluyendo montos aún no disponibles? | | `lifetimeCashBalance` | ¿Qué se ha depositado **alguna vez** aquí? Solo crece — es la pista de auditoría | Revisa `availableCashBalance` antes de cualquier ejecución de alto volumen. `totalCashBalance` menos el disponible es dinero en tránsito. ### Cómo gestionarlas | Operación | Mutación | | :-------- | :-------------------------------------------------------- | | Crear | `createUserCashBalance` — recibe un `nickname` | | Listar | `getUserCashBalances` — filtrable y paginada | | Leer una | `getUserCashBalanceById` | | Renombrar | [Editar cuentas de gasto](/features/edit-spend-accounts) | | Cerrar | [Cerrar cuentas de gasto](/features/close-spend-accounts) | → [Cuentas de gasto](/features/spend-accounts) · [Obtener cuentas de gasto](/features/get-spend-accounts) *** ## Todas las formas en que el dinero se mueve | De | A | Mutación | Alcance | | :--------------------------------- | :---------------------------------- | :----------------------------------------- | :----------------------- | | Fuente de fondos externa | Saldo en efectivo / cuenta de gasto | `depositCashBalance` — `CASH_BALANCE` | `MAKE_DEPOSIT` | | Fuente de fondos externa | Saldo de prepago | `depositCashBalance` — `GIFT_CARD_BALANCE` | `MAKE_DEPOSIT` | | Fuente de fondos externa | Saldo de reserva | `depositCashBalance` — `RESERVE_BALANCE` | `MAKE_DEPOSIT` | | Código de Fluz Gift Card | Saldo de prepago | `redeemFluzGiftCard` | `MAKE_DEPOSIT` | | Tu cuenta de gasto | Otra de tus cuentas de gasto | `transferInternalBalance` | `MAKE_INTERNAL_TRANSFER` | | Tu cuenta | La cuenta de otro usuario de Fluz | `createTransfer` | — | | Saldo en efectivo o de recompensas | Cuenta externa | `withdrawCashBalance` | `MAKE_WITHDRAWAL` | | Compras | Saldo de recompensas | Se gana automáticamente | — | ### Hacia dentro — depositar desde fuentes externas `depositCashBalance` extrae de una fuente de fondos vinculada hacia un saldo que elijas. * **Fuente de fondos:** `bankAccountId`, `bankCardId` o `paypalVaultId`, todos obtenidos desde `getWallet`. * **Destino:** `depositType` de `CASH_BALANCE`, `GIFT_CARD_BALANCE` o `RESERVE_BALANCE`. * **Cuenta de gasto:** con `CASH_BALANCE`, apunta una explícitamente usando `userCashBalanceId`. La liquidación varía de instantánea a 2–5 días hábiles según la fuente. El objeto `balances` devuelto refleja lo disponible inmediatamente, así que léelo en lugar de asumir que llegó el monto completo. → [Depositar fondos desde cuentas externas](/features/deposit-from-external-accounts) · [Fuentes de fondos](/features/funding-sources) ### Hacia dentro — canjear una Fluz Gift Card `redeemFluzGiftCard` acredita un **código** de Fluz Gift Card directamente al saldo de prepago. El canje es instantáneo, y cualquier tarifa de activación regresa en `depositFee`. Esta es la única forma de ingresar valor a la billetera sin una fuente de fondos vinculada — útil para promociones, reembolsos y obsequios, donde el destinatario puede no tener ninguna cuenta bancaria vinculada. → [Canjear Fluz Gift Card](/features/redeem-fluz-gift-card) ### Alrededor — entre tus propias cuentas de gasto `transferInternalBalance` mueve fondos entre dos cuentas de gasto que posees. Internamente se registra como dos movimientos vinculados — un retiro desde el origen y un depósito al destino — y la respuesta devuelve ambos. ```json theme={null} { "input": { "idempotencyKey": "1f1df3e7-5d43-4e3d-83de-31922d4aefb7", "amount": 25.00, "sourceUserCashBalanceId": "", "destinationUserCashBalanceId": "" } } ``` Ambos IDs deben ser de tus propias cuentas, deben ser distintos, y el origen necesita suficiente saldo **disponible**. Las transferencias internas se liquidan de inmediato — lo que las convierte en la forma más rápida de desbloquear una compra que está extrayendo de la cuenta equivocada. → [Transferir entre cuentas de gasto](/features/transfer-between-spend-accounts) ### Alrededor — a otro usuario de Fluz Enviar a una cuenta de Fluz *diferente* es una operación separada. Dirige el destino por `accountId`, o por tu propio identificador con `externalReferenceId` — ver [Administrar IDs de referencia externa](/managing-external-reference-ids). El destinatario debe haber autorizado tu aplicación. → [Transferencias de cuenta a cuenta](/features/account-to-account-transfers) · [Búsqueda de destinatario](/features/lookup-recipient) ### Hacia fuera — retirar a una cuenta externa `withdrawCashBalance` envía dinero hacia fuera. Elige un **saldo de origen** — `CASH_BALANCE` o `REWARDS_BALANCE`, los dos únicos que admiten retiros — y un **método**, proporcionando el ID de destino correspondiente: | Método | Campo requerido | Tiempos y costo | | :---------- | :--------------- | :-------------------------------------------------------------------- | | `BANK_ACH` | `bankAccountId` | 1–3 días hábiles, sin comisiones | | `BANK_CARD` | `bankCardId` | Push-to-card a una tarjeta de débito elegible, puede tener comisiones | | `PAYPAL` | `paypalVaultId` | Puede tener comisiones | | `VENMO` | `venmoAccountId` | Puede tener comisiones | Cuando el origen es el saldo en efectivo, nombra la cuenta de gasto desde la cual extraer. Espera un estado inicial `PENDING` o `PROCESSING` en ACH en lugar de una finalización inmediata. El input de retiro nombra el campo de la cuenta de gasto `cashBalanceId`, mientras que los depósitos y compras usan `userCashBalanceId`. Mismo objeto, nombre de campo diferente — una inconsistencia conocida a tener en cuenta. → [Retirar a cuenta externa](/features/withdraw-to-external-account) *** ## Lectura de saldos Dos queries, dos granularidades: | Query | Devuelve | | :-------------------- | :----------------------------------------------------------------------------------------------------------------------------------- | | `getWallet` | Todos los saldos — `cashBalance`, `rewardsBalance`, `giftCardCashBalance` — más fuentes de fondos vinculadas y `blockedPaymentTypes` | | `getUserCashBalances` | Detalle por cuenta de gasto: apodo, `isDefault`, estado y los tres montos | `getWallet` también es donde obtienes los IDs de las fuentes de fondos que necesita cada depósito y retiro. Revisa los saldos antes de mover dinero en lugar de reaccionar ante una falla. → [Consultar saldo de la cuenta](/check-account-balance) · [Ver fuentes de fondos](/features/view-funding-sources) *** ## Idempotencia Cada mutación que mueve dinero — depósito, canje, transferencia interna, transferencia de cuenta a cuenta, retiro — requiere un `idempotencyKey` único generado por el cliente. Reenviar la misma llave devuelve el resultado original en lugar de procesar de nuevo. **Genera una llave por movimiento previsto y reutilízala en cada reintento de ese movimiento.** Una llave nueva para un reintento es cómo suceden transferencias duplicadas. → [Idempotencia](/concepts/idempotency) *** ## Scopes | Scope | Cubre | | :----------------------- | :--------------------------------------------------------- | | `LIST_PAYMENT` | Lectura de billeteras, saldos y fuentes de fondos | | `MANAGE_PAYMENT` | Creación y gestión de cuentas de gasto y fuentes de fondos | | `MAKE_DEPOSIT` | Depósitos y canje de Fluz Gift Card | | `MAKE_INTERNAL_TRANSFER` | Movimiento de fondos entre tus propias cuentas de gasto | | `MAKE_WITHDRAWAL` | Envío de fondos a cuentas externas | Habilítalos primero en la pestaña **Permissions** de tu app — un scope que solicites pero no hayas habilitado se omite silenciosamente en lugar de ser rechazado. → [Configurar app OAuth](/configure-o-auth-app) *** ## Próximos pasos El ciclo de vida completo de principio a fin, como un quickstart ejecutable. Crear, fondear, renombrar y cerrar sublibros contables. Vincula tarjetas bancarias, cuentas bancarias y billeteras digitales. La referencia completa del input de depósito. Métodos, tiempos y manejo de errores. Cada movimiento en un solo feed filtrable.