Skip to main content
虚拟账户号码（VAN） 是由银行签发的真实路由号和账户号，指向某个用户的消费账户。任何 Fluz 之外的主体——雇主、银行、客户、市场平台——都可以向该路由号与账户号组合汇款，资金将作为存款进入该消费账户。 VAN 不持有资金。消费账户才持有余额。 VAN 只是通向它的另一条地址。
单一余额，多重地址——最终将实现。无论资金通过哪条地址到达，消费账户都会入账到同一笔余额。VAN 的数据模型支持每个消费账户拥有多个活动的虚拟账户号码，其中恰有一个被标记为主要，以便未来可以按来源方区分——例如工资发放与某位特定客户——而无需拆分资金。目前，每个消费账户都会配置且仅配置一个 VAN，并且它始终是主要的。现在还没有通过 API、控制台或客户经理来申请第二个 VAN 的路径。参见多个虚拟账户号码。

​
协同工作方式

入账资金通过 VAN 到达。出账资金仍以一贯方式从消费账户流出——礼品卡与虚拟卡资金、内部转账，以及提现至已链接的外部账户。

​
配置

虚拟账户号码由 Fluz 配置。没有用于创建 VAN 的变更操作，也没有控制台按钮可申请。只要消费账户满足条件，配置将由 Fluz 端发起完成；你的集成只需读取结果，而非触发创建。

​
资格

当满足以下所有条件时，消费账户具备虚拟账户号码的资格：
创建消费账户并非触发条件。具备资格的消费账户与已配置 VAN 是两个不同状态。新创建的消费账户可立即用于礼品卡、虚拟卡以及内部转账，但可能尚未拥有 VAN。在创建消费账户后立刻展示存款指引会让用户看到空白页面。

​
触发与时效

配置是自动且异步的。一旦满足上述条件，Fluz 即会发起；VAN 由赞助银行签发，并在银行返回后写回该消费账户。 VAN 不会在创建消费账户的同一次请求中可用。将可用性视为最终一致性，并在用户真正需要时再读取 VAN，而不是在账户创建时读取。 在 VAN 写回之前，getSpendAccountVirtualAccountNumbers 返回一个空数组。不会报错，也不会返回 null。
Pending — VAN not yet provisioned
单独的空数组具备歧义：它既可能表示_尚未配置_，也可能表示_项目未获授权_。请结合消费账户自身状态来判断，而不是无限重试。

​
推荐的集成模式

1

创建消费账户

按你的常规流程继续。不要因 VAN 的可用性阻塞用户。
2

延迟读取 VAN

当用户进入存款、直接存款或账户详情页面时再调用 getSpendAccountVirtualAccountNumbers——不要在账户创建时提前调用。
3

显式处理空结果

渲染“正在设置存款详情”的状态，而非报错或留空。下次进入页面时再检查。
4

按 ID 缓存，而非按位置

使用 virtualAccountNumberId 作为稳定键。切勿按数组索引进行键控。

​
API 与控制台行为一致

二者读取相同的底层对象，且均无法创建、修改或移除。 若某个消费账户的 API 返回空数组，则控制台对同一账户也不会显示任何存款详情。不存在仅限控制台的 VAN 获取途径。

​
支持的清算通道

发送至虚拟账户号码的入账支持四条清算通道：
暂不支持 ACH 借记（拉取）。虚拟账户号码目前仅能接收资金。你不能使用 VAN 的路由号与账户号发起 ACH 借记——第三方无法用这些凭据从消费账户拉走资金。对 ACH 借记的支持即将推出。目前如需出金，请使用提现至外部账户或内部转账。

​
入账长什么样

