> ## 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. # Retirar a cuenta externa ## Descripción general Un retiro permite a los usuarios transferir fondos desde su saldo de Fluz a una cuenta externa. Los usuarios pueden retirar de 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 | | `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 del usuario a su cuenta externa especificada. ```json theme={null} { "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 utilizar. 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`. Predetermina a `CASH_BALANCE` si no se especifica. | | `bankAccountId` | `UUID` | Requerido cuando `method` es `BANK_ACH`. El identificador de la cuenta bancaria vinculada para retiros 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 de saldo en efectivo específica desde la cual retirar. Requerido cuando `source` es `CASH_BALANCE`. | ### WithdrawCashBalanceInput ```json theme={null} { "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" } ``` *** ### Ejemplo de respuesta La respuesta de la mutación `withdrawCashBalance` incluye el(los) registro(s) de retiro y los saldos actualizados del usuario. ```json theme={null} { "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!` | Tarifa cobrada por procesar el retiro. | | `chargedFee` | `String!` | Tarifa cobrada al usuario por el retiro. | | `status` | `String!` | Estado interno del retiro (por ejemplo, `PENDING`, `COMPLETED`, `FAILED`). | | `displayStatus` | `String!` | Estado de visualización para el usuario (por ejemplo, `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 envió 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 pasarela de pago (para ACH). | | `payoutId` | `String` | Identificador de pago del pasarela de pago (para PayPal/Venmo). | | `emailAddress` | `String` | Dirección de correo electrónico asociada con el retiro. | | `bankAccountId` | `UUID` | Identificador de la cuenta bancaria utilizada (si corresponde). | | `userCashBalanceId` | `UUID` | Identificador de la cuenta de saldo en efectivo del usuario desde la que se retiró. | | `seatId` | `UUID` | El ID de asiento asociado con la cuenta. | *** ## Alcance requerido Esta mutación requiere que el scope **`MAKE_WITHDRAWAL`** sea otorgado al token de acceso. ```graphql theme={null} 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. Generalmente liquida en 1-3 días hábiles. Sin tarifas. | | `BANK_CARD` | `bankCardId` | Transferencia instantánea push-to-card. Disponible solo para tarjetas de débito elegibles. Puede tener tarifas. | | `PAYPAL` | `paypalVaultId` | Transferencia a una cuenta de PayPal vinculada. Puede tener tarifas. | | `VENMO` | `venmoAccountId` | Transferencia a una cuenta de Venmo vinculada. Puede tener tarifas. | *** ## Manejo de errores Escenarios comunes de error: | Código de error | Descripción | | -------------------- | ------------------------------------------------------------------------------- | | `MISSING_ARGUMENT` | Falta un campo obligatorio (por ejemplo, `idempotencyKey`, `amount`, `method`). | | `INVALID_AMOUNT` | El monto es cero o negativo. | | `INSUFFICIENT_FUNDS` | El usuario no tiene suficiente saldo para completar el retiro. | | `WITHDRAW_ERROR` | Error general de retiro. Revisa el mensaje de error para más detalles. | ### Ejemplo de respuesta de error ```json theme={null} { "errors": [ { "message": "Missing required argument - require idempotencyKey.", "extensions": { "code": "MISSING_ARGUMENT" } } ] } ``` *** ## Retiros múltiples En algunos casos, una sola solicitud de retiro puede dar como resultado múltiples registros de retiro. Esto puede suceder cuando el monto del retiro se divide entre múltiples asientos (posiciones de red). La respuesta contendrá todos los registros de retiro creados. ```json theme={null} { "data": { "withdrawCashBalance": { "withdraws": [ { "withdrawId": "withdraw-1", "amount": "75.00", "seatId": "seat-1" }, { "withdrawId": "withdraw-2", "amount": "25.00", "seatId": "seat-2" } ] } } } ``` *** ## Mejores prácticas 1. **Usa siempre claves de idempotencia únicas** - Genera un nuevo UUID para cada solicitud de retiro y evita transacciones duplicadas. 2. **Verifica los saldos antes de retirar** - Utiliza la consulta `getWallet` para confirmar que el usuario tiene fondos suficientes antes de iniciar un retiro. 3. **Maneja estados pendientes** - Los retiros pueden tardar en procesarse. El campo `status` indicará el estado actual del retiro. 4. **Almacena las referencias de transacción** - Guarda el `withdrawId` y el `transactionLogId` para conciliación y soporte. *** ## Registro de cambios ### v1.2.0 - 2024-11-20 **Ajustes de esquema y limpieza de campos** * Se eliminó el campo `isExpedited` de `WithdrawCashBalanceInput` - el ACH expedito ya no es configurable vía la API * Se cambió el campo `seat_id` en el tipo `Withdraw` de opcional a obligatorio (`UUID` → `UUID!`) * Se actualizó la descripción del método `BANK_CARD` para eliminar la referencia a "expedited" ### v1.1.0 - 2024-10-15 **Se agregó compatibilidad con Venmo y retiros de saldo de recompensas** * Se añadió `VENMO` al enum `WithdrawMethods` * Se añadió el campo `venmoAccountId` a `WithdrawCashBalanceInput` * Se añadió `REWARDS_BALANCE` al enum `WithdrawSource` para permitir retirar ganancias de cashback * Se añadió el campo `seat_id` al tipo de respuesta `Withdraw` para el seguimiento de cuentas con múltiples asientos ### v1.0.0 - 2024-09-01 **Lanzamiento inicial** * Se introdujo la mutación `withdrawCashBalance` con el requisito de scope `MAKE_WITHDRAWAL` * Se añadió el enum `WithdrawMethods` con los métodos `PAYPAL`, `BANK_ACH` y `BANK_CARD` * Se añadió el enum `WithdrawSource` con la fuente `CASH_BALANCE` * Se añadió el tipo de entrada `WithdrawCashBalanceInput` con soporte de idempotencia * Se añadió el tipo de respuesta `Withdraw` con detalles completos del registro de retiro * Se añadió el tipo `WithdrawCashBalanceResponse` que devuelve los registros de retiro y los saldos actualizados * Integrado con payout-service para el procesamiento de retiros * Se añadió el registro de acciones de la aplicación para la auditoría