Withdraw to External Account

Overview

A withdrawal allows users to transfer funds from their Fluz balance to an external account. Users can withdraw from two types of balances:

Cash Balance - Funds deposited by the user into their Fluz account
Rewards Balance - Cashback earnings accumulated from purchases

Fluz supports the following withdrawal methods:

Method	Description
`BANK_ACH`	ACH transfer to a linked bank account
`BANK_CARD`	Push-to-card transfer to a linked debit card
`PAYPAL`	Transfer to a linked PayPal account
`VENMO`	Transfer to a linked Venmo account

Withdraw Cash Balance

Sample Request

You can initiate a withdrawal with the withdrawCashBalance mutation. This mutation transfers funds from a user’s Fluz balance to their specified external account.

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

This mutation requires the WithdrawCashBalanceInput input type. Any field marked with an exclamation mark (!) in the schema is mandatory and must be included in the request.

Input Fields

Field Name	Type	Description
`idempotencyKey`	`UUID!`	A unique client-generated UUID to ensure the request is processed only once. This prevents duplicate withdrawals if the same request is sent multiple times.
`amount`	`Float!`	The amount to withdraw. Must be greater than 0.
`method`	`WithdrawMethods!`	The withdrawal method to use. One of: `PAYPAL`, `BANK_ACH`, `BANK_CARD`, `VENMO`.
`source`	`WithdrawSource`	The source balance from which to withdraw funds. One of: `CASH_BALANCE`, `REWARDS_BALANCE`. Defaults to `CASH_BALANCE` if not specified.
`bankAccountId`	`UUID`	Required when `method` is `BANK_ACH`. The identifier of the linked bank account for ACH withdrawals.
`bankCardId`	`UUID`	Required when `method` is `BANK_CARD`. The identifier of the linked debit card for push-to-card withdrawals.
`paypalVaultId`	`UUID`	Required when `method` is `PAYPAL`. The identifier of the linked PayPal account.
`venmoAccountId`	`UUID`	Required when `method` is `VENMO`. The identifier of the linked Venmo account.
`cashBalanceId`	`UUID`	The identifier of the specific cash balance account to withdraw from. Required when `source` is `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"
}

Sample Response

The response from the withdrawCashBalance mutation includes the withdrawal record(s) and the user’s updated balances.

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

Response Fields

Withdraw Object

Field Name	Type	Description
`withdrawId`	`UUID!`	Unique identifier for the withdrawal.
`amount`	`String!`	The amount withdrawn.
`processingFee`	`String!`	Fee charged for processing the withdrawal.
`chargedFee`	`String!`	Fee charged to the user for the withdrawal.
`status`	`String!`	Internal status of the withdrawal (e.g., `PENDING`, `COMPLETED`, `FAILED`).
`displayStatus`	`String!`	User-friendly display status (e.g., `PROCESSING`, `COMPLETE`).
`withdrawMethod`	`WithdrawMethods!`	The withdrawal method used.
`withdrawSource`	`WithdrawSource!`	The source balance from which funds were withdrawn.
`submissionDate`	`DateTime!`	Date and time when the withdrawal was submitted.
`createdAt`	`DateTime!`	Date and time when the withdrawal was created.
`updatedAt`	`DateTime!`	Date and time when the withdrawal was last updated.
`transactionLogId`	`UUID`	Identifier of the associated transaction log.
`externalTransactionId`	`String`	External transaction identifier from payment gateway (for ACH).
`payoutId`	`String`	Payout identifier from payment gateway (for PayPal/Venmo).
`emailAddress`	`String`	Email address associated with the withdrawal.
`bankAccountId`	`UUID`	Identifier of the bank account used (if applicable).
`userCashBalanceId`	`UUID`	Identifier of the user cash balance account withdrawn from.
`seatId`	`UUID`	The seat ID associated with the account.

Required Scope

This mutation requires the MAKE_WITHDRAWAL scope to be granted to the access token.

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

Withdrawal Methods by Account Type

Method	Required Field	Notes
`BANK_ACH`	`bankAccountId`	Standard ACH transfer. Typically settles in 1-3 business days. No fees.
`BANK_CARD`	`bankCardId`	Push-to-card instant transfer. Available for eligible debit cards only. May have fees.
`PAYPAL`	`paypalVaultId`	Transfer to linked PayPal account. May have fees.
`VENMO`	`venmoAccountId`	Transfer to linked Venmo account. May have fees.

Error Handling

Common error scenarios:

Error Code	Description
`MISSING_ARGUMENT`	Required field is missing (e.g., `idempotencyKey`, `amount`, `method`).
`INVALID_AMOUNT`	Amount is zero or negative.
`INSUFFICIENT_FUNDS`	User does not have enough balance to complete the withdrawal.
`WITHDRAW_ERROR`	General withdrawal error. Check the error message for details.

Example Error Response

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

Multiple Withdrawals

In some cases, a single withdrawal request may result in multiple withdrawal records. This can happen when the withdrawal amount is split across multiple seats (network positions). The response will contain all withdrawal records created.

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

Best Practices

Always use unique idempotency keys - Generate a new UUID for each withdrawal request to prevent duplicate transactions.
Check balances before withdrawing - Use the getWallet query to verify the user has sufficient funds before initiating a withdrawal.
Handle pending states - Withdrawals may take time to process. The status field will indicate the current state of the withdrawal.
Store transaction references - Save the withdrawId and transactionLogId for reconciliation and support purposes.

Changelog

v1.2.0 - 2024-11-20

Schema refinements and field cleanup

Removed isExpedited field from WithdrawCashBalanceInput - expedited ACH is no longer configurable via the API
Changed seat_id field on Withdraw type from optional to required (UUID → UUID!)
Updated description for BANK_CARD method to remove “expedited” reference

v1.1.0 - 2024-10-15

Added Venmo support and rewards balance withdrawals

Added VENMO to WithdrawMethods enum
Added venmoAccountId field to WithdrawCashBalanceInput
Added REWARDS_BALANCE to WithdrawSource enum to support withdrawing cashback earnings
Added seat_id field to Withdraw response type for multi-seat account tracking

v1.0.0 - 2024-09-01

Initial release

Introduced withdrawCashBalance mutation with MAKE_WITHDRAWAL scope requirement
Added WithdrawMethods enum with PAYPAL, BANK_ACH, and BANK_CARD methods
Added WithdrawSource enum with CASH_BALANCE source
Added WithdrawCashBalanceInput input type with idempotency support
Added Withdraw response type with full withdrawal record details
Added WithdrawCashBalanceResponse type returning withdrawal records and updated balances
Integrated with payout-service for withdrawal processing
Added application action logging for audit trail

​Overview

​Withdraw Cash Balance

​Sample Request

​Input Fields

​WithdrawCashBalanceInput

​Sample Response

​Response Fields

​Withdraw Object

​Required Scope

​Withdrawal Methods by Account Type

​Error Handling

​Example Error Response

​Multiple Withdrawals

​Best Practices

​Changelog

​v1.2.0 - 2024-11-20

​v1.1.0 - 2024-10-15

​v1.0.0 - 2024-09-01