> ## 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. **Amount：** **必填** - 你希望存入的金額。
2. **idempotencyKey：** **必填** - 用戶端產生的唯一 UUID，確保請求只被處理一次。
3. **資金來源 (Funding Source)：** 進行存款所使用的付款方式（例如：銀行帳戶、信用卡或簽帳卡、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. **存款目的地 (Deposit Destination)：** 你希望將資金存入的餘額。可用選項定義於 `CashBalanceDepositType` 列舉：
   1. **`CASH_BALANCE`**
   2. **`GIFT_CARD_BALANCE`**
   3. **`RESERVE_BALANCE`**
5. **商家類別代碼 (Merchant Category Code)：** 僅適用於 **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 />