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.

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

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

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

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

{
  "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 y evita transacciones duplicadas.
Verifica los saldos antes de retirar - Utiliza 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 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

​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