Billeteras y transferencias

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

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

Pull — tú inicias

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.

Push — alguien más inicia

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	ACH pull, tarjeta, PayPal	Tu app	Una cuenta de gasto elegida
Número de cuenta virtual	RTP, FedNow, Wire, ACH credit	Un remitente externo	La cuenta de gasto detrás de ese VAN
Canjear una tarjeta de regalo de Fluz	—	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.

Mover y retirar fondos

Acción	Operación	Alcance
Transferir entre cuentas de gasto	Transferencia interna	`MANAGE_PAYMENT`
Transferir a otra cuenta de Fluz	Transferencia de billetera	`MANAGE_PAYMENT`
Buscar un destinatario de transferencia	Resolver un `account_id`	—
Retirar a una cuenta externa	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.

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.

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

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
  }
}

Variables

{
  "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 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

Cuentas de gasto

Crea, renombra y cierra las cuentas que contienen el saldo.

Números de cuenta virtuales

Recibe créditos RTP, FedNow, wire y ACH directamente en una cuenta de gasto.

Depositar fondos

Ingresa dinero desde una cuenta bancaria o tarjeta vinculada.

Retirar fondos

Mueve dinero a una cuenta externa.

Transferir entre cuentas

Mueve saldo entre las propias cuentas de gasto de un usuario.

Obtener todas las transacciones

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.

​El mapa del dinero

​Tipos de saldo

​Las cuentas de gasto contienen el saldo

​Ingresando fondos

Pull — tú inicias

Push — alguien más inicia

​Mover y retirar fondos

​Lectura de saldos

​Lectura del libro mayor

​Scopes de un vistazo

​A dónde ir después

Cuentas de gasto

Números de cuenta virtuales

Depositar fondos

Retirar fondos

Transferir entre cuentas

Obtener todas las transacciones

El mapa del dinero

Tipos de saldo

Las cuentas de gasto contienen el saldo

Ingresando fondos

Mover y retirar fondos

Lectura de saldos

Lectura del libro mayor

Scopes de un vistazo

A dónde ir después