钱包与转账 - Fluz

Fluz 上的每一美元都存放于一个余额中。资金从外部资金来源或虚拟账户号码进入余额，通过转账在余额之间流动，并通过购买或提现离开。本节涵盖以上全部内容。首先要理解的最有用的一点：一个账户不只有一个余额。它有多个，而且它们的行为各不相同。 有些可提现，有些不可提现，其中一个——消费账户——可以存在多个。

资金地图

余额类型

一个账户最多可以持有四种余额。消费账户是唯一一种用户可以拥有多个的余额。

余额	可否提现	它包含什么
消费账户（现金余额）	可	主要的工作余额。用于为礼品卡、虚拟卡、转账和提现提供资金。
奖励余额	可	在 Fluz 活动中赚取的返现和奖励奖金。
礼品卡余额	否	预付价值，仅可用于礼品卡和虚拟卡购买。
准备金余额	否	由 Fluz 持有，用于覆盖结算失败的交易，保持账户良好状态。

这些余额之和构成账户的可用 Fluz 余额——可用于为支付提供资金的总额。

同一余额会以多个名称出现。礼品卡余额在 getWallet 中返回为 giftCardCashBalance，在 Transaction 类型上返回为 gift_card_prepayment_balance_*。奖励余额在 getWallet 中是 rewardsBalance，在 Transaction 上是 seat_balance_*。这些是别名，而不是不同的钱包。

消费账户持有余额

消费账户——API 中的 UserCashBalance——是一个具名的现金容器。用户可以开设多个，并为每个设置昵称，从而按用途隔离资金而无需开设多个 Fluz 账户。 每个消费账户都有自己独立的余额。 一个账户中的资金不会在另一个账户中可用，除非通过内部转账进行划转。每个消费账户跟踪三个数值，均以字符串返回：

字段	含义
`totalCashBalance`	该账户当前持有的全部余额。
`availableCashBalance`	目前可立即支用的部分。
`lifetimeCashBalance`	该账户自成立以来累计存入总额。

入金方式

资金流入余额有两种本质不同的方向，这一区别会影响你的集成方式。

拉取——由你发起

你的应用调用 depositCashBalance，Fluz 从用户已关联的资金来源拉取资金：银行账户、银行卡或数字钱包。你可控制时间与金额。

推送——由他方发起

外部方将资金发送至附属于某个消费账户的虚拟账户号码。到达后 Fluz 记入存款。你无法控制时间与金额。

路径	支付轨道	发起方	入账至
存入资金	ACH 拉取、银行卡、PayPal	你的应用	指定的消费账户
虚拟账户号码	RTP、FedNow、Wire、电汇、ACH 入账	外部汇款方	该 VAN 背后的消费账户
兑换 Fluz 礼品卡	—	用户	礼品卡余额
符合条件活动的返现	—	Fluz	奖励余额

虚拟账户号码是一个地址，而非余额。每个消费账户可以拥有一个或多个虚拟账户号码——真实的路由号与账号对。任何汇入这些号码的资金都会记入该消费账户。同一账户上的多个 VAN 共享同一余额；它们的存在是为了让你区分不同来款，如工资入账与客户付款。参见虚拟账户号码。

资金划转与取出

动作	操作	所需权限
在消费账户间转账	内部转账	`MANAGE_PAYMENT`
转账至其他 Fluz 账户	钱包转账	`MANAGE_PAYMENT`
查询转账收款人	解析 `account_id`	—
提现至外部账户	提现	`MANAGE_PAYMENT`

礼品卡余额与准备金余额不可提现。 礼品卡余额仅可用于礼品卡与虚拟卡购买。准备金余额由 Fluz 持有，非用户可指挥的资金。

读取余额

getWallet 一次性返回账户的各类余额，以及用户已关联的资金来源。

query getWallet {
  getWallet {
    balances {
      rewardsBalance      { availableBalance totalBalance lifetimeBalance }
      cashBalance         { availableBalance totalBalance pendingBalance lifetimeBalance }
      giftCardCashBalance { availableBalance totalBalance pendingBalance lifetimeBalance }

      userCashBalances(paginate: { limit: 10, offset: 0 }) {
        userCashBalanceId
        nickname
        totalCashBalance
        availableCashBalance
        lifetimeCashBalance
        status
        createdAt
      }
    }
    blockedPaymentTypes
  }
}

