提现至外部账户

概览

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

现金余额 - 用户存入其 Fluz 账户的资金
奖励余额 - 购物累计的返现收益

Fluz 支持以下提现方式：

方法	描述
`BANK_ACH`	转账至已关联的银行账户（ACH）
`BANK_CARD`	推送至已关联借记卡的即时到卡转账
`PAYPAL`	转账至已关联的 PayPal 账户
`VENMO`	转账至已关联的 Venmo 账户

提现现金余额

示例请求

你可以使用 withdrawCashBalance mutation 发起提现。该 mutation 会将用户的 Fluz 余额资金转至其指定的外部账户。

{
  "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 输入类型。架构中带有感叹号（!）的任何字段都是必填项，必须包含在请求中。

输入字段

字段名	类型	描述
`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

{
  "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 mutation 的响应包含提现记录以及用户更新后的余额。

{
  "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`	与账户关联的席位 ID。

所需权限范围

此 mutation 需要将 MANAGE_PAYMENT scope 授予访问令牌。

generateUserAccessToken(
  userId: "...",
  accountId: "...",
  scopes: [MANAGE_PAYMENT]
)

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

方法	必填字段	说明
`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`	一般性提现错误。请检查错误消息了解详情。

示例错误响应

{
  "errors": [
    {
      "message": "Missing required argument - require idempotencyKey.",
      "extensions": {
        "code": "MISSING_ARGUMENT"
      }
    }
  ]
}

多笔提现

在某些情况下，一次提现请求可能会产生多条提现记录。当提现金额被拆分到多个席位（网络位置）时会发生这种情况。响应将包含所有创建的提现记录。

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

最佳实践

始终使用唯一的幂等键 - 为每个提现请求生成新的 UUID，防止重复交易。
提现前检查余额 - 使用 getWallet 查询在发起提现前确认用户资金充足。
处理待处理状态 - 提现可能需要一定时间处理。status 字段将指示当前状态。
存储交易引用 - 保存 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 字段，用于多席位账户追踪

v1.0.0 - 2024-09-01

初始发布

引入 withdrawCashBalance mutation，并要求 MAKE_WITHDRAWAL scope
新增 WithdrawMethods 枚举，包含 PAYPAL、BANK_ACH 和 BANK_CARD 方法
新增 WithdrawSource 枚举，包含 CASH_BALANCE 来源
新增具有幂等支持的 WithdrawCashBalanceInput 输入类型
新增包含完整提现记录详情的 Withdraw 响应类型
新增返回提现记录与更新余额的 WithdrawCashBalanceResponse 类型
集成 payout-service 处理提现
新增应用动作日志用于审计追踪

​概览

​提现现金余额

​示例请求

​输入字段

​WithdrawCashBalanceInput

​示例响应

​响应字段

​Withdraw 对象

​所需权限范围

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

​错误处理

​示例错误响应

​多笔提现

​最佳实践

​变更日志

​v1.2.0 - 2024-11-20

​v1.1.0 - 2024-10-15

​v1.0.0 - 2024-09-01

概览