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

# 提領至外部帳戶

## Overview

提領可讓使用者將資金從其 Fluz 餘額轉移到外部帳戶。使用者可以從兩種類型的餘額提領：

* **現金餘額（Cash Balance）** - 使用者存入其 Fluz 帳戶的資金
* **獎勵餘額（Rewards Balance）** - 從消費累積的現金回饋

Fluz 支援以下提領方式：

| Method      | Description       |
| ----------- | ----------------- |
| `BANK_ACH`  | ACH 轉帳至已連結的銀行帳戶   |
| `BANK_CARD` | 推播至卡的轉帳至已連結的金融卡   |
| `PAYPAL`    | 轉帳至已連結的 PayPal 帳戶 |
| `VENMO`     | 轉帳至已連結的 Venmo 帳戶  |

## Withdraw Cash Balance

### Sample Request

你可以使用 `withdrawCashBalance` mutation 來發起提領。此 mutation 會把資金從使用者的 Fluz 餘額轉到其指定的外部帳戶。

```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"
    }
  }
}
```

此 mutation 需要 `WithdrawCashBalanceInput` 輸入型別。結構中以驚嘆號（`!`）標記的欄位為必填，必須包含於請求中。

### Input Fields

| Field Name       | Type               | Description                                                            |
| ---------------- | ------------------ | ---------------------------------------------------------------------- |
| `idempotencyKey` | `UUID!`            | 由客戶端產生的唯一 UUID，以確保請求只被處理一次。當同一請求重複送出時，可避免重複提領。                         |
| `amount`         | `Float!`           | 要提領的金額。必須大於 0。                                                         |
| `method`         | `WithdrawMethods!` | 要使用的提領方式。可為：`PAYPAL`、`BANK_ACH`、`BANK_CARD`、`VENMO`。                   |
| `source`         | `WithdrawSource`   | 要提領資金的來源餘額。可為：`CASH_BALANCE`、`REWARDS_BALANCE`。未指定時預設為 `CASH_BALANCE`。 |
| `bankAccountId`  | `UUID`             | 當 `method` 為 `BANK_ACH` 時必填。ACH 提領所使用的已連結銀行帳戶識別碼。                      |
| `bankCardId`     | `UUID`             | 當 `method` 為 `BANK_CARD` 時必填。推播至卡提領所使用的已連結金融卡識別碼。                      |
| `paypalVaultId`  | `UUID`             | 當 `method` 為 `PAYPAL` 時必填。已連結 PayPal 帳戶的識別碼。                           |
| `venmoAccountId` | `UUID`             | 當 `method` 為 `VENMO` 時必填。已連結 Venmo 帳戶的識別碼。                             |
| `cashBalanceId`  | `UUID`             | 要提領之特定現金餘額帳戶的識別碼。當 `source` 為 `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

`withdrawCashBalance` mutation 的回應包含提領紀錄以及使用者更新後的餘額。

```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!`            | 提領的唯一識別碼。                                   |
| `amount`                | `String!`          | 提領的金額。                                      |
| `processingFee`         | `String!`          | 提領處理費用。                                     |
| `chargedFee`            | `String!`          | 向使用者收取的提領費用。                                |
| `status`                | `String!`          | 提領的內部狀態（例如 `PENDING`、`COMPLETED`、`FAILED`）。 |
| `displayStatus`         | `String!`          | 供使用者查看的狀態（例如 `PROCESSING`、`COMPLETE`）。      |
| `withdrawMethod`        | `WithdrawMethods!` | 所使用的提領方式。                                   |
| `withdrawSource`        | `WithdrawSource!`  | 資金提領的來源餘額。                                  |
| `submissionDate`        | `DateTime!`        | 提領提交的日期與時間。                                 |
| `createdAt`             | `DateTime!`        | 建立提領的日期與時間。                                 |
| `updatedAt`             | `DateTime!`        | 最近更新提領的日期與時間。                               |
| `transactionLogId`      | `UUID`             | 關聯交易紀錄的識別碼。                                 |
| `externalTransactionId` | `String`           | 來自支付閘道的外部交易識別碼（適用於 ACH）。                    |
| `payoutId`              | `String`           | 來自支付閘道的撥款識別碼（適用於 PayPal/Venmo）。             |
| `emailAddress`          | `String`           | 與此提領關聯的電子郵件地址。                              |
| `bankAccountId`         | `UUID`             | 使用的銀行帳戶識別碼（若適用）。                            |
| `userCashBalanceId`     | `UUID`             | 進行提領的使用者現金餘額帳戶識別碼。                          |
| `seatId`                | `UUID`             | 與該帳戶關聯的 seat ID。                            |

***

## Required Scope

此 mutation 需要將 **`MAKE_WITHDRAWAL`** 權限範圍授與存取權杖。

```graphql theme={null}
generateUserAccessToken(
  userId: "...",
  accountId: "...",
  scopes: [MAKE_WITHDRAWAL]
)
```

***

## Withdrawal Methods by Account Type

| Method      | Required Field   | Notes                           |
| ----------- | ---------------- | ------------------------------- |
| `BANK_ACH`  | `bankAccountId`  | 標準 ACH 轉帳。通常於 1-3 個工作天內到帳。無手續費。 |
| `BANK_CARD` | `bankCardId`     | 推播至卡的即時轉帳。僅適用於符合條件的金融卡。可能收取手續費。 |
| `PAYPAL`    | `paypalVaultId`  | 轉帳至已連結的 PayPal 帳戶。可能收取手續費。      |
| `VENMO`     | `venmoAccountId` | 轉帳至已連結的 Venmo 帳戶。可能收取手續費。       |

***

## Error Handling

常見錯誤情境：

| Error Code           | Description                                    |
| -------------------- | ---------------------------------------------- |
| `MISSING_ARGUMENT`   | 缺少必要欄位（例如 `idempotencyKey`、`amount`、`method`）。 |
| `INVALID_AMOUNT`     | 金額為 0 或負數。                                     |
| `INSUFFICIENT_FUNDS` | 使用者餘額不足，無法完成提領。                                |
| `WITHDRAW_ERROR`     | 一般提領錯誤。請查看錯誤訊息以取得詳細資訊。                         |

### Example Error Response

```json theme={null}
{
  "errors": [
    {
      "message": "Missing required argument - require idempotencyKey.",
      "extensions": {
        "code": "MISSING_ARGUMENT"
      }
    }
  ]
}
```

***

## Multiple Withdrawals

在某些情況下，單一提領請求可能會產生多筆提領紀錄。當提領金額分散到多個 seats（網路位置）時，會出現此情況。回應會包含所有建立的提領紀錄。

```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. **一律使用唯一的冪等鍵（idempotency keys）** - 為每次提領請求產生新的 UUID，以防止重複交易。
2. **提領前先檢查餘額** - 使用 `getWallet` 查詢在發起提領前確認使用者有足夠資金。
3. **處理待處理狀態** - 提領可能需要時間處理。`status` 欄位會指出目前的處理狀態。
4. **儲存交易參考** - 保留 `withdrawId` 與 `transactionLogId` 以便對帳與客服支援。

