Retirar a cuenta externa

Descripción general

Un retiro permite a los usuarios transferir fondos de su saldo de Fluz a una cuenta externa. Los usuarios pueden retirar desde dos tipos de saldos:

Saldo en efectivo - Fondos depositados por el usuario en su cuenta de Fluz
Saldo de recompensas - Ganancias de cashback acumuladas por compras

Fluz admite los siguientes métodos de retiro:

Método	Descripción
`BANK_ACH`	Transferencia ACH a una cuenta bancaria vinculada
`BANK_CARD`	Transferencia push-to-card a una tarjeta de débito vinculada, entregada como una transacción de crédito original (OCT)
`PAYPAL`	Transferencia a una cuenta de PayPal vinculada
`VENMO`	Transferencia a una cuenta de Venmo vinculada

Retirar saldo en efectivo

Ejemplo de solicitud

Puedes iniciar un retiro con la mutación withdrawCashBalance. Esta mutación transfiere fondos del saldo de Fluz de un usuario a su cuenta externa especificada.

{
  "query": "mutation withdrawCashBalance($input: WithdrawCashBalanceInput!) { withdrawCashBalance(input: $input) { withdraws { withdrawId amount processingFee chargedFee status displayStatus withdrawMethod withdrawSource submissionDate createdAt updatedAt transactionLogId bankAccountId userCashBalanceId seatId } balances { cashBalance { availableBalance totalBalance } rewardsBalance { availableBalance totalBalance } } } }",
  "variables": {
    "input": {
      "idempotencyKey": "550e8400-e29b-41d4-a716-446655440000",
      "amount": 100.00,
      "method": "BANK_ACH",
      "source": "CASH_BALANCE",
      "bankAccountId": "a578fe07-7165-47b8-b147-2251c99b7fc1",
      "cashBalanceId": "8d197a56-53df-439b-85cd-bb88dfca9a5f"
    }
  }
}

Esta mutación requiere el tipo de entrada WithdrawCashBalanceInput. Cualquier campo marcado con un signo de exclamación (!) en el esquema es obligatorio y debe incluirse en la solicitud.

Campos de entrada

Nombre del campo	Tipo	Descripción
`idempotencyKey`	`UUID!`	Un UUID único generado por el cliente para garantizar que la solicitud se procese solo una vez. Esto evita retiros duplicados si se envía la misma solicitud varias veces.
`amount`	`Float!`	El monto a retirar. Debe ser mayor que 0.
`method`	`WithdrawMethods!`	El método de retiro a usar. Uno de: `PAYPAL`, `BANK_ACH`, `BANK_CARD`, `VENMO`.
`source`	`WithdrawSource`	El saldo de origen desde el cual retirar fondos. Uno de: `CASH_BALANCE`, `REWARDS_BALANCE`. Por defecto es `CASH_BALANCE` si no se especifica.
`bankAccountId`	`UUID`	Requerido cuando `method` es `BANK_ACH`. El identificador de la cuenta bancaria vinculada para retiros por ACH.
`bankCardId`	`UUID`	Requerido cuando `method` es `BANK_CARD`. El identificador de la tarjeta de débito vinculada para retiros push-to-card.
`paypalVaultId`	`UUID`	Requerido cuando `method` es `PAYPAL`. El identificador de la cuenta de PayPal vinculada.
`venmoAccountId`	`UUID`	Requerido cuando `method` es `VENMO`. El identificador de la cuenta de Venmo vinculada.
`cashBalanceId`	`UUID`	El identificador de la cuenta específica de saldo en efectivo desde la cual retirar. Requerido cuando `source` es `CASH_BALANCE`.
`isExpedited`	`Boolean`	Si es `true`, el retiro se procesa de inmediato. Si es `false` o se omite, se procesa en un calendario estándar de liquidación. Actualmente aplica a retiros `BANK_CARD`, y las dos velocidades tienen precios distintos — puedes previsualizarlos con `getWithdrawFeeEstimate`.

