提现至外部账户

概览

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

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

Fluz 支持以下提现方式：

Method	Description
`BANK_ACH`	通过 ACH 转账至已绑定的银行账户
`BANK_CARD`	通过原始贷记交易（OCT）推送到已绑定的借记卡
`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 输入类型。架构中带感叹号（!）的字段为必填，必须在请求中提供。

输入字段

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` 时必填。
`isExpedited`	`Boolean`	若为 `true`，则立即处理提现。若为 `false` 或省略，则按标准结算进度处理。目前适用于 `BANK_CARD` 提现，两种速度的费用不同 — 可用 `getWithdrawFeeEstimate` 进行预估。

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",
  "isExpedited": false
}

示例响应

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 对象

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

必需的 Scope

此 mutation 需要将 MAKE_WITHDRAWAL scope 授予访问令牌。getWithdrawFeeEstimate 查询同样需要该 scope。

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

各账户类型的提现方式

Method	Required Field	Notes
`BANK_ACH`	`bankAccountId`	标准 ACH 转账。通常在 1-3 个工作日内结算。无费用。
`BANK_CARD`	`bankCardId`	推卡提现，以原始贷记交易（OCT）方式入账。仅适用于符合条件的借记卡。将 `isExpedited: true` 设置为即时到账，或省略以按标准进度结算。可能产生费用。
`PAYPAL`	`paypalVaultId`	转账至已绑定的 PayPal 账户。可能产生费用。
`VENMO`	`venmoAccountId`	转账至已绑定的 Venmo 账户。可能产生费用。

提现前预览费用

使用 getWithdrawFeeEstimate 查询在提交前对提现进行报价。传入你计划使用的相同 amount、method、source 和 isExpedited，响应会精确告知用户将实际收到的金额。

{
  "query": "query getWithdrawFeeEstimate($input: GetWithdrawFeeEstimateInput!) { getWithdrawFeeEstimate(input: $input) { fee netAmount feePercent feeMaxCap settlementDelayDays } }",
  "variables": {
    "input": {
      "amount": 100.00,
      "method": "BANK_CARD",
      "source": "CASH_BALANCE",
      "isExpedited": true
    }
  }
}

Field Name	Type	Description
`fee`	`Float!`	此次提现将收取的费用。
`netAmount`	`Float!`	扣除费用后用户实际可收到的金额。
`feePercent`	`Float!`	适用的费率百分比。
`feeMaxCap`	`Float`	若适用，以美元计的手续费上限。
`settlementDelayDays`	`Int`	至结算的工作日天数。对立即结算的加急提现为 `null`。

费用从提现金额中扣除，而非额外叠加：余额会扣减完整的 amount，目的账户收到 netAmount。将 FLUZPAY 作为 method 传入会返回 ARG-0001。

推卡提现（OCT）

BANK_CARD 提现是推卡付款，以**原始贷记交易（OCT）**的卡网络交易类型将资金打到卡上。它需要 bankCardId，且绑定的借记卡必须支持 OCT。不符合条件的卡无法通过其他方式入账，用户需选择其他提现方式。 isExpedited 控制到账速度：

`isExpedited`	Behavior
`true`	在请求期间将资金推送至该卡。
`false` 或省略	提现会记录为 `PENDING`，并在 `settlementDelayDays` 个工作日后释放。

处于 PENDING 的推卡提现尚未最终完成。标准提现会在结算延迟后入账，但届时仍可能失败——例如该卡已无法接收该笔付款。若失败，资金将退回至来源余额。请对提现状态进行对账，而不要将初始的 PENDING 响应视为已完成的付款。

卡片可用性

大多数 Visa 与 Mastercard 借记卡均可接收推卡付款。可用性会在提交提现时评估，这是卡片本身的属性，并非可由你配置。

