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

# 提现到外部账户

## 概览

提现允许用户将资金从其 Fluz 余额转至外部账户。用户可以从两种类型的余额中提现：

* **现金余额（Cash Balance）** - 用户存入其 Fluz 账户的资金
* **奖励余额（Rewards Balance）** - 购物获得累计的返现

Fluz 支持以下提现方式：

| 方法          | 说明                |
| ----------- | ----------------- |
| `BANK_ACH`  | 转至已绑定银行账户的 ACH 转账 |
| `BANK_CARD` | 推送到已绑定借记卡的即时到卡转账  |
| `PAYPAL`    | 转至已绑定的 PayPal 账户  |
| `VENMO`     | 转至已绑定的 Venmo 账户   |

## 提现现金余额

### 示例请求

你可以使用 `withdrawCashBalance` 变更发起提现。该变更会将资金从用户的 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"
    }
  }
}
```

该变更需要 `WithdrawCashBalanceInput` 输入类型。架构中带有感叹号（`!`）的任何字段都是必填项，必须包含在请求中。

### 输入字段

| 字段名              | 类型                 | 说明                                                                     |
| ---------------- | ------------------ | ---------------------------------------------------------------------- |
| `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"
}
```

***

### 示例响应

`withdrawCashBalance` 变更的响应包含提现记录以及用户更新后的余额。

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

### 响应字段

#### Withdraw 对象

| 字段名                     | 类型                 | 说明                                          |
| ----------------------- | ------------------ | ------------------------------------------- |
| `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。                             |

***

## 必需的 Scope

该变更需要在访问令牌上授予 **`MAKE_WITHDRAWAL`** scope。

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

***

## 按账户类型划分的提现方式

| 方法          | 必填字段             | 备注                             |
| ----------- | ---------------- | ------------------------------ |
| `BANK_ACH`  | `bankAccountId`  | 标准 ACH 转账。通常在 1-3 个工作日内结算。无费用。 |
| `BANK_CARD` | `bankCardId`     | 推送到卡的即时转账。仅适用于符合条件的借记卡。可能产生费用。 |
| `PAYPAL`    | `paypalVaultId`  | 转至已绑定的 PayPal 账户。可能产生费用。       |
| `VENMO`     | `venmoAccountId` | 转至已绑定的 Venmo 账户。可能产生费用。        |

***

## 错误处理

常见错误场景：

| 错误码                  | 说明                                             |
| -------------------- | ---------------------------------------------- |
| `MISSING_ARGUMENT`   | 缺少必填字段（例如，`idempotencyKey`、`amount`、`method`）。 |
| `INVALID_AMOUNT`     | 金额为零或为负数。                                      |
| `INSUFFICIENT_FUNDS` | 用户余额不足，无法完成提现。                                 |
| `WITHDRAW_ERROR`     | 通用提现错误。请检查错误消息了解详情。                            |

### 错误响应示例

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

***

## 多笔提现记录

在某些情况下，单次提现请求可能会产生多条提现记录。当提现金额需要在多个 seat（网络位置）之间拆分时，就会出现这种情况。响应将包含所有创建的提现记录。

```json theme={null}
{
  "data": {
    "withdrawCashBalance": {
      "withdraws": [
        {
          "withdrawId": "withdraw-1",
          "amount": "75.00",
          "seatId": "seat-1"
        },
        {
          "withdrawId": "withdraw-2", 
          "amount": "25.00",
          "seatId": "seat-2"
        }
      ]
    }
  }
}
```

***

## 最佳实践

1. 始终使用唯一的幂等键 - 为每个提现请求生成新的 UUID，以防止重复交易。
2. 提现前检查余额 - 使用 `getWallet` 查询在发起提现前验证用户是否有足够资金。
3. 处理待处理状态 - 提现可能需要时间处理。`status` 字段会指示提现的当前状态。
4. 存储交易引用 - 保存 `withdrawId` 和 `transactionLogId`，用于对账与客服支持。

***

## 更新日志

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

**架构优化与字段清理**

* 从 `WithdrawCashBalanceInput` 中移除 `isExpedited` 字段 - 加急 ACH 不再通过 API 配置
* 将 `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` 变更，并要求具备 `MAKE_WITHDRAWAL` scope
* 添加包含 `PAYPAL`、`BANK_ACH` 和 `BANK_CARD` 方法的 `WithdrawMethods` 枚举
* 添加带有 `CASH_BALANCE` 来源的 `WithdrawSource` 枚举
* 添加支持幂等的 `WithdrawCashBalanceInput` 输入类型
* 添加包含完整提现记录详情的 `Withdraw` 响应类型
* 添加返回提现记录与更新后余额的 `WithdrawCashBalanceResponse` 类型
* 集成 payout-service 以进行提现处理
* 添加应用操作日志记录以提供审计追踪