WithdrawCashBalanceInput

{
  "idempotencyKey": "550e8400-e29b-41d4-a716-446655440000",
  "amount": 100.00,
  "method": "BANK_ACH",
  "source": "CASH_BALANCE",
  "bankAccountId": "a578fe07-7165-47b8-b147-2251c99b7fc1",
  "bankCardId": null,
  "paypalVaultId": null,
  "venmoAccountId": null,
  "cashBalanceId": "8d197a56-53df-439b-85cd-bb88dfca9a5f",
  "isExpedited": false
}

Ejemplo de respuesta

La respuesta de la mutación withdrawCashBalance incluye el/los registro(s) del retiro y los saldos actualizados del usuario.

{
  "data": {
    "withdrawCashBalance": {
      "withdraws": [
        {
          "withdrawId": "c4d5e6f7-8901-2345-6789-0abcdef12345",
          "amount": "100.00",
          "processingFee": "0.00",
          "chargedFee": "0.00",
          "status": "PENDING",
          "displayStatus": "PROCESSING",
          "withdrawMethod": "BANK_ACH",
          "withdrawSource": "CASH_BALANCE",
          "submissionDate": "2024-01-15T10:30:00Z",
          "createdAt": "2024-01-15T10:30:00Z",
          "updatedAt": "2024-01-15T10:30:00Z",
          "transactionLogId": "f1234567-89ab-cdef-0123-456789abcdef",
          "bankAccountId": "a578fe07-7165-47b8-b147-2251c99b7fc1",
          "userCashBalanceId": "8d197a56-53df-439b-85cd-bb88dfca9a5f",
          "seatId": "e7979eb7-1727-48ed-8c5a-c56532908c1e"
        }
      ]
    }
  }
}

Campos de la respuesta

Objeto Withdraw

Nombre del campo	Tipo	Descripción
`withdrawId`	`UUID!`	Identificador único del retiro.
`amount`	`String!`	El monto retirado.
`processingFee`	`String!`	Comisión cobrada por procesar el retiro.
`chargedFee`	`String!`	Comisión cobrada al usuario por el retiro.
`status`	`String!`	Estado interno del retiro (p. ej., `PENDING`, `COMPLETED`, `FAILED`).
`displayStatus`	`String!`	Estado visible para el usuario (p. ej., `PROCESSING`, `COMPLETE`).
`withdrawMethod`	`WithdrawMethods!`	El método de retiro utilizado.
`withdrawSource`	`WithdrawSource!`	El saldo de origen desde el cual se retiraron fondos.
`submissionDate`	`DateTime!`	Fecha y hora en que se presentó el retiro.
`createdAt`	`DateTime!`	Fecha y hora en que se creó el retiro.
`updatedAt`	`DateTime!`	Fecha y hora de la última actualización del retiro.
`transactionLogId`	`UUID`	Identificador del registro de transacción asociado.
`externalTransactionId`	`String`	Identificador de transacción externo del gateway de pagos (para ACH).
`payoutId`	`String`	Identificador del pago en el gateway de pagos (para PayPal/Venmo).
`emailAddress`	`String`	Dirección de correo electrónico asociada con el retiro.
`bankAccountId`	`UUID`	Identificador de la cuenta bancaria usada (si aplica).
`userCashBalanceId`	`UUID`	Identificador de la cuenta de saldo en efectivo del usuario desde la cual se retiró.
`seatId`	`UUID`	El ID de la posición (seat) asociada con la cuenta.

Alcance requerido

Esta mutación requiere que el token de acceso tenga otorgado el alcance MAKE_WITHDRAWAL. La consulta getWithdrawFeeEstimate requiere el mismo alcance.

generateUserAccessToken(
  userId: "...",
  accountId: "...",
  scopes: [MAKE_WITHDRAWAL]
)

Métodos de retiro por tipo de cuenta

