> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fluz.app/llms.txt
> Use this file to discover all available pages before exploring further.

# 嵌入式小部件概览

> 将托管的 Fluz 流程嵌入到你的产品中，用于收集用户授权、在我们的 PCI 范围内采集敏感数据并确认资金流动 —— 然后在服务器端通过 API 完成其余所有工作。

## 小部件究竟是什么

Fluz 小部件是一段托管、由 Fluz 渲染的流程，你只需几行 JavaScript 即可将其嵌入你自己的网站。它在你的页面之上、你的域名下、你的品牌风格内以模态框运行。

它存在是为了替你完成三件你不应该自己去构建的事情：

<CardGroup cols={3}>
  <Card title="收集用户授权" icon="shield-check">
    小部件是终端用户创建或登录其 Fluz 账户并\*\*授予你的应用可在其账户上执行操作所需范围（scopes）\*\*的方式。没有授权，就没有 API 访问。
  </Card>

  <Card title="采集敏感数据" icon="lock">
    卡号、SSN、身份文件和 PIN 由 Fluz 采集，位于 Fluz 的 PCI DSS 环境中，并在我们这边加密。它们永远不会触达你的服务器。
  </Card>

  <Card title="确认资金流动" icon="arrow-left-right">
    用户会在一个值得信任的界面中看到并批准转账的金额与方向，这一步会将预授权令牌转变为已完成的交易。
  </Card>
</CardGroup>

除此之外的一切 —— 发卡、拉取资金、查询余额、读取交易 —— 都由你通过 API 按自己的节奏完成，无需用户在场。

<Info>
  **思维模型：** 小部件是一种\_同意与敏感数据界面\_，不是一个产品。它是流程中狭窄且高合规的部分。实际工作发生在 API 上。
</Info>

***

## 分工

| 工作               | 小部件 | API                                                      |
| :--------------- | :-- | :------------------------------------------------------- |
| 创建用户的 Fluz 账户    | ✅   | ✅ [用户注册](/docs/user-registration)                        |
| 身份验证（KYC）        | ✅   | ✅ [用户 KYC 验证](/docs/user-kyc-verification)               |
| 企业验证（KYB）        | —   | ✅ [企业注册](/docs/business-registration)                    |
| 获取用户的范围授权        | ✅   | ✅ [OAuth 授权流程](/docs/grant-widget-user-permissions-todo) |
| 采集卡的 PAN / CVV   | ✅   | 仅代币化                                                     |
| 采集 SSN 或身份证件     | ✅   | 如果你已持有则可透传                                               |
| 设置交易 PIN         | ✅   | —                                                        |
| 确认特定转账金额         | ✅   | —                                                        |
| 通过 Plaid 关联银行账户  | ✅   | ✅ [资金来源](/features/funding-sources)                      |
| 开卡、编辑、锁定或展示虚拟卡   | —   | ✅ [虚拟卡](/features/virtual-cards)                         |
| 存入、提现、转账、汇款      | —   | ✅ [钱包与转账](/features/move-funds-with-external-accounts)   |
| 购买礼品卡、读取目录       | —   | ✅ [商户目录](/merchant-catalog)                              |
| 读取交易、批注、审批流      | —   | ✅ [交易](/features/get-all-transactions)                   |
| 批量发行最多 10,000 张卡 | —   | ✅ [批量操作](/features/virtual-cards)                        |

***

## 你可以在幕后完成一切

这是关于小部件最容易被忽略的一点：**它并不是使用 Fluz 的唯一方式，也不是大部分工作完成的方式。**

一旦用户授予了你的应用范围 —— 无论是通过小部件，还是通过独立的 [OAuth 授权流程](/docs/grant-widget-user-permissions-todo) —— 你的服务器就持有了用户访问令牌。从那一刻起，[API 功能](/features) 页面上列出的每一种能力都可由你以编程方式调用，无需打开小部件，也无需用户旁观：

<CardGroup cols={2}>
  <Card title="资金来源" icon="coins" href="/features/funding-sources">
    关联银行卡与 Plaid 银行账户，并在需要时拉取资金。
  </Card>

  <Card title="钱包与转账" icon="wallet" href="/features/move-funds-with-external-accounts">
    开设消费账户，存入、提现，在内部或跨账户划转资金。
  </Card>

  <Card title="虚拟卡" icon="credit-card" href="/features/virtual-cards">
    消费控制、锁定/解锁、PIN、钱包开通、批量发卡。
  </Card>

  <Card title="开放式卡" icon="wallet-cards" href="/features/open-loop-cards/send-open-loop-cards">
    生成由收件人认领的托管卡片链接，并对链接全生命周期进行控制。
  </Card>

  <Card title="汇款" icon="circle-dollar-sign" href="/features/account-to-account-transfers">
    通过手机号或邮箱查找收款人并转账到其他 Fluz 钱包。
  </Card>

  <Card title="审批与授权用户" icon="users" href="/features/approvals-and-requests">
    添加团队成员，为其发卡，并路由审批请求。
  </Card>
