Skip to main content
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 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: Revisa availableCashBalance antes de cualquier ejecución de alto volumen. totalCashBalance menos el disponible es dinero en tránsito.

​
Cómo gestionarlas

→ Cuentas de gasto · Obtener cuentas de gasto

​
Todas las formas en que el dinero se mueve

​
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 · Fuentes de fondos

​
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

​
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.
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

​
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. El destinatario debe haber autorizado tu aplicación. → Transferencias de cuenta a cuenta · Búsqueda de destinatario

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

​
Lectura de saldos

Dos queries, dos granularidades: 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 · Ver fuentes de fondos

​
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

​
Scopes

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

​
Próximos pasos

Mover dinero a través de una billetera

El ciclo de vida completo de principio a fin, como un quickstart ejecutable.

Cuentas de gasto

Crear, fondear, renombrar y cerrar sublibros contables.

Fuentes de fondos

Vincula tarjetas bancarias, cuentas bancarias y billeteras digitales.

Depositar fondos

La referencia completa del input de depósito.

Retirar fondos

Métodos, tiempos y manejo de errores.

Actividad de transacciones

Cada movimiento en un solo feed filtrable.