Método	Campo requerido	Notas
`BANK_ACH`	`bankAccountId`	Transferencia ACH estándar. Normalmente liquida en 1-3 días hábiles. Sin comisiones.
`BANK_CARD`	`bankCardId`	Transferencia push-to-card, entregada como una transacción de crédito original (OCT). Disponible solo para tarjetas de débito elegibles. Configura `isExpedited: true` para entrega inmediata, o omítelo para liquidación en el calendario estándar. Puede tener comisiones.
`PAYPAL`	`paypalVaultId`	Transferencia a cuenta de PayPal vinculada. Puede tener comisiones.
`VENMO`	`venmoAccountId`	Transferencia a cuenta de Venmo vinculada. Puede tener comisiones.

Previsualizar comisiones antes de retirar

Usa la consulta getWithdrawFeeEstimate para cotizar un retiro antes de enviarlo. Pasa el mismo amount, method, source e isExpedited que piensas enviar, y la respuesta te indicará exactamente cuánto recibirá el usuario.

{
  "query": "query getWithdrawFeeEstimate($input: GetWithdrawFeeEstimateInput!) { getWithdrawFeeEstimate(input: $input) { fee netAmount feePercent feeMaxCap settlementDelayDays } }",
  "variables": {
    "input": {
      "amount": 100.00,
      "method": "BANK_CARD",
      "source": "CASH_BALANCE",
      "isExpedited": true
    }
  }
}

Nombre del campo	Tipo	Descripción
`fee`	`Float!`	La comisión que se cobrará por este retiro.
`netAmount`	`Float!`	El monto que el usuario realmente recibirá, después de comisiones.
`feePercent`	`Float!`	El porcentaje de comisión aplicado.
`feeMaxCap`	`Float`	El tope máximo de comisión en dólares, si aplica.
`settlementDelayDays`	`Int`	Días hábiles hasta la liquidación. `null` para retiros acelerados que liquidan de inmediato.

La comisión se deduce del retiro en lugar de sumarse encima: el saldo se debita por el amount completo, y el destino recibe netAmount. Pasar FLUZPAY como method devuelve ARG-0001.

Retiros push-to-card (OCT)

Un retiro BANK_CARD es un pago push-to-card, entregado como una transacción de crédito original (OCT) — el tipo de transacción de red de tarjetas para abonar fondos a una tarjeta. Requiere bankCardId, y la tarjeta de débito vinculada debe admitir OCT. Una tarjeta no elegible no puede recibirse por ningún otro medio, por lo que el usuario debe elegir otro método de retiro. La velocidad de entrega se controla con isExpedited:

`isExpedited`	Comportamiento
`true`	Los fondos se envían a la tarjeta durante la solicitud.
`false` o omitido	El retiro se registra como `PENDING` y se libera después de `settlementDelayDays` días hábiles.

Un retiro push-to-card PENDING aún no es definitivo.Un retiro estándar se entrega a la tarjeta después del tiempo de liquidación y aún puede fallar en ese momento — por ejemplo, si la tarjeta ya no puede recibir el pago. Cuando sucede, los fondos se acreditan de vuelta al saldo de origen. Reconciliá el estado del retiro en lugar de tratar la respuesta inicial PENDING como un pago completado.

Elegibilidad de la tarjeta

La mayoría de las tarjetas de débito Visa y Mastercard pueden recibir un pago push-to-card. La elegibilidad se evalúa cuando se envía el retiro y es una propiedad de la propia tarjeta más que algo que configures.

La elegibilidad no está disponible por adelantado y no se hereda desde los depósitos.No hay una consulta que informe si una tarjeta admite OCT — esto se muestra en el primer retiro a esa tarjeta. La elegibilidad para retiros y depósitos también es independiente, por lo que una tarjeta desde la que un usuario depositó exitosamente no es necesariamente una tarjeta a la que puedas enviar un retiro. Ver Depositar desde cuentas externas.