</CardGroup>

小部件的职责是帮你拿到令牌。之后你要做的全部在服务器端完成。

***

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

你不必在“全小部件”或“全 API”之间二选一。大多数集成介于两者之间，决定因素通常是**你已经持有哪些敏感数据并希望继续自行持有。**

<Tabs>
  <Tab title="全小部件">
    **你将整个用户旅程交给我们。**

    小部件负责账户创建、手机号 + 双因素登录、KYC、PIN 设置、权限授权以及交易确认。你只需渲染一个按钮并生成签名令牌。

    * 最快上生产的路径 —— 以小时计，而非以迭代计。
    * 你的侧边零 PCI 范围、零 CIP 数据处理。
    * 在点击与回调之间对界面外观的控制最少。

    **适用场景：** 付款与提现流程、市场平台、零工平台、奖励计划 —— 任何你希望资金离开你的系统、而你不想成为金融机构的地方。
  </Tab>

  <Tab title="混合（最常见）">
    **你保留你已经拥有的部分；我们接管你不愿处理的部分。**

    使用你在注册时已收集的资料，通过 [`registerUser`](/docs/user-registration) 自行为用户注册。如果你已持有 SSN 和地址，可使用 [`verifyUserInformation`](/docs/user-kyc-verification) 自行运行 KYC。之后仅在真正需要的步骤打开小部件：

    * 权限授权，
    * 当 KYC 返回 `DECLINED` 或需要审核时的证件上传，
    * 卡 PAN 采集，
    * PIN 设置，
    * 交易确认界面。

    你的引导流程仍由你掌控。用户不会重复输入你已掌握的信息。小部件仅在一个狭窄而显然与金融相关的时刻出现，随后即退出视野。

    **适用场景：** 已有通过 KYC 的用户群的平台、金融科技公司、任何已经完成身份验证且不希望让用户重复验证的场景。
  </Tab>

  <Tab title="无头 / 仅 API">
    **完全不使用小部件。**

    完全通过 API 完成用户注册、验证、关联资金来源、发卡与资金流动。通过独立的 [OAuth 授权流程](/docs/grant-widget-user-permissions-todo) 获取范围授权 —— 这是一次重定向，而非嵌入 —— 或者在你自己的平台账户上操作。

    * 对每一个像素拥有完全控制权。
    * 如果你采集卡数据，**你**需对 PCI DSS 范围负责；你处理的任何 CIP 数据也需由你保障安全。
    * 某些流程仍需要托管界面：向终端用户展示完整卡片信息和采集身份证件通常是例外情况。

    **适用场景：** 批量发卡、后台运营、拨付批次、ERP 与会计系统集成，以及任何无终端用户参与的流程。
  </Tab>
</Tabs>

<Note>
  **关于通过 API 注册用户：** 如果你自行为用户注册并完成 KYC，*然后* 打开小部件，请在预批准交易令牌中传入 `externalId`，以便我们将会话与已创建的账户匹配，而不是新建账户。你也可以传入 `phoneNumber`、`firstName`、`lastName`、`email` 和 `username` 来跳过小部件中的相应步骤。参见 [设置你的服务器](/developers/setting-up-your-server)。
</Note>

***

## 小部件与 OAuth 应用的关系

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

<Steps>
  <Step title="你定义天花板（应用范围）">
    在你应用的 **Permissions** 选项卡中，选择你的应用被允许请求的范围。这是你的应用可请求的最大权限，与任何单个用户是否同意无关。某些小部件类型无法缺少的范围会被分组到该选项卡底部，且无法取消选择。

    完整列表见 [应用范围](/docs/application-scopes) —— `MAKE_DEPOSIT`、`MAKE_WITHDRAW`、`LIST_PAYMENT`、`CREATE_VIRTUALCARD`、`REVEAL_VIRTUALCARD`、`PURCHASE_GIFTCARD` 等等。
  </Step>

  <Step title="你配置授权可去往何处（OAuth 选项卡）">
    **Origin** —— 承载小部件的域名。**Redirect URIs** —— 我们的授权服务器可将用户送回的位置，不带查询参数，并且在交换时必须精确匹配。**Webhook URLs** —— 一个或多个 REST 端点，每个端点可选订阅特定事件；未选事件的 URL 将作为兜底处理。

    参见 [配置应用小部件](/developers/configure-app-widget)。
  </Step>

  <Step title="用户设定地板（用户范围）">
    小部件打开时，会向用户展示你请求的范围 —— 按可读的顶层分组显示，而非原始枚举值列表 —— 由用户批准。任何被拒绝的范围都不会被授予。
  </Step>

  <Step title="两类授权都必须有效">
    应用的有效权限是应用级授权与用户级授权的**交集**，且二者都必须未过期。这在 `generateUserAccessToken` 阶段被强制执行，而不是在调用时 —— 因此被撤销或过期的授权会表现为令牌失败，而不是流程中莫名其妙的错误。
  </Step>

  <Step title="代码变成令牌">
    授权会在你的重定向 URI 处生成一个授权 `code`。在 `/token/exchange` 处使用 `client_id:client_secret` 的 Basic 认证头将其交换为 `accessToken`、`refreshToken` 与已确认的 `scope` 数组。参见 [交换授权码](/docs/exchanging-an-oauth-authorization-code) 与 [刷新访问令牌](/docs/refreshing-an-oauth-access-token)。
  </Step>
