Skip to main content

​
组件到底是什么

Fluz 组件是一个托管的、由 Fluz 渲染的流程，你只需几行 JavaScript 就能将其嵌入到自己的网站。它以模态窗口的形式运行，覆盖在你的页面之上，位于你的域名下，采用你的品牌风格。 它的存在是为了解决三项你不必自己构建的任务：

收集用户授权

组件是终端用户创建或登录其 Fluz 账户，并**向你的应用授予在该账户上操作所需的权限范围（scopes）**的方式。没有授权，就没有 API 访问。

采集敏感数据

卡号、SSN、身份证件和 PIN 由 Fluz 在 Fluz 的 PCI DSS 环境内收集，并在我们端加密存储。它们从不会触达你的服务器。

确认资金流动

用户会在一个他们信任的界面中查看并批准转账的金额与方向，这一步会将预授权令牌变为已完成的交易。
演示一个组件：payouts 其余工作——发卡、扣款、查余额、读交易——都由你通过 API 按自己的节奏在服务器端完成，无需用户在场。
心智模型： 组件是一个_同意与敏感数据的载体_，而不是一个产品。它是流程中狭窄且高合规的部分。真正的工作发生在 API。

​
分工方式

​
你可以在幕后运行一切

这是关于组件最常被忽略的一点：它并不是使用 Fluz 的唯一方式，也不是完成大部分工作的方式。 一旦用户授予了你的应用权限范围——无论是通过组件，还是通过独立的 OAuth 授权流程——你的服务器就持有了用户访问令牌。从那一刻起，API 功能 页面上列出的每项能力都可以由你以编程方式使用，无需打开组件，也无需用户旁观：

资金来源

关联银行卡和 Plaid 银行账户，然后按需扣款。

钱包与转账

开设消费账户、存款、取款，并在内部或账户之间划转资金。

虚拟卡

消费控制、锁定/解锁、PIN、钱包绑定、批量发卡。

Open loop cards

生成由收款人领取的托管卡链接，并全面掌控链接生命周期。

汇款

通过手机号或邮箱查找收款人，并向其他 Fluz 钱包转账。

审批与授权用户

添加团队成员、为其发卡并路由审批请求。
组件的工作是帮你拿到令牌。之后的事情完全在服务器端进行。

​
选择你要交给我们的流程比例

你不必在“全组件”或“全 API”之间二选一。大多数集成都介于两者之间，决定因素通常是你已持有并希望继续持有的敏感数据。
你将整个用户旅程交给我们。组件负责账户创建、手机号登录 + 双重认证、KYC、PIN 设置、权限授予以及交易确认。你只需渲染一个按钮并生成签名令牌。
  • 最快的投产路径——以小时计，而非以迭代计。
  • 你方零 PCI 范围，零 CIP 数据处理。
  • 对从点击到回调期间的外观与体验控制较少。
适用场景： 付款和提现流程、市场平台、零工平台、奖励计划——任何你希望资金离开你的系统、同时又不想成为金融机构的地方。
关于通过 API 注册用户： 如果你自行注册并完成用户 KYC，然后 再打开组件，请在预批准交易令牌中传入 externalId，这样我们就能将会话匹配到你已创建的账户，而不是新建一个。你也可以传入 phoneNumber、firstName、lastName、email 和 username 以跳过组件中的相应步骤。参见设置你的服务器。

​
组件与 OAuth 应用的关系

组件就是一个 OAuth 应用。它不是具有独立权限模型的独立对象——它是带有可嵌入前端的 OAuth 应用。
1

你定义上限（应用 scopes）

在应用的 Permissions 选项卡中，你选择应用可请求的 scopes。这是你的应用今后无论如何都能请求的最大权限，与某个具体用户同意了什么无关。某些组件类型运行不可或缺的 scopes 会被分组显示在选项卡底部，且不可取消选择。完整列表参见应用程序 Scopes——MAKE_DEPOSIT、MAKE_WITHDRAW、LIST_PAYMENT、CREATE_VIRTUALCARD、REVEAL_VIRTUALCARD、PURCHASE_GIFTCARD 等等。
2

你配置授权可去向何处（OAuth 选项卡）

Origin——承载组件的域名。Redirect URIs——我们的授权服务器可将用户送回的地址，不含查询参数，并且在交换时必须精确匹配。Webhook URLs——一个或多个 REST 端点，每个端点可选订阅特定事件；未选事件的 URL 成为兜底项。参见配置应用组件。
3

用户设定下限（用户 scopes）

当组件打开时，用户会看到你请求的 scopes——以可读的顶层分组展示，而非原始枚举值列表——并进行批准。任何被拒绝的权限都不会被授予。
4

两种授权都必须有效

应用的有效权限是应用级授权与用户级授权的交集，且二者都必须未过期。这一点在 generateUserAccessToken 时强制执行，而不是在调用时——因此撤销或过期的授权会表现为令牌失败，而非流程中途出现神秘错误。
5

代码变成令牌

授权会在你的重定向 URI 生成授权 code。在 /token/exchange 处用 client_id:client_secret 的 Basic 认证头来交换，获得 accessToken、refreshToken 和已确认的 scope 数组。参见交换授权码与刷新访问令牌。
预批准交易令牌（patToken）与 OAuth 访问令牌是不同的东西，承担不同职责。patToken 是用你的 apiSecret 签名的短期、单笔交易 JWT，只授权_一次_、_一个金额_的资金流动。OAuth 的 accessToken 则允许你的服务器在一段时间内代表用户对其账户进行操作。一次组件会话通常会同时涉及两者。

​
PCI 合规与敏感数据