可用性无法提前获知，且与存款的可用性不互通。没有可查询卡片是否支持 OCT 的接口——它只会在对该卡首次提现时显现。提现与存款的可用性相互独立，因此用户成功用于存款的卡片，并不一定可用于接收提现。参见从外部账户存款。

BANK_CARD 提现不受 cardType 限制：PREPAID 卡不会被预先排除，与其他卡一样基于可用性决定接受或拒绝。由于 BANK_CARD 没有替代的交付路径，请务必在你的界面中保持 BANK_ACH、PAYPAL 或 VENMO 可选，以防不合格卡片导致流程中断。推卡失败会表现为 HN-0124 或 BC-0004 —— 见下方的错误处理。

错误处理

常见错误场景：

Error Code	Description
`WDR-0001`	余额不足——用户资金不足以完成提现。
`WDR-0002`	金额无效——金额为零或负数。
`WDR-0003`	通用提现错误。请检查错误信息了解详情。
`WDR-0004`	提现方式无效——请使用 `PAYPAL`、`BANK_ACH`、`BANK_CARD` 或 `VENMO`。
`WDR-0005`	Venmo 手机号码无效。适用于 `VENMO` 提现。
`WDR-0006`	该 Venmo 账户已绑定。适用于 `VENMO` 提现。
`WDR-0007`	支付方式的提现限额已超出。
`ARG-0001`	必填参数无效。向 `getWithdrawFeeEstimate` 传入 `FLUZPAY` 也会返回该代码。
`ARG-0002`	缺少必填参数——`idempotencyKey`、`amount`、`method`，或所选方式对应的目标 ID。
`HN-0124`	该卡不支持推卡（OCT）提现。请提供其他方式。
`BC-0004`	该卡被拒。请展示提示并提供其他方式。
`G-0004`	银行卡提现暂不可用。稍后重试或改用其他方式。

ARG-* 错误会在资金发生任何变动之前抛出。

错误响应示例

{
  "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.3.0

加急提现与费用预览

重新引入 WithdrawCashBalanceInput 上的 isExpedited。它控制 BANK_CARD 提现的到账速度：true 表示在请求期间推送至该卡，false 或省略表示按标准进度结算。这取代了下面 v1.2.0 的说明（此前表示该字段已被移除）。
新增 getWithdrawFeeEstimate 查询以及 GetWithdrawFeeEstimateInput / WithdrawFeeEstimate 类型，可在提交前预览费用、净额与结算时间。
补充了关于推卡提现作为原始贷记交易（OCT）的说明，包括卡片可用性，以及标准提现在提交后仍可能失败并退回至来源余额的事实。
更正了 withdrawCashBalance 的必需 scope 为 MAKE_WITHDRAWAL。此前页面列出的 MANAGE_PAYMENT 有误；同时，Withdraw 类型上的 seat_id 也是可选的（UUID），而非 v1.2.0 所述的必填。
说明了虽然 FLUZPAY 存在于 WithdrawMethods 枚举中，但并不是可用的提现方式：withdrawCashBalance 会以 WDR-0004（提现方式无效）拒绝，getWithdrawFeeEstimate 则以 ARG-0001 拒绝。

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 对象

​必需的 Scope

​各账户类型的提现方式

​提现前预览费用

​推卡提现（OCT）

​卡片可用性

​错误处理

​错误响应示例

​多笔提现

​最佳实践

​更新日志

​v1.3.0

​v1.2.0 - 2024-11-20

​v1.1.0 - 2024-10-15

​v1.0.0 - 2024-09-01

概览

提现现金余额

示例请求

输入字段

WithdrawCashBalanceInput

示例响应

响应字段

Withdraw 对象

必需的 Scope

各账户类型的提现方式

提现前预览费用

推卡提现（OCT）

卡片可用性

错误处理

错误响应示例

多笔提现

最佳实践

更新日志

v1.3.0

v1.2.0 - 2024-11-20

v1.1.0 - 2024-10-15

v1.0.0 - 2024-09-01