</Steps>

<Warning>
  预批准交易令牌（`patToken`）与 OAuth 访问令牌是**不同的东西**，并承担不同的职责。`patToken` 是由你的 `apiSecret` 签名的短期、单笔交易 JWT，只授权\_一次\_ \_一个金额\_的资金流动。OAuth `accessToken` 则允许你的服务器在更长时间内代表用户账户执行操作。一次小部件会话通常同时涉及两者。
</Warning>

***

## PCI 合规与敏感数据

当小部件打开时，其中的敏感字段属于 Fluz，而不是你。用户在我们的 iframe 中输入、向我们的服务器提交，受我们的合规计划覆盖。

这意味着 Fluz 负责：

* **卡数据。** PAN、有效期与 CVV 按照 PCI DSS 要求采集与存储，并在我们这边静态加密。你的页面从不接触它们，你的日志不会包含它们，你的基础设施在这些流程中保持在 PCI 范围之外。
* **完整卡号展示。** 向终端用户展示其虚拟卡号同样使用 Fluz 托管界面，理由相同。
* **CIP 与身份数据。** SSN、出生日期、地址与上传的身份证件在我们的验证环境内收集与留存。
* **PIN。** 由我们设置与存储，绝不传给你。
* **银行凭据。** Plaid 关联流程在小部件内运行；你不需处理用户的银行登录信息。

仍由你负责的内容：你的 `apiSecret` 与 `client_secret`。Installation 选项卡会渲染包含你真实凭据的可运行代码片段，这既方便也有风险 —— **在你的服务器上生成 `patToken`，切勿在浏览器 JavaScript 中生成。** 页面源代码中的任何内容都是公开的。

<Info>
  Fluz 维持 SOC 2 Type II 控制，并按照 PCI DSS 要求处理卡数据。若你的合规团队在供应商审查中需要文档，请联系你的 Fluz 客户经理。
</Info>

***

## 获取你的嵌入代码

你不需要手写集成。你应用的 **Installation** 选项卡会为你生成嵌入代码，预填你应用真实的 `apiKey`，并提供两个选择器：

**Transaction Type** —— 选择资金流动的方向：

| Installation 选项卡标签 | JWT 中的 `transactionType` | 会发生什么                                     |
| :----------------- | :----------------------- | :---------------------------------------- |
| **Pay-In**         | `DEPOSIT`                | 用户将资金转入 Fluz 并进一步进入你的运营消费账户。资金流向\_你的平台\_。 |
| **Payout**         | `WITHDRAW`               | 资金从你的运营消费账户流向用户的 Fluz 账户。资金流向\_你的用户\_。    |

**Server Language** —— 生成签名的预批准交易令牌的代码片段，使用你的后端实际所用语言：

<CardGroup cols={4}>
  <Card title="JavaScript" icon="square-code" />

  <Card title="Ruby" icon="gem" />

  <Card title="Python" icon="code" />

  <Card title="Go" icon="code" />

  <Card title="Java" icon="coffee" />

  <Card title="PHP" icon="code" />

  <Card title="C# / .NET" icon="code" />

  <Card title="更多" icon="ellipsis" />
</CardGroup>

切换选择器，代码块会自动改写 —— 正确的 JWT 库、正确的声明名称、正确的 HS256 签名、正确的一天过期时间。复制它，从你的密钥库中填入 `apiSecret`，你就拥有一个可运行的令牌生成器。每种变体也在 [设置你的服务器](/developers/setting-up-your-server) 中有完整文档。

客户端部分只需一个 script 标签加一次 `FluzEmbedded.init(...)` 调用。你可以让我们渲染按钮，或将模态框绑定到你已有的按钮。参见 [将 JS 小部件添加到你的页面](/developers/adding-the-js-widget-to-your-page)。

你的应用配置位于：