Los retiros BANK_CARD no están restringidos por cardType: una tarjeta PREPAID no se descarta de antemano y se acepta o rechaza por elegibilidad como cualquier otra. Debido a que BANK_CARD no tiene una vía de entrega alternativa, mantén siempre BANK_ACH, PAYPAL o VENMO disponibles en tu interfaz para que una tarjeta no elegible no bloquee el flujo. Los fallos de push-to-card aparecen como HN-0124 o BC-0004 — consulta Manejo de errores abajo.

Manejo de errores

Escenarios comunes de error:

Código de error	Descripción
`WDR-0001`	Saldo insuficiente — el usuario no tiene fondos suficientes para completar el retiro.
`WDR-0002`	Monto inválido — el monto es cero o negativo.
`WDR-0003`	Error general de retiro. Revisa el mensaje de error para más detalles.
`WDR-0004`	Método de retiro inválido — usa `PAYPAL`, `BANK_ACH`, `BANK_CARD` o `VENMO`.
`WDR-0005`	Número de teléfono de Venmo inválido. Aplica a retiros `VENMO`.
`WDR-0006`	La cuenta de Venmo ya está vinculada. Aplica a retiros `VENMO`.
`WDR-0007`	Se excedió el límite de retiro del método de pago.
`ARG-0001`	Un argumento requerido es inválido. Pasar `FLUZPAY` a `getWithdrawFeeEstimate` también devuelve este código.
`ARG-0002`	Falta un argumento requerido — `idempotencyKey`, `amount`, `method` o el ID de destino para el método elegido.
`HN-0124`	La tarjeta no es elegible para retiros push-to-card (OCT). Ofrece otro método.
`BC-0004`	La tarjeta fue rechazada. Muestra el mensaje y ofrece otro método.
`G-0004`	Los retiros a tarjeta bancaria no están disponibles temporalmente. Reintenta más tarde o usa otro método.

Los errores ARG-* se generan antes de que se muevan fondos.

Ejemplo de respuesta de error

{
  "errors": [
    {
      "message": "Missing required argument - require idempotencyKey.",
      "extensions": {
        "code": "MISSING_ARGUMENT"
      }
    }
  ]
}

Retiros múltiples

En algunos casos, una sola solicitud de retiro puede resultar en múltiples registros de retiro. Esto puede ocurrir cuando el monto del retiro se divide entre múltiples posiciones (seats) de la red. La respuesta contendrá todos los registros de retiro creados.

{
  "data": {
    "withdrawCashBalance": {
      "withdraws": [
        {
          "withdrawId": "withdraw-1",
          "amount": "75.00",
          "seatId": "seat-1"
        },
        {
          "withdrawId": "withdraw-2",
          "amount": "25.00",
          "seatId": "seat-2"
        }
      ]
    }
  }
}

Mejores prácticas

Usa siempre claves de idempotencia únicas - Genera un UUID nuevo para cada solicitud de retiro para evitar transacciones duplicadas.
Verifica los saldos antes de retirar - Usa la consulta getWallet para confirmar que el usuario tiene fondos suficientes antes de iniciar un retiro.
Maneja estados pendientes - Los retiros pueden tardar en procesarse. El campo status indicará el estado actual del retiro.
Guarda las referencias de transacción - Conserva withdrawId y transactionLogId para conciliación y soporte.

Registro de cambios

v1.3.0

Retiros acelerados y previsualización de comisiones

