> ## 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. # 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. ```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" } } } ``` 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 ```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" } ``` *** ### Sample Response The response from the `withdrawCashBalance` mutation includes the withdrawal record(s) and the user's updated balances. ```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" } ] } } } ``` ### 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. ```graphql theme={null} 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 ```json theme={null} { "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. ```json theme={null} { "data": { "withdrawCashBalance": { "withdraws": [ { "withdrawId": "withdraw-1", "amount": "75.00", "seatId": "seat-1" }, { "withdrawId": "withdraw-2", "amount": "25.00", "seatId": "seat-2" } ] } } } ``` *** ## Best Practices 1. **Always use unique idempotency keys** - Generate a new UUID for each withdrawal request to prevent duplicate transactions. 2. **Check balances before withdrawing** - Use the `getWallet` query to verify the user has sufficient funds before initiating a withdrawal. 3. **Handle pending states** - Withdrawals may take time to process. The `status` field will indicate the current state of the withdrawal. 4. **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