userCashBalances 支持分页，并按创建时间倒序返回账户。若要获取单个消费账户，请使用 getUserCashBalanceById。

若需展示用户可支用现金总额，请对 userCashBalances 中的 availableCashBalance 求和。 不要再将 cashBalance 与各个消费账户数值相加——那会高估总额。

准备金余额由 Fluz 持有而非用户指挥。其当前状态可在每笔交易上通过 reserve_balance_available_balance 和 reserve_balance_total_balance 快照字段查看，详见下文。

读取总账

余额告诉你现状；getTransactions 告诉你如何到达该状态。若要查看某个特定消费账户的总账，请按其 ID 过滤。 所需权限范围： LIST_PAYMENT 以及 LIST_PURCHASES

query spendAccountLedger($userCashBalanceId: [UUID], $limit: Int, $offset: Int) {
  getTransactions(
    filter: { userCashBalanceId: $userCashBalanceId }
    paginate: { limit: $limit, offset: $offset }
  ) {
    transactions {
      record_id
      transaction_type
      amount
      source
      destination
      status
      used_user_cash_balance_id
      cash_balance_available_balance
      created_at
    }
    totalCount
    hasNextPage
  }
}

Variables

{
  "userCashBalanceId": ["9c1f6b2e-4d7a-4c3b-9f11-2a5e8b0d6c74"],
  "limit": 20,
  "offset": 0
}

每笔交易还带有一个余额快照——该交易应用后每个余额的状态——以及指示交易影响了哪些余额的标志位：

余额	快照字段	影响标志
消费/现金	`cash_balance_available_balance` · `cash_balance_total_balance`	`is_cash_balance_affected`
奖励	`seat_balance_available_balance` · `seat_balance_total_balance`	`is_seat_balance_affected`
礼品卡	`gift_card_prepayment_balance_available_balance` · `gift_card_prepayment_balance_total_balance`	`is_gift_card_balance_affected`
准备金	`reserve_balance_available_balance` · `reserve_balance_total_balance`	`is_reserve_balance_affected`
其他现金	`other_cash_balance_available_balance` · `other_cash_balance_total_balance`	—

只有消费账户可按 ID 过滤。 TransactionFilterInput 暴露了 userCashBalanceId，但没有针对奖励、礼品卡或准备金余额的等效过滤器。若要筛选这些余额的活动，请按日期范围获取交易并基于相应的 is_..._affected 标志过滤。

getTransactions 每页最多返回20 条记录。检查 hasNextPage 并递增 offset 以分页。完整过滤器参考见 Get All Transactions。

权限范围速览

你的目标	所需范围
读取余额、消费账户与 VAN	`LIST_PAYMENT`
读取交易总账	`LIST_PAYMENT` + `LIST_PURCHASES`
创建、编辑或关闭消费账户	`MANAGE_PAYMENT`
存入、转账或提现	`MANAGE_PAYMENT`

下一步去哪里

消费账户

创建、重命名并关闭持有余额的账户。

虚拟账户号码

通过 RTP、FedNow、电汇与 ACH 入账直接接收至消费账户。

存入资金

从已关联的银行账户或银行卡拉取资金入金。

提现资金

将资金转出至外部账户。

账户间转账

在用户自己的多个消费账户之间划转余额。

获取全部交易

完整总账，包含过滤与分页。

想了解更多？ 与我们的专家交流以获取更多信息或申请演示。

​资金地图

​余额类型

​消费账户持有余额

​入金方式

拉取——由你发起

推送——由他方发起

​资金划转与取出

​读取余额

​读取总账

​权限范围速览

​下一步去哪里

消费账户

虚拟账户号码

存入资金

提现资金

账户间转账

获取全部交易

资金地图

余额类型

消费账户持有余额

入金方式

资金划转与取出

读取余额

读取总账

权限范围速览

下一步去哪里