Skip to main content

​
小部件究竟是什么

Fluz 小部件是一段托管、由 Fluz 渲染的流程，你只需几行 JavaScript 即可将其嵌入你自己的网站。它在你的页面之上、你的域名下、你的品牌风格内以模态框运行。 它存在是为了替你完成三件你不应该自己去构建的事情：

收集用户授权

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

采集敏感数据

卡号、SSN、身份文件和 PIN 由 Fluz 采集，位于 Fluz 的 PCI DSS 环境中，并在我们这边加密。它们永远不会触达你的服务器。

确认资金流动

用户会在一个值得信任的界面中看到并批准转账的金额与方向，这一步会将预授权令牌转变为已完成的交易。
除此之外的一切 —— 发卡、拉取资金、查询余额、读取交易 —— 都由你通过 API 按自己的节奏完成，无需用户在场。
思维模型： 小部件是一种_同意与敏感数据界面_，不是一个产品。它是流程中狭窄且高合规的部分。实际工作发生在 API 上。

​
分工

​
你可以在幕后完成一切

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

资金来源

关联银行卡与 Plaid 银行账户，并在需要时拉取资金。

钱包与转账

开设消费账户，存入、提现，在内部或跨账户划转资金。

虚拟卡

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

开放式卡

生成由收件人认领的托管卡片链接，并对链接全生命周期进行控制。

汇款

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

审批与授权用户

添加团队成员，为其发卡，并路由审批请求。
小部件的职责是帮你拿到令牌。之后你要做的全部在服务器端完成。

​
自由选择交给我们的流程范围

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

​
小部件与 OAuth 应用的关系

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

你定义天花板（应用范围）

在你应用的 Permissions 选项卡中，选择你的应用被允许请求的范围。这是你的应用可请求的最大权限，与任何单个用户是否同意无关。某些小部件类型无法缺少的范围会被分组到该选项卡底部，且无法取消选择。完整列表见 应用范围 —— MAKE_DEPOSIT、MAKE_WITHDRAW、LIST_PAYMENT、CREATE_VIRTUALCARD、REVEAL_VIRTUALCARD、PURCHASE_GIFTCARD 等等。
2

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

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

用户设定地板（用户范围）

小部件打开时，会向用户展示你请求的范围 —— 按可读的顶层分组显示，而非原始枚举值列表 —— 由用户批准。任何被拒绝的范围都不会被授予。
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 并挑选最接近你要构建内容的模板。模板会预配置应用类型、所需范围、交易方向以及用户将看到的屏幕顺序 —— 因此新应用在你完成命名的那一刻就能工作。 当前可用的模板包括：
将模板视为起点而非规格。 创建后，前往 Permissions 选项卡，并围绕你的实际目标塑造应用 —— 添加你的用例所需的范围，移除不需要的范围。一个稍后会代表用户发卡的提现小部件需要 CREATE_VIRTUALCARD；仅现金流动的则不需要。请求更少的范围意味着更短的同意界面与更高的完成率，所以只请求你所需的权限，不多也不少。
创建应用：添加新的应用小部件 · 配置应用：配置应用小部件 · 关闭应用：禁用或删除你的应用

​
终端用户所见

当用户抵达承载你小部件的页面并触发打开模态框的动作后：
1

登录或注册

用户通过发送到其手机的双因素验证码登录其 Fluz 账户。如果他们没有账户，可以在此创建。在 patToken 中传入 phoneNumber 可直接跳过到验证码输入步骤。
2

KYC

如果你已经持有用户的 SSN，请传给我们以便验证；否则，小部件会运行完整 KYC 流程。返回值为 APPROVED、DECLINED、DUPLICATE 或 ERROR —— 各含义与用户可尝试次数见 用户 KYC 验证。
3

授予权限

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

设置 PIN

这是全局适用于 Fluz 的安全措施，后续在需要更高确认的操作中会再次提示。
5

确认交易

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

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

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

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

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

​
后续步骤

添加小部件

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

配置 OAuth 与权限

范围、来源域、重定向 URI、Webhooks。

设置你的服务器

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

嵌入小部件

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

API 的全部能力

全部功能面，均可在服务器端使用。

构建平台

使用客户范围令牌在关联账户上运行所有能力。