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」之間二選一。大多數整合落在中間地帶，而決定因素通常是你已持有哪些敏感資料，並且是否希望繼續持有。
你把整個使用者旅程交給我們。小工具會處理帳戶建立、手機登入 + 2FA、KYC、PIN 設定、權限授與以及交易確認。你只需渲染一個按鈕並產生簽名權杖。
  • 最快上線途徑 — 以小時計，不是以衝刺（sprints）計。
  • 你的端完全不涉入 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 會成為全攔收件匣。請參見 設定 App 小工具。
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；只移動現金的則不需要。請求較少的範圍代表更短的同意畫面與更高的完成率，因此只要求你需要的。
建立應用程式：新增小工具 · 設定它：設定 App 小工具 · 關閉它：停用或刪除你的應用程式

​
終端使用者會看到什麼

當使用者到達承載你小工具的頁面並觸發開啟彈窗的動作時：
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 與權限

Scopes、origins、redirect URIs、webhooks。

設定你的伺服器

以你的語言產生預先核准交易權杖。

嵌入小工具

Script 標籤、初始化呼叫、按鈕綁定。

API 可做的一切

完整能力面，全部可於伺服器端使用。

打造一個平台

使用具客戶範疇的權杖在連結帳戶上運行所有能力。