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, delivered as an original credit transaction (OCT)
`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`.
`isExpedited`	`Boolean`	If `true`, the withdrawal is processed immediately. If `false` or omitted, it is processed on a standard settlement schedule. Currently applies to `BANK_CARD` withdrawals, and the two speeds are priced differently — preview with `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
}

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. The getWithdrawFeeEstimate query requires the same scope.

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 transfer, delivered as an original credit transaction (OCT). Available for eligible debit cards only. Set `isExpedited: true` for immediate delivery, or omit it to settle on the standard schedule. May have fees.
`PAYPAL`	`paypalVaultId`	Transfer to linked PayPal account. May have fees.
`VENMO`	`venmoAccountId`	Transfer to linked Venmo account. May have fees.

Preview Fees Before Withdrawing

Use the getWithdrawFeeEstimate query to quote a withdrawal before you submit it. Pass the same amount, method, source, and isExpedited you intend to send, and the response tells you exactly what the user will receive.

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

Field Name	Type	Description
`fee`	`Float!`	The fee that will be charged for this withdrawal.
`netAmount`	`Float!`	The amount the user will actually receive, after fees.
`feePercent`	`Float!`	The fee percentage applied.
`feeMaxCap`	`Float`	The maximum fee cap in dollars, if one applies.
`settlementDelayDays`	`Int`	Business days until settlement. `null` for expedited withdrawals that settle immediately.

The fee is deducted from the withdrawal rather than added on top: the balance is debited the full amount, and the destination receives netAmount. Passing FLUZPAY as method returns ARG-0001.

Push-to-Card Withdrawals (OCT)

A BANK_CARD withdrawal is a push-to-card payout, delivered as an original credit transaction (OCT) — the card-network transaction type for crediting funds to a card. It requires bankCardId, and the linked debit card must support OCT. An ineligible card cannot be delivered to by any other means, so the user has to pick a different withdrawal method. Delivery speed is controlled by isExpedited:

`isExpedited`	Behavior
`true`	Funds are pushed to the card during the request.
`false` or omitted	The withdrawal is recorded as `PENDING` and released after `settlementDelayDays` business days.

A PENDING push-to-card withdrawal is not yet final.A standard withdrawal is delivered to the card after the settlement delay, and it can still fail at that point — for example if the card is no longer able to receive the payout. When it does, the funds are credited back to the source balance. Reconcile withdrawal status instead of treating the initial PENDING response as a completed payout.

Card Eligibility

Most Visa and Mastercard debit cards can receive a push-to-card payout. Eligibility is evaluated when the withdrawal is submitted, and is a property of the card itself rather than something you configure.

Eligibility is not available in advance, and does not carry over from deposits.There is no query that reports whether a card supports OCT — it surfaces on the first withdrawal to that card. Withdrawal and deposit eligibility are also independent, so a card a user successfully deposited from is not necessarily a card you can send a withdrawal to. See Deposit From External Accounts.

BANK_CARD withdrawals are not restricted by cardType: a PREPAID card is not ruled out up front, and is accepted or declined on eligibility like any other card. Because BANK_CARD has no alternative delivery path, always keep BANK_ACH, PAYPAL, or VENMO reachable in your UI so an ineligible card does not dead-end the flow. Push-to-card failures surface as HN-0124 or BC-0004 — see Error Handling below.

Error Handling

Common error scenarios:

Error Code	Description
`WDR-0001`	Insufficient balance — the user does not have enough funds to complete the withdrawal.
`WDR-0002`	Invalid amount — the amount is zero or negative.
`WDR-0003`	General withdrawal error. Check the error message for details.
`WDR-0004`	Invalid withdrawal method — use `PAYPAL`, `BANK_ACH`, `BANK_CARD`, or `VENMO`.
`WDR-0005`	Invalid Venmo phone number. Applies to `VENMO` withdrawals.
`WDR-0006`	The Venmo account is already linked. Applies to `VENMO` withdrawals.
`WDR-0007`	The payment method’s withdrawal limit has been exceeded.
`ARG-0001`	A required argument is invalid. Passing `FLUZPAY` to `getWithdrawFeeEstimate` also returns this code.
`ARG-0002`	A required argument is missing — `idempotencyKey`, `amount`, `method`, or the destination ID for the chosen method.
`HN-0124`	The card is not eligible for push-to-card (OCT) withdrawals. Offer another method.
`BC-0004`	The card was declined. Surface the message and offer another method.
`G-0004`	Bank card withdrawals are temporarily unavailable. Retry later or fall back to another method.

ARG-* errors are raised before any funds move.

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.3.0

Expedited withdrawals and fee previews

Reintroduced isExpedited on WithdrawCashBalanceInput. It controls delivery speed for BANK_CARD withdrawals: true pushes to the card during the request, false or omitted settles on the standard schedule. This supersedes the v1.2.0 note below, which said the field had been removed.
Added the getWithdrawFeeEstimate query and the GetWithdrawFeeEstimateInput / WithdrawFeeEstimate types, so fees, net amount, and settlement timing can be previewed before submitting.
Documented push-to-card withdrawals as original credit transactions (OCT), including card eligibility and the fact that a standard withdrawal can still fail after it is submitted and be refunded to the source balance.
Corrected the required scope for withdrawCashBalance to MAKE_WITHDRAWAL. The MANAGE_PAYMENT scope previously listed on this page was wrong; seat_id on the Withdraw type is also optional (UUID), not required as v1.2.0 stated.
Documented that FLUZPAY, though present on the WithdrawMethods enum, is not a usable withdrawal method: withdrawCashBalance rejects it with WDR-0004 (invalid withdrawal method), and getWithdrawFeeEstimate rejects it with ARG-0001.

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

​Preview Fees Before Withdrawing

​Push-to-Card Withdrawals (OCT)

​Card Eligibility

​Error Handling

​Example Error Response

​Multiple Withdrawals

​Best Practices

​Changelog

​v1.3.0

​v1.2.0 - 2024-11-20

​v1.1.0 - 2024-10-15

​v1.0.0 - 2024-09-01

Overview

Withdraw Cash Balance

Sample Request

Input Fields

WithdrawCashBalanceInput

Sample Response

Response Fields

Withdraw Object

Required Scope

Withdrawal Methods by Account Type

Preview Fees Before Withdrawing

Push-to-Card Withdrawals (OCT)

Card Eligibility

Error Handling

Example Error Response

Multiple Withdrawals

Best Practices

Changelog

v1.3.0

v1.2.0 - 2024-11-20

v1.1.0 - 2024-10-15

v1.0.0 - 2024-09-01