Se reintrodujo isExpedited en WithdrawCashBalanceInput. Controla la velocidad de entrega para retiros BANK_CARD: true envía a la tarjeta durante la solicitud, false u omitido liquida en el calendario estándar. Esto reemplaza la nota de la v1.2.0 de abajo, que decía que el campo había sido eliminado.
Se añadió la consulta getWithdrawFeeEstimate y los tipos GetWithdrawFeeEstimateInput / WithdrawFeeEstimate, para que las comisiones, el monto neto y los tiempos de liquidación puedan previsualizarse antes de enviar.
Se documentaron los retiros push-to-card como transacciones de crédito originales (OCT), incluyendo la elegibilidad de la tarjeta y el hecho de que un retiro estándar aún puede fallar después de enviado y ser reembolsado al saldo de origen.
Se corrigió el alcance requerido para withdrawCashBalance a MAKE_WITHDRAWAL. El alcance MANAGE_PAYMENT listado previamente en esta página era incorrecto; seat_id en el tipo Withdraw también es opcional (UUID), no requerido como indicaba la v1.2.0.
Se documentó que FLUZPAY, aunque presente en el enum WithdrawMethods, no es un método de retiro utilizable: withdrawCashBalance lo rechaza con WDR-0004 (método de retiro inválido) y getWithdrawFeeEstimate lo rechaza con ARG-0001.

v1.2.0 - 2024-11-20

Ajustes de esquema y limpieza de campos

Se eliminó el campo isExpedited de WithdrawCashBalanceInput - el ACH acelerado ya no es configurable vía la API
Se cambió el campo seat_id en el tipo Withdraw de opcional a requerido (UUID → UUID!)
Se actualizó la descripción para el método BANK_CARD para eliminar la referencia a “acelerado”

v1.1.0 - 2024-10-15

Se agregó soporte de Venmo y retiros del saldo de recompensas

Se agregó VENMO al enum WithdrawMethods
Se agregó el campo venmoAccountId a WithdrawCashBalanceInput
Se agregó REWARDS_BALANCE al enum WithdrawSource para admitir el retiro de ganancias de cashback
Se agregó el campo seat_id al tipo de respuesta Withdraw para el seguimiento en cuentas con múltiples seats

v1.0.0 - 2024-09-01

Lanzamiento inicial

Se introdujo la mutación withdrawCashBalance con el requisito de alcance MAKE_WITHDRAWAL
Se agregó el enum WithdrawMethods con los métodos PAYPAL, BANK_ACH y BANK_CARD
Se agregó el enum WithdrawSource con la fuente CASH_BALANCE
Se agregó el tipo de entrada WithdrawCashBalanceInput con soporte de idempotencia
Se agregó el tipo de respuesta Withdraw con detalles completos del registro de retiro
Se agregó el tipo WithdrawCashBalanceResponse que devuelve los registros de retiro y los saldos actualizados
Integración con payout-service para el procesamiento de retiros
Se agregó el registro de acciones de la aplicación para la auditoría

​Descripción general

​Retirar saldo en efectivo

​Ejemplo de solicitud

​Campos de entrada

​WithdrawCashBalanceInput

​Ejemplo de respuesta

​Campos de la respuesta

​Objeto Withdraw

​Alcance requerido

​Métodos de retiro por tipo de cuenta

​Previsualizar comisiones antes de retirar

​Retiros push-to-card (OCT)

​Elegibilidad de la tarjeta

​Manejo de errores

​Ejemplo de respuesta de error

​Retiros múltiples

​Mejores prácticas

​Registro de cambios

​v1.3.0

​v1.2.0 - 2024-11-20

​v1.1.0 - 2024-10-15

​v1.0.0 - 2024-09-01

Descripción general

Retirar saldo en efectivo

Ejemplo de solicitud

Campos de entrada

WithdrawCashBalanceInput

Ejemplo de respuesta

Campos de la respuesta

Objeto Withdraw

Alcance requerido

Métodos de retiro por tipo de cuenta

Previsualizar comisiones antes de retirar

Retiros push-to-card (OCT)

Elegibilidad de la tarjeta

Manejo de errores

Ejemplo de respuesta de error

Retiros múltiples

Mejores prácticas

Registro de cambios

v1.3.0

v1.2.0 - 2024-11-20

v1.1.0 - 2024-10-15

v1.0.0 - 2024-09-01