当资金到达虚拟账户号码时，Fluz 会针对目标消费账户记录一笔标准存款。该存款的资金来源为虚拟账户——而非银行卡、银行账户或 PayPal——因为这笔钱起源于 Fluz 之外，是被推送进来的，而不是从已链接的支付方式中被拉取的。 这意味着：
  • 这笔入账会出现在与其他任何存款相同的交易与存款历史中。
  • 不存在可对账的关联资金来源对象，也不存在备用卡预授权，因为并未从用户处扣款。
  • 该存款可归因到接收它的具体 VAN，因此当一个消费账户拥有多个 VAN 时，你可以区分工资入账与客户付款。

​
获取用户的虚拟账户号码

使用 getSpendAccountVirtualAccountNumbers 列出某个消费账户上的活动 VAN。它会返回所有活动的 VAN，其中一个被标记为主要。 所需权限范围：LIST_PAYMENT
Variables
返回 [SpendAccountVirtualAccountNumber!]!。完整字段列表参见类型参考。
展示账户号。VAN 的完整账户号属于敏感信息。在列表视图中应进行掩码处理，只有在用户明确操作时才显示完整值，就像对待卡片 PAN 一样。当用户需要将详情提供给第三方时，优先使用虚拟账户文档中所述的 PDF 生成件，而非自由复制粘贴。

​
多个虚拟账户号码

查询返回列表，并且类型带有 isPrimary 标记，这是因为底层 VAN 数据模型支持每个消费账户拥有多个活动的虚拟账户号码——例如一个专用于工资发放、另一些按客户区分——全部入账到同一余额。 这在今天尚不可用。 目前每个消费账户仅限一个 VAN，且不存在通过 API 变更、控制台流程或客户经理申请来创建、查看或管理第二个 VAN 的方式。对于 Austin Capital Bank（Fluz 当前的 VAN 赞助方），每账户一个 VAN 的限制是 ACB 端的全局设置，而非按项目配置——因此 Fluz 无法为某个单独的集成进行配置或启用。
当前对所有项目均为只读。上述读取查询（getSpendAccountVirtualAccountNumbers）是唯一对外提供的 VAN 操作，适用于所有集成，无一例外。对额外 VAN 的支持是未来能力，而非今日可申请或开启的功能。

​
依然按列表来构建

尽管今天每个消费账户恰有一个 VAN，也请按列表结构而非单对象来编写代码。API 已按该方式设计，这样未来若支持更多 VAN，你无需进行破坏性修改。
  • 切勿按数组索引取值。 不要读取 result[0]。请选择 isPrimary 为 true 的 VAN。
  • 显式处理长度为 0 的情况（参见配置），尽管目前非零情况总为长度 1。
  • 在文档查询中显式传递 virtualAccountNumberId，而不是依赖主要 VAN 的默认选择，这样当将来支持额外 VAN 时，你的集成无需改代码。

​
向第三方提供详情

相比让用户手动把路由号和账户号抄录到工资系统或通过邮件发给交易对手，Fluz 可按需生成 PDF 文档： 在未传入 virtualAccountNumberId 时，这三种文档均默认使用消费账户的主要 VAN，并且三者都需要 LIST_PAYMENT 权限范围。 完整参考见虚拟账户文档。

​
要求

  • 用户必须至少拥有一个活动的消费账户，且账户持有人已通过 CIP。
  • 你的项目必须在赞助银行获授 VAN 权限。这在上线对接时约定，无法通过 API 启用。
  • 读取虚拟账户号码及生成文档均需要用户访问令牌上的 LIST_PAYMENT 权限范围。
  • 虚拟账户号码由 Fluz 异步配置，且无法通过 API 或控制台创建、修改或删除。参见配置。
  • 目前在读取时假设消费账户可能为 0 或 1 个 VAN。按列表结构编写（不要用索引）以适配未来可能支持的多个 VAN。

​
相关

消费账户

实际持有余额的账户。

虚拟账户文档

付款指引、存款表与状态函。

存入资金

从已链接的银行账户或银行卡发起拉取入账。

资金来源

Fluz 如何分类流入的资金。
想进一步了解？ 联系我们的专家以获取更多信息或申请演示。