Skip to main content

​
小部件究竟是什么

Fluz 小部件是一个由 Fluz 托管并渲染的流程，你只需几行 JavaScript 就能把它嵌入你自己的网站。它运行在你的域名下，采用你的品牌样式，可以作为覆盖在页面上的模态框运行，或者（目前仅限预发布环境）内联渲染在你自定义尺寸的容器中。 它存在是为了完成三件你不应自己去构建的工作：

收集用户授权

小部件是终端用户创建或登录其 Fluz 账户并授予你的应用在该账户上所需的作用域的方式。没有授权，就没有 API 访问。

采集敏感数据

卡号、SSN、身份证件和 PIN 均由 Fluz 在 Fluz 的 PCI DSS 环境中采集，并在我们侧加密存储。它们永远不会触达你的服务器。

确认资金流动

用户在一个他们信任的界面中查看并批准转账金额与方向，这一步使预授权令牌转化为已完成的交易。
[演示一个小部件：付款]https://demos.fluz.app/payout-prepaid/?launch-card=1&subtitle=Send%20a%20payout%20and%20watch%20it%20become%20a%20spendable%20card.&image=https%3A%2F%2Fdemos.fluz.app%2Fassets%2Fprepaid-demo-shot.png&image-dark=https%3A%2F%2Fdemos.fluz.app%2Fassets%2Fprepaid-demo-shot-dark.png) 其他所有事情——发卡、资金归集、余额查询、读取交易——都由你通过 API 在服务器端按你的节奏来做，无需用户在场。
**思维模型：**小部件是一个_授权与敏感数据的界面_，不是一款产品。它是流程中窄而高合规的部分。真正的工作发生在 API。

​
分工方式

​
你可以在幕后完成一切

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

资金来源

关联银行卡和 Plaid 银行账户，然后按需拉取资金。

钱包与转账

开立消费账户，存入、取出，并在内部或跨账户移动资金。

虚拟卡

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

开放回路卡

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

汇款

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

审批与授权用户

添加团队成员，为他们发卡，并路由审批请求。
小部件的工作是帮助你拿到令牌。之后你要做的一切都在服务器端完成。

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

你不必在“全小部件”或“全 API”之间二选一。大多数集成都落在二者之间，决定因素通常是你已经持有并希望继续掌握的敏感数据是什么。
你把整个用户旅程交给我们。小部件处理账户创建、手机号 + 2FA 登录、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 托管的界面——要么在小部件内，要么通过 Secure Elements Card Reveal 内联到你的页面。不论哪种方式，数据都在 Fluz 的框架中渲染，而非你的，从而你不进入 PCI 范围。仅当你将原始 PAN 和 CVV 引入自己的服务器时才需要 PCI DSS 认证——参见尽职调查。
  • **CIP 与身份数据。**SSN、出生日期、地址与上传的身份证件均在我们的验证环境中采集与保存。
  • **PIN。**由我们设置与存储，从不向你传输。
  • **银行凭据。**Plaid 关联流程在小部件中运行；你不会处理用户的银行登录信息。
你的责任仍包括：你的 apiSecret 与 client_secret。Installation 标签会渲染包含你真实凭据的可用代码片段，这既方便也有风险——**在你的服务器上生成 patToken，绝不要在浏览器 JavaScript 中生成。**任何出现在页面源码中的内容都属于公开信息。
Fluz 维护 SOC 2 Type II 控制，并按照 PCI DSS 要求处理卡片数据。若你的合规团队需要供应商审查的资料，请联系你的 Fluz 客户经理。

​
获取嵌入代码

你无需手写集成。应用的 Installation 标签会为你生成集成代码，预先填充你应用真实的 apiKey，并提供两个选择器： Transaction Type——选择资金流向： 并非每种小部件类型都会发生资金流动。ENROLLMENT 会按你选择的顺序引导用户完成账户设置——身份验证、资金来源、PIN——不包含金额与交易确认。目前仅在预发布环境可用。 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

登录或注册

用户通过发送到其手机的 2FA 验证码登录其 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、Webhook。

设置你的服务器

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

嵌入小部件

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

Enrollment 小部件

按你选择的顺序运行 KYC、资金来源与 PIN。目前仅限预发布环境。

Secure Elements

在你的页面内联展示卡片详情，无需小部件模态框。

终止会话

在用户完成之前取消你已移交的小部件支付。

API 的全部能力

完整的能力范围，均可在服务器端使用。

构建平台

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