当组件打开时，其中的敏感字段属于 Fluz，而不是你。用户在我们的 iframe 中输入、向我们的服务器提交，受我们的合规计划保障。 这意味着 Fluz 负责：
  • 卡数据。 PAN、有效期与 CVV 按照 PCI DSS 要求采集与存储，并在我们端静态加密。你的页面从不接触它们，你的日志不会包含它们，你的基础设施在这些流程中不处于 PCI 范围内。
  • 完整卡号展示。 向终端用户展示其虚拟卡号同样使用 Fluz 托管界面，原因相同。
  • CIP 与身份数据。 SSN、出生日期、地址以及上传的身份证件在我们的验证环境内采集与留存。
  • PIN。 由我们设置与存储，从不传输给你。
  • 银行凭据。 Plaid 关联流程在组件内运行；你从不处理用户的银行登录信息。
你的责任范围：你的 apiSecret 与 client_secret。Installation 选项卡会渲染包含你真实凭据的可用代码片段，这既方便也有风险——在你的服务器上生成 patToken，切勿在浏览器 JavaScript 中生成。 任何出现在页面源代码中的内容都是公开的。
Fluz 维持 SOC 2 Type II 控制，并按照 PCI DSS 要求处理卡数据。若你的合规团队需要供应商审查文档，请联系你的 Fluz 客户经理。

​
获取你的嵌入代码

你无需手写集成代码。应用的 Installation 选项卡会为你生成，预填你应用的真实 apiKey，并提供两个选择器： Transaction Type——选择资金流动方向： Server Language——在你的后端实际使用的语言中，生成签名预批准交易令牌的代码片段：

JavaScript

Ruby

Python

Go

Java

PHP

C# / .NET

更多

切换选择器，代码块会自动更新——正确的 JWT 库、正确的声明字段名、正确的 HS256 签名以及一天有效期。复制它，将你从机密存储中取出的 apiSecret 填入，即可得到可用的令牌生成器。每个变体也都在设置你的服务器中有完整文档。 客户端部分是一行 script 标签加一次 FluzEmbedded.init(...) 调用。你可以让我们渲染按钮，也可以把模态绑定到你已有的按钮上。参见将 JS 组件添加到你的页面。 你的应用配置位于：
例如 https://fluz.app/for-developers/overview/19be9561-a6a1-4e02-8243-10ede908ef33。顶部的选项卡——Overview、Permissions、OAuth、Installation——与上述步骤一一对应。

​
从模板开始

你不会从空白应用开始。在开发者控制台中选择 Browse templates，并挑选最接近你要构建内容的模板。模板会预配置应用类型、所需 scopes、交易方向以及用户将看到的屏幕顺序——因此新应用在你完成命名的一刻就可用。 当前可用的模板包括：
将模板视为起点，而非规范。 创建后前往 Permissions 选项卡，根据你的实际目标塑造应用——添加用例所需的 scopes，移除不需要的。一个未来会代表用户发卡的 payout 组件需要 CREATE_VIRTUALCARD；仅移动现金的则不需要。请求更少的 scopes 意味着更短的同意界面与更高的完成率，因此只请求你所需的内容。
创建应用：添加新的应用组件 · 配置它：配置应用组件 · 关闭它：禁用或删除你的应用

​
终端用户会看到什么

当用户访问承载你组件的页面并触发打开模态的动作后：
1

登录或注册

用户通过发送到其手机的双重验证码对其 Fluz 账户进行认证。若他们没有账户，会在此创建。在 patToken 中传入 phoneNumber 可直接跳到验证码输入步骤。
2

KYC

如果你已持有用户的 SSN，请传给我们以便验证。否则，组件会运行完整的 KYC 流程。响应为 APPROVED、DECLINED、DUPLICATE 或 ERROR——每种含义及用户可尝试次数见用户 KYC 验证。
3

授予权限

用户审阅并批准你的应用请求的 scopes。
4

设置 PIN

这是一项覆盖 Fluz 的安全措施，后续在需要更高级别确认的操作中会再次提示。
5

确认交易

用户看到金额与方向，并选择批准或关闭。无论哪种情况，你都会收到事件。

​
Pay-In：资金进入你的平台

请先检查用户的 Fluz 余额，确认其可覆盖交易。
  1. 用户输入存款金额并点击你的按钮。
  2. 组件展示确认界面。
    • 已确认 → 我们从用户的消费账户向你的账户发起转账。
    • 被拒绝或关闭 → 我们发送事件。
  3. 你会收到完成或失败事件。
  4. 验证你的 Fluz 余额以确认结算。

​
Payout：资金转出给你的用户

请先检查你账户的 Fluz 余额。若无法覆盖转账，请先从你的资金来源发起存款。在你方隔离或冻结用户资金，以防转账在途期间发生双花。
  1. 用户输入提现金额并点击你的按钮。
  2. 组件展示确认界面。
    • 已确认 → 我们从你的运营者消费账户向用户账户发起转账。
    • 被拒绝或关闭 → 我们发送事件。
  3. 你会收到完成或失败事件。
  4. 组件向用户展示提现已完成，并提供其 Fluz 虚拟卡的直接访问。
每次资金流动调用都需要在令牌中使用唯一的 jti 以实现幂等性，并在 API 侧使用唯一的 idempotencyKey。参见幂等性。

​
后续步骤

添加组件

从模板创建你的第一个应用。

配置 OAuth 与权限

Scopes、origins、重定向 URI、webhooks。

设置你的服务器

用你的语言生成预批准交易令牌。

嵌入组件

Script 标签、初始化调用、按钮绑定。

API 的全部能力

完整能力面，全部可在服务器端使用。

构建一个平台

通过客户范围的令牌在关联账户上运行所有能力。