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 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 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 asegurar que la solicitud se procese solo una vez. Esto previene retiros duplicados si la misma solicitud se envía 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 específica de saldo en efectivo desde la cual retirar. Requerido cuando `source` es `CASH_BALANCE`.

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

Ejemplo de respuesta

La respuesta de la mutación withdrawCashBalance incluye el(los) registro(s) de 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!`	Tarifa cobrada por el procesamiento del 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 los 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 la transacción asociada.
`externalTransactionId`	`String`	Identificador de transacción externo del gateway de pagos (para ACH).
`payoutId`	`String`	Identificador del pago del 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 utilizada (si aplica).
`userCashBalanceId`	`UUID`	Identificador de la cuenta de saldo en efectivo del usuario desde la cual se retiró.
`seatId`	`UUID`	El ID de asiento asociado con la cuenta.

Alcance requerido

Esta mutación requiere que el token de acceso tenga otorgado el alcance MANAGE_PAYMENT.

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

Métodos de retiro por tipo de cuenta

Método	Campo requerido	Notas
`BANK_ACH`	`bankAccountId`	Transferencia ACH estándar. Normalmente se liquida en 1-3 días hábiles. Sin comisiones.
`BANK_CARD`	`bankCardId`	Transferencia instantánea push-to-card. Disponible solo para tarjetas de débito elegibles. Puede tener comisiones.
`PAYPAL`	`paypalVaultId`	Transferencia a la cuenta de PayPal vinculada. Puede tener comisiones.
`VENMO`	`venmoAccountId`	Transferencia a la cuenta de Venmo vinculada. Puede tener comisiones.

Manejo de errores

Escenarios de error comunes:

Código de error	Descripción
`MISSING_ARGUMENT`	Falta un campo requerido (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

{
  "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 suceder cuando el monto de retiro se divide entre varios asientos (posiciones de 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 nuevo UUID para cada solicitud de retiro para prevenir 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.
Almacena las referencias de transacción - Guarda withdrawId y 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 requerido (UUID → UUID!)
Se actualizó la descripción para el 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 agregó VENMO al enum WithdrawMethods
Se agregó el campo venmoAccountId a WithdrawCashBalanceInput
Se agregó REWARDS_BALANCE al enum WithdrawSource para admitir retiros de ganancias de cashback
Se agregó el campo seat_id al tipo de respuesta Withdraw para el seguimiento de cuentas con múltiples asientos

v1.0.0 - 2024-09-01

Versión 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
Integrado con payout-service para el procesamiento de retiros
Se agregó el registro de acciones de la aplicación para la trazabilidad de 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

​Manejo de errores

​Ejemplo de respuesta de error

​Retiros múltiples

​Mejores prácticas

​Registro de cambios

​v1.2.0 - 2024-11-20

​v1.1.0 - 2024-10-15

​v1.0.0 - 2024-09-01