depositCashBalance When you’re ready to move money into your Fluz account, you can deposit funds into the following three balances:

Cash balance- A regular cash balance deposit.
Gift card balance- A non-withdrawable deposit for gift card balance.
Reserve balance - A deposit held in reserve balance.

Make a Deposit

Deposits require the MAKE_DEPOSIT scope on the access token. To deposit funds into one of your Fluz balances, use the depositCashBalance mutation. This mutation accepts an input object type of DepositCashBalanceInput, which allows you to specify the following details:

Amount: Required - The amount you wish to deposit.
idempotencyKey: Required - A unique client-generated UUID to ensure a request is processed only once.
Funding Source: The payment method from which the deposit will be made (e.g., bank account, credit or debit card, PayPal). In order to get your funding source’s ID, use the getWallet query.
1. bankAccountId - If you want to pay with a bank account, define the bank account ID in the depositCashBalance mutation.
2. bankCardId - If you want to pay with a bank card, define the bank card ID in the depositCashBalance mutation.
3. paypalVaultID - If you want to pay with a PayPal account, define the PayPal account ID in the depositCashBalance mutation.
Deposit Destination: The balance where you want to deposit your funds. The available options for this are defined in the CashBalanceDepositType enumerator:
1. CASH_BALANCE
2. GIFT_CARD_BALANCE
3. RESERVE_BALANCE
Merchant Category Code: Only applies for GIFT_CARD_BALANCE. A four-digit number that classifies a business by the type of products or services it offers. Use getMccList to retrieve a list of valid MCCs.
userCashBalanceId - If CASH_BALANCEis selected, you can specify the cash balance (spend account) to deposit your funds
memo* - If you want to attach a note to this transaction, provide a free-text memo here. Max 255 characters.
transactionCategory - If you want to categorize this transaction, provide a category name. Categories are created automatically on first use and reused if the same name is passed again.
attachmentId - If you want to attach a file to this transaction, provide the ID returned by the upload endpoint. See Add Expense Details. 📘 See Add Expense Details for full details on uploading attachments and working with memos and categories.

Sample Request

graphql

mutation depositCashBalance($input: DepositCashBalanceInput!) {
  depositCashBalance(input: $input) {
    cashBalanceDeposits {
      ...CashBalanceDepositFragment
    }
    balances {
      ...UserBalancesFragment
    }
  }
}

DepositCashBalanceInput

{
  "idempotencyKey": "0284be6f-1a69-44f7-9da0-5b5edaf45d19",
  "amount": 987.65,
  "depositType": "GIFT_CARD_BALANCE",
  "merchantCategoryCode": 1234,
  "bankAccountId": "0285c162-fb2f-4c32-b076-29166471f570",
  "bankCardId": "0284be6f-1a69-44f7-9da0-5b5edaf45d19",
  "paypalVaultId": "0284be6f-1a69-44f7-9da0-5b5edaf45d19",
  "userCashBalanceId": "0347adef-2b69-45e6-8db0-5b5daddf45d2"
}

Sample Response

{
  "data": {
    "depositCashBalance": {
      "cashBalanceDeposits": [
        {
          "cashBalanceDepositId": "5f5c5b5f-4c4b-4e4e-9e9e-4f4f4f4f4f4f",
          "depositDisplayId": "102370",
          "depositAmount": "100.00",
          "depositFee": "2.00",
          "bankAccountId": "b2c3d4e5-f6a7-890b-c12d-34ef5678gh90",
          "transactionDate": "2024-08-21T10:30:00Z",
          "clearedDate": "2024-08-22T12:00:00Z",
          "status": "COMPLETED",
          "expectedClearedDate": "2024-08-22T12:00:00Z",
          "cashBalanceDepositType": "CASH_BALANCE",
          "cashBalanceSettlements": [
            {
              "cashBalanceSettlementId": "255f8245-02c7-4817-901e-15fe265f6968",
              "cashBalanceDepositId": "255f8245-02c7-4817-901e-15fe265f6968",
              "availabilityType": "INSTANT",
              "status": "AVAILABLE"
            }
          ]
        }
      ],
      "balances": {
        "cashBalance": {
          "availableBalance": "25.00",
          "totalBalance": "25.00",
          "pendingBalance": "25.00",
          "lifetimeBalance": "25.00",
        },
        "rewardBalance": {
          "availableBalance": "25.00",
          "totalBalance": "25.00",
          "lifetimeBalance": "25.00",
        },
        "giftCardCashBalance": {
          "availableBalance": "25.00",
          "totalBalance": "25.00",
          "pendingBalance": "25.00",
          "lifetimeBalance": "25.00",
        }
      }
    }
  }
}

