提现到外部账户

概览

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

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

Fluz 支持以下提现方式：

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

提现现金余额

示例请求

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

该变更需要 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 变更的响应包含提现记录以及用户更新后的余额。

{
  "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。

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`	通用提现错误。请检查错误消息了解详情。

错误响应示例

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

多笔提现记录

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

{
  "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 字段，用于多 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 以进行提现处理
添加应用操作日志记录以提供审计追踪

​概览

​提现现金余额

​示例请求

​输入字段

​WithdrawCashBalanceInput

​示例响应

​响应字段

​Withdraw 对象

​必需的 Scope

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

​错误处理

​错误响应示例

​多笔提现记录

​最佳实践

​更新日志

​v1.2.0 - 2024-11-20

​v1.1.0 - 2024-10-15

​v1.0.0 - 2024-09-01

概览