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

# 从外部账户存款

depositCashBalance

当你准备将资金转入你的 Fluz 账户时，你可以将资金存入以下三个余额之一：

1. **现金余额** - 常规现金余额存款。
2. **礼品卡余额** - 用于礼品卡余额的不可提现存款。
3. **预留余额** - 存入预留余额的存款。

# 发起存款

要将资金存入你的某个 Fluz 余额，请使用 `depositCashBalance` [mutation](https://storage.googleapis.com/fluz-public-docs/api-reference.html#mutation-depositCashBalance)。该 mutation 接受 `DepositCashBalanceInput` 输入对象类型，你可以在其中指定以下详细信息：

1. **金额：** **必填** - 你希望存入的金额。
2. **idempotencyKey：** **必填** - 由客户端生成的唯一 UUID，确保请求只被处理一次。
3. **资金来源：** 进行存款所用的支付方式（例如，银行账户、信用卡或借记卡、PayPal）。要获取你的资金来源 ID，请使用 `getWallet` [query](https://storage.googleapis.com/fluz-public-docs/api-reference.html#query-getWallet)。
   1. **`bankAccountId`** - 如果你想用银行账户付款，请在 `depositCashBalance` mutation 中设置银行账户 ID。
   2. **`bankCardId`** - 如果你想用银行卡付款，请在 `depositCashBalance` mutation 中设置银行卡 ID。
   3. **`paypalVaultID`** - 如果你想用 PayPal 账户付款，请在 `depositCashBalance` mutation 中设置 PayPal 账户 ID。
4. **存款目标：** 你希望将资金存入的余额。可用选项在 `CashBalanceDepositType` 枚举中定义：
   1. **`CASH_BALANCE`**
   2. **`GIFT_CARD_BALANCE`**
   3. **`RESERVE_BALANCE`**
5. **商户类别代码：** 仅适用于 **GIFT\_CARD\_BALANCE**。用于按照所提供的产品或服务类型对企业进行分类的四位数字。使用 `getMccList` 获取有效 MCC 列表。
6. **`userCashBalanceId`** - 如果选择了 `CASH_BALANCE`，你可以指定要存入资金的现金余额（消费账户）。
7. *`memo`*\* - 如果你想为该交易附加备注，请在此处提供自由文本备注。最多 255 个字符。
8. **`transactionCategory`** - 如果你想为该交易分类，请提供一个类别名称。类别会在首次使用时自动创建，并在再次传入相同名称时复用。
9. **`attachmentId`** - 如果你想为该交易附加文件，请提供上传端点返回的 ID。参见 [添加费用明细](/features/add-expense-details)。📘 有关上传附件以及使用备注和类别的完整详情，请参见 [添加费用明细](/features/add-expense-details)。

## 示例请求

```graphql graphql theme={null}
mutation depositCashBalance($input: DepositCashBalanceInput!) {
  depositCashBalance(input: $input) {
    cashBalanceDeposits {
      ...CashBalanceDepositFragment
    }
    balances {
      ...UserBalancesFragment
    }
  }
}
```

## DepositCashBalanceInput

```json theme={null}
{
  "idempotencyKey": "0284be6f-1a69-44f7-9da0-5b5edaf45d19",
  "amount": 987.65,
  "depositType": "GIFT_CARD_BALANCE",
  "merchantCategoryCode": 1234,
  "bankAccountId": "0284be6f-1a69-44f7-9da0-5b5edaf45d19",
  "bankCardId": "0284be6f-1a69-44f7-9da0-5b5edaf45d19",
  "paypalVaultId": "0284be6f-1a69-44f7-9da0-5b5edaf45d19",
  "userCashBalanceId": "0347ade-2b69-55e6-4db0-5b5daddf45d22"
}
```

## 示例响应

```json theme={null}
{
  "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",
        }
      }
    }
  }
}
```

# 存款响应

使用 `depositCashBalance` [mutation](https://storage.googleapis.com/fluz-public-docs/api-reference.html#mutation-depositCashBalance) 发起存款后，你将收到包含该笔存款详情的响应。

| 字段名称                | 类型                    | 说明                               |
| :------------------ | :-------------------- | :------------------------------- |
| cashBalanceDeposits | \[CashBalanceDeposit] | 作为该 mutation 一部分所进行的现金余额存款列表。    |
| balances            | UserBalances          | 用户当前的余额，包括现金余额、奖励余额和 Fluz 预付款余额。 |

`CashBalanceDeposit` 对象将包含你所发起存款的重要信息。

| 字段名称                   | 类型                        | 说明                                                                   |
| :--------------------- | :------------------------ | :------------------------------------------------------------------- |
| cashBalanceDepositId   | UUID!                     | 现金余额存款的唯一标识符。                                                        |
| depositDisplayId       | String!                   | 面向用户展示的存款显示标识符。                                                      |
| depositAmount          | String!                   | 存款金额。                                                                |
| depositFee             | String                    | 与存款相关的费用（如适用）。                                                       |
| bankCardId             | UUID                      | 用于存款的银行卡标识符。                                                         |
| bankAccountId          | UUID                      | 用于存款的银行账户标识符。                                                        |
| paypalVaultId          | UUID                      | 用于存款的 PayPal vault 标识符。                                              |
| transactionDate        | DateTime!                 | 进行该交易的日期和时间。                                                         |
| clearedDate            | DateTime                  | 存款清算完成的日期和时间（如适用）。                                                   |
| status                 | CashBalanceDepositStatus! | 存款当前状态。                                                              |
| expectedClearedDate    | DateTime!                 | 该笔存款预计清算完成的日期和时间。                                                    |
| cashBalanceDepositType | CashBalanceDepositType!   | 现金余额存款类型，包括 `CASH_BALANCE`,`GIFT_CARD_PREPAYMENT`,`RESERVE_BALANCE`。 |
| cashBalanceSettlements | \[CashBalanceSettlement]  | 存款的结算时间详情，包括状态与类型。                                                   |

> 📘 请注意
>
> 存款可能会即时结算，或在 2-5 个工作日内结算。要了解结算时间如何计算，[阅读这篇文章。](https://help.fluz.app/en/articles/5773275-instant-access)

<br />

<StickyContactSalesBanner />