Debit Card Deposits

A deposit funded by a debit card may be processed as an account funding transaction (AFT) — a card-network transaction type designed for moving funds into an account. Fluz applies it automatically where it is available; there is no field to request it. What it changes for you is the fee. AFT applies only when all of the following hold:

The funding source is a bankCardId, and the card’s cardType is DEBIT.
depositType is CASH_BALANCE. Deposits to GIFT_CARD_BALANCE and RESERVE_BALANCE never use AFT.
The card is AFT-eligible.

CREDIT and PREPAID bank cards never use AFT, and neither do bank accounts (bankAccountId) or PayPal (paypalVaultId). They are charged the standard rate for their payment method — this is a normal outcome, not an error.

Fees on Debit Card Deposits

AFT-eligible cards are charged an AFT-specific rate. Cards that are not AFT-eligible are charged the standard debit-card rate instead — this is a normal outcome, not an error. Because the two rates differ, read depositFee from the response instead of computing the fee client-side.

Card Eligibility

Whether a card supports AFT is a property of the card itself rather than something you configure. Eligibility is evaluated when the deposit is submitted.

Eligibility is not available in advance, and does not carry over to withdrawals.There is no query that reports whether a card supports AFT — it is reflected in the fee on the first deposit from that card. Deposit and withdrawal eligibility are also independent, so a card a user can deposit from is not necessarily a card you can send a withdrawal to. See Withdraw to External Account.

Handle these decline codes on debit-card deposits:

Code	Meaning	What to do
`HN-0125`	This card is not eligible for account funding (AFT) transfers.	Ask the user for a different funding source.
`PG-0003`	The deposit could not be processed for this card right now.	Retry later, or fall back to another funding source.
`BC-0004`	The card was declined by the issuer.	Surface the message; the user should contact their bank or try another card.

Keep an alternative funding source reachable in your UI so an ineligible or declined card does not dead-end the flow.

Deposit Response

Once you initiate a deposit with the depositCashBalance mutation, you will get a response providing details about the deposit.

Field Name	Type	Description
cashBalanceDeposits	[CashBalanceDeposit]	List of cash balance deposits made as part of the mutation.
balances	UserBalances	The current balances for the user, including cash balance, rewards balance, and Fluz prepayment balance.

The CashBalanceDeposit object will contain important information about the deposit you initiated.

Field Name	Type	Description
cashBalanceDepositId	UUID!	Unique identifier for the cash balance deposit.
depositDisplayId	String!	Display identifier for the deposit, intended for user-facing purposes.
depositAmount	String!	The amount of the deposit.
depositFee	String	Fee associated with the deposit, if applicable.
bankCardId	UUID	Identifier of the bank card used for the deposit.
bankAccountId	UUID	Identifier of the bank account used for the deposit.
paypalVaultId	UUID	Identifier of the PayPal vault used for the deposit.
transactionDate	DateTime!	Date and time when the transaction was made.
clearedDate	DateTime	Date and time when the deposit cleared, if applicable.
status	CashBalanceDepositStatus!	Current status of the deposit.
expectedClearedDate	DateTime!	Expected date and time for the deposit to clear.
cashBalanceDepositType	CashBalanceDepositType!	Type of the cash balance deposit: `CASH_BALANCE`, `GIFT_CARD_BALANCE`, or `RESERVE_BALANCE`.
cashBalanceSettlements	[CashBalanceSettlement]	Settlement time details for the deposit, including status and type.

📘 Please note Deposits may settle instantly or within 2-5 business days. To learn how settlement times are calculated, read this article.

Features

Deposit From External Accounts

Make a Deposit

Sample Request

DepositCashBalanceInput

Sample Response

Debit Card Deposits

Fees on Debit Card Deposits

Card Eligibility

Deposit Response

​Make a Deposit

​Sample Request

​DepositCashBalanceInput

​Sample Response

​Debit Card Deposits

​Fees on Debit Card Deposits

​Card Eligibility

​Deposit Response

Make a Deposit

Sample Request

DepositCashBalanceInput

Sample Response

Debit Card Deposits

Fees on Debit Card Deposits

Card Eligibility

Deposit Response