***

## Changelog

### v1.2.0 - 2024-11-20

**結構優化與欄位清理**

* 從 `WithdrawCashBalanceInput` 移除 `isExpedited` 欄位 —— 已不再可透過 API 設定加速 ACH
* `Withdraw` 型別中的 `seat_id` 欄位由選填改為必填（`UUID` → `UUID!`）
* 更新 `BANK_CARD` 方法的說明，移除「加速」相關敘述

### v1.1.0 - 2024-10-15

**新增 Venmo 支援與獎勵餘額提領**

* 在 `WithdrawMethods` 列舉中新增 `VENMO`
* 在 `WithdrawCashBalanceInput` 新增 `venmoAccountId` 欄位
* 在 `WithdrawSource` 列舉中新增 `REWARDS_BALANCE` 以支援提領現金回饋
* 在 `Withdraw` 回應型別中新增 `seat_id` 欄位，以支援多 seat 帳戶追蹤

### v1.0.0 - 2024-09-01

**初始版本**

* 新增 `withdrawCashBalance` mutation，需具備 `MAKE_WITHDRAWAL` 權限範圍
* 新增含 `PAYPAL`、`BANK_ACH`、`BANK_CARD` 方法的 `WithdrawMethods` 列舉
* 新增 `WithdrawSource` 列舉並包含 `CASH_BALANCE` 來源
* 新增支援冪等的 `WithdrawCashBalanceInput` 輸入型別
* 新增具完整提領紀錄細節的 `Withdraw` 回應型別
* 新增回傳提領紀錄與更新餘額的 `WithdrawCashBalanceResponse` 型別
* 整合 payout-service 以處理提領
* 新增應用程式動作記錄以供稽核追蹤