Mover dinero a través de una billetera

Este Quickstart mueve dinero a través del ciclo de vida completo de la billetera: abre una cuenta de gasto diseñada para un propósito, fúndela, mueve fondos entre cuentas, envíalos de vuelta a una cuenta externa y verifica el libro mayor en cada paso: la plomería debajo de cada tarjeta y flujo de compra.

Requisitos previos

Una cuenta de Fluz con una aplicación de staging: Pasos 1–2 de cualquier quickstart, o consulta Prepara tus cuentas y Credenciales de API.
Una cuenta bancaria de prueba vinculada para las etapas de depósito y retiro: tu sandbox viene con fuentes de fondos de prueba, o agrega más desde Cuentas bancarias de prueba.
Cada mutación que mueva dinero necesita una idempotencyKey única: consulta Idempotencia.

El flujo completo

Genera un token con los cuatro alcances de la billetera

Este flujo toca cuatro alcances — uno por capacidad:

    {
      "scopes": ["MANAGE_PAYMENT", "LIST_PAYMENT", "MAKE_INTERNAL_TRANSFER", "MAKE_WITHDRAWAL"]
    }

MANAGE_PAYMENT crea cuentas y depósitos, LIST_PAYMENT los lee, MAKE_INTERNAL_TRANSFER mueve fondos entre tus cuentas, y MAKE_WITHDRAWAL envía fondos hacia afuera. Detalles para generar: Credenciales de API.

Crea una cuenta de gasto

Las cuentas de gasto son sublibros con nombre — “Viajes del equipo”, “Operaciones”, “Marketing” — que mantienen los presupuestos separados mientras viven bajo una sola cuenta de Fluz.

    mutation createUserCashBalance($input: CreateUserCashBalanceInput!) {
      createUserCashBalance(input: $input) {
        userCashBalanceId
        nickname
        availableCashBalance
        status
      }
    }

    { "input": { "nickname": "Team Travel" } }

    {
      "data": {
        "createUserCashBalance": {
          "userCashBalanceId": "f8a3c9e1-7b2d-4f5e-9c8a-1d2e3f4a5b6c",
          "nickname": "Team Travel",
          "availableCashBalance": "0",
          "status": "ACTIVE"
        }
      }
    }

Guarda el userCashBalanceId: cada paso posterior direcciona la cuenta con él. Tu cuenta también ya tiene una cuenta de gasto predeterminada; transferirás entre ambas en el Paso 4.

Deposita en ella

Fondea la nueva cuenta desde una fuente vinculada con depositCashBalance, apuntando a ella mediante userCashBalanceId:

    mutation depositCashBalance($input: DepositCashBalanceInput!) {
      depositCashBalance(input: $input) {
        cashBalanceDeposits { depositAmount status }
        balances {
          cashBalance { availableBalance totalBalance pendingBalance }
        }
      }
    }

    {
      "input": {
        "idempotencyKey": "3c9e1f8a-2b7d-4e5f-8c9a-6b5a4f3e2d1c",
        "amount": 100.00,
        "depositType": "CASH_BALANCE",
        "userCashBalanceId": "<TEAM_TRAVEL_ACCOUNT_ID>",
        "bankAccountId": "<YOUR_TEST_BANK_ACCOUNT_ID>"
      }
    }

Los depósitos pueden liquidarse al instante o dentro de 2–5 días hábiles según la fuente; los balances devueltos reflejan lo que está disponible ahora mismo. Los IDs de las fuentes de fondos provienen de getWallet: consulta Ver fuentes de fondos.

Transfiere entre tus cuentas

Mueve $25 desde la cuenta nueva a tu cuenta predeterminada con transferInternalBalance. Internamente se registra como dos movimientos vinculados: un retiro desde el origen y un depósito en el destino, y la respuesta devuelve ambos:

    mutation transferInternalBalance($input: TransferInternalBalanceInput!) {
      transferInternalBalance(input: $input) {
        withdraw { withdrawId amount status userCashBalanceId }
        cashBalanceDeposit { cashBalanceDepositId depositAmount status }
      }
    }

    {
      "input": {
        "idempotencyKey": "1f1df3e7-5d43-4e3d-83de-31922d4aefb7",
        "amount": 25.00,
        "sourceUserCashBalanceId": "<TEAM_TRAVEL_ACCOUNT_ID>",
        "destinationUserCashBalanceId": "<DEFAULT_ACCOUNT_ID>"
      }
    }

Ambos IDs deben ser tus propias cuentas de gasto, deben ser diferentes, y la cuenta origen necesita saldo disponible suficiente. Enviar a un usuario de Fluz diferente es una operación distinta: Transferir a otra billetera de Fluz.

Retira de vuelta

Completa el viaje de ida y vuelta enviando fondos a una cuenta externa con withdrawCashBalance — aquí vía ACH:

    mutation withdrawCashBalance($input: WithdrawCashBalanceInput!) {
      withdrawCashBalance(input: $input) {
        withdraws { withdrawId amount status displayStatus withdrawMethod }
      }
    }

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

method también acepta BANK_CARD (push-to-card, bankCardId), PAYPAL (paypalVaultId) y VENMO (venmoAccountId); cada uno requiere su campo de ID correspondiente. ACH típicamente liquida en 1–3 días hábiles, así que espera PENDING / PROCESSING al principio. Referencia completa: Retirar a cuenta externa.

Verifica el libro mayor

Cierra el ciclo leyendo nuevamente las cuentas con getUserCashBalances:

    query {
      getUserCashBalances {
        userCashBalances {
          userCashBalanceId
          nickname
          availableCashBalance
          totalCashBalance
          lifetimeCashBalance
          isDefault
          status
        }
        totalCount
      }
    }

Deberías ver la historia en los números: “Team Travel” con lifetimeCashBalance de 100.00 y un saldo disponible reducido (25 transferidos afuera, 50 retirándose), y tu cuenta predeterminada arriba 25.00. lifetimeCashBalance solo crece — es la pista de auditoría de todo lo que alguna vez se depositó.

Listo 🎉

Has ejecutado el ciclo de vida completo del libro mayor: crear, fondear, mover, pagar, verificar. Estas cuentas son el sustrato del que se alimenta todo lo demás:

Fondea una tarjeta virtual desde esta cuenta

Apunta userCashBalanceId a tu nueva cuenta para un gasto con tarjeta por presupuesto, limpio.

Envía fondos a otro usuario de Fluz

Busca un destinatario y mueve dinero de billetera a billetera.

Administra cuentas de gasto

Cambia el nombre, cierra y administra cuentas con el tiempo.

Actividad de transacciones

Cada movimiento anterior, en un solo feed filtrable con notas y categorías.

¿Quieres saber más? Contáctanos en support@fluz.app para hablar con nuestros expertos o solicitar una demo.

Comienza

Panel de Fluz

Guías rápidas

Mover dinero a través de una billetera

El flujo completo

Listo 🎉

Fondea una tarjeta virtual desde esta cuenta

Envía fondos a otro usuario de Fluz

Administra cuentas de gasto

Actividad de transacciones

​El flujo completo

​Listo 🎉

Fondea una tarjeta virtual desde esta cuenta

Envía fondos a otro usuario de Fluz

Administra cuentas de gasto

Actividad de transacciones

El flujo completo

Listo 🎉