Withdrawal

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:

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

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

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

Error Handling

Common error scenarios:

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

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