```text theme={null}
https://fluz.app/for-developers/overview/{appId}
```

例如 `https://fluz.app/for-developers/overview/19be9561-a6a1-4e02-8243-10ede908ef33`。顶部的选项卡 —— **Overview**、**Permissions**、**OAuth**、**Installation** —— 与上述步骤一一对应。

***

## 从模板开始

你并非从一个空白应用开始。在开发者控制台中，选择 **Browse templates** 并挑选最接近你要构建内容的模板。模板会预配置应用类型、所需范围、交易方向以及用户将看到的屏幕顺序 —— 因此新应用在你完成命名的那一刻就能工作。

当前可用的模板包括：

| 模板                                   | 它会设置什么                                         |
| :----------------------------------- | :--------------------------------------------- |
| **Withdraw to a virtual Mastercard** | 一个以可即时使用的 Fluz 虚拟卡结束的 `Payout` 流程。预先选择提现与开卡范围。 |
| **OAuth Integration**                | 一个仅含权限、不带嵌入式 UI 的应用 —— 适用于无头与重定向式集成。           |

<Note>
  **将模板视为起点而非规格。** 创建后，前往 **Permissions** 选项卡，并围绕你的实际目标塑造应用 —— 添加你的用例所需的范围，移除不需要的范围。一个稍后会代表用户发卡的提现小部件需要 `CREATE_VIRTUALCARD`；仅现金流动的则不需要。请求更少的范围意味着更短的同意界面与更高的完成率，所以只请求你所需的权限，不多也不少。
</Note>

创建应用：[添加新的应用小部件](/developers/add-a-widget) · 配置应用：[配置应用小部件](/developers/configure-app-widget) · 关闭应用：[禁用或删除你的应用](/developers/disable-or-delete-your-app)

***

## 终端用户所见

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

<Steps>
  <Step title="登录或注册">
    用户通过发送到其手机的双因素验证码登录其 Fluz 账户。如果他们没有账户，可以在此创建。在 `patToken` 中传入 `phoneNumber` 可直接跳过到验证码输入步骤。
  </Step>

  <Step title="KYC">
    如果你已经持有用户的 SSN，请传给我们以便验证；否则，小部件会运行完整 KYC 流程。返回值为 `APPROVED`、`DECLINED`、`DUPLICATE` 或 `ERROR` —— 各含义与用户可尝试次数见 [用户 KYC 验证](/docs/user-kyc-verification)。
  </Step>

  <Step title="授予权限">
    用户审阅并批准你的应用请求的范围。
  </Step>

  <Step title="设置 PIN">
    这是全局适用于 Fluz 的安全措施，后续在需要更高确认的操作中会再次提示。
  </Step>

  <Step title="确认交易">
    用户会看到金额与方向，并选择批准或关闭。无论哪种情况，你都会收到事件。
  </Step>
</Steps>

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

<Info>
  先检查用户的 Fluz 余额，以确认其可覆盖此次交易。
</Info>

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

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

<Info>
  先检查你账户的 Fluz 余额。如果无法覆盖转账，请从你的资金来源发起存款。在转账进行中，请在你侧隔离或冻结用户资金以避免双重花费。
</Info>

1. 用户输入提现金额并点击你的按钮。
2. 小部件展示确认界面。
   * **确认** → 我们从你的运营消费账户向用户账户发起转账。
   * **拒绝或关闭** → 我们发送事件。
3. 你会收到完成或失败事件。
4. 小部件向用户展示提现完成，并为其提供对 Fluz 虚拟卡的直接访问。

<Note>
  每一次资金流动调用都需要在令牌中使用唯一的 `jti` 以实现幂等性，并在 API 侧使用唯一的 `idempotencyKey`。参见 [幂等性](/docs/idempotency-requests)。
</Note>

***

## 后续步骤

<CardGroup cols={2}>
  <Card title="添加小部件" icon="plus" href="/developers/add-a-widget">
    从模板创建你的第一个应用。
  </Card>

  <Card title="配置 OAuth 与权限" icon="shield" href="/developers/configure-app-widget">
    范围、来源域、重定向 URI、Webhooks。
  </Card>

  <Card title="设置你的服务器" icon="server" href="/developers/setting-up-your-server">
    用你的语言生成预批准交易令牌。
  </Card>

  <Card title="嵌入小部件" icon="code" href="/developers/adding-the-js-widget-to-your-page">
    Script 标签、初始化调用、按钮绑定。
  </Card>

  <Card title="API 的全部能力" icon="sparkles" href="/features">
    全部功能面，均可在服务器端使用。
  </Card>

  <Card title="构建平台" icon="building-2" href="/build-a-platform">
    使用客户范围令牌在关联账户上运行所有能力。
  </Card>
</CardGroup>