小工具到底是什麼
Fluz Widget 是一個代管、由 Fluz 渲染的流程，你只需幾行 JavaScript 就能嵌入到自己的網站。它會在你的網域、你的品牌之下執行——可以是覆蓋在頁面上的模態視窗，或是（目前僅限測試環境）以你自行設定大小的容器內嵌呈現。 它的存在是為了處理三件你不該自己重造的工作：收集使用者授權
小工具是最終使用者建立或登入其 Fluz 帳戶並授予你的應用程式在該帳戶上行動所需的 scopes 的方式。沒有授權，就沒有 API 存取。
擷取敏感資料
卡號、SSN、身分證明文件與 PIN 由 Fluz 在 Fluz 的 PCI DSS 環境內收集，並在我們這一側加密。這些資料永遠不會觸及你的伺服器。
確認資金移動
使用者會在可被信任的介面中看見並核准轉帳的金額與方向，這正是將預先授權權杖轉化為已完成交易的關鍵。
心智模型： 小工具是一個_同意與敏感資料的介面_，而不是一個產品。它處理的是流程中狹窄且高合規的部分。真正的工作發生在 API。
分工方式
你可以在幕後完成所有動作
這是大家最常忽略的一點：小工具不是使用 Fluz 的唯一方式，也不是大多數工作執行的主要路徑。 一旦使用者已經授予你的應用程式 scopes——無論是透過小工具還是獨立的 OAuth 授權流程——你的伺服器就持有使用者的存取權杖。從那一刻起，API 功能頁面上列出的每個能力都可由你以程式方式使用，不需要開啟小工具，也不需要使用者在場：資金來源
連結銀行卡與 Plaid 銀行帳戶，之後可隨需提取資金。
錢包與轉帳
開立消費帳戶、存入、提領，並在內部或跨帳戶移動資金。
虛擬卡
消費控制、鎖定/解鎖、PIN、錢包載具佈建、批量核發。
Open loop 卡
產生由收件者認領的代管卡片連結，並擁有完整的連結生命週期控管。
匯款
以電話或 email 搜尋收款人並轉帳至其他 Fluz 錢包。
核准與授權使用者
新增團隊成員、為其核發卡片並配置核准路由。
選擇要交給我們多少流程
你不必在「全用小工具」與「全用 API」之間二選一。多數整合都介於兩者之間，決定因素通常是你已持有哪些敏感資料，且是否希望繼續自行持有。- 完整小工具
- 混合（最常見）
- 無頭 / 僅 API
你把整個使用者旅程交給我們。小工具處理帳號建立、手機 + 2FA 登入、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 會成為全捕捉（catch-all）。請見設定應用程式小工具。
3
使用者設定下限（使用者 scopes）
小工具開啟時，使用者會看見你請求的 scopes——以可讀的頂層標題分組，而非原始的列舉值——並加以核准。任何被拒絕的項目都不會被授與。
4
兩種授與都必須有效
應用程式的實際權限是應用程式層級授與與使用者層級授與的交集，且兩者都必須未過期。這在
generateUserAccessToken 階段被強制檢查，而非在呼叫時——因此撤銷或過期的授與會表現為權杖產生失敗，而不是流程中段莫名其妙的錯誤。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
更多
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，移除不需要的。未來要代表使用者發卡的撥款小工具需要
CREATE_VIRTUALCARD；只移轉現金的則不需要。請求越少 scopes，授權畫面越短、完成率越高，因此只要你需要的，不多要。最終使用者會看到什麼
當使用者抵達承載你小工具的頁面並採取會開啟模態的動作後：1
登入或註冊
使用者以傳送到其手機的 2FA 驗證碼登入其 Fluz 帳戶。若沒有帳戶，會在此處建立。於
patToken 傳入 phoneNumber 可直接跳到輸入驗證碼步驟。2
KYC
若你已持有使用者的 SSN，將其傳給我們以供驗證。否則，小工具會執行完整的 KYC 流程。回應可能為
APPROVED、DECLINED、DUPLICATE 或 ERROR——各狀態意義與使用者可嘗試次數請見使用者 KYC 驗證。3
授與權限
使用者檢視並核准你的應用所請求的 scopes。
4
設定 PIN
Fluz 範圍內的安全措施，之後在需要高層級確認的操作時也會再次要求。
5
確認交易
使用者會看到金額與方向，然後選擇核准或關閉。無論結果如何，你都會收到事件。
Pay-In：資金流入你的平台
先檢查使用者的 Fluz 餘額以確認其能支付此次交易。
- 使用者輸入存入金額並點擊你的按鈕。
- 小工具呈現確認畫面。
- 已確認 → 我們會自使用者的消費帳戶向你的帳戶發起轉帳。
- 已拒絕或關閉 → 我們會送出事件。
- 你會收到完成或失敗事件。
- 驗證你的 Fluz 餘額以確認結算。
Payout：資金流向你的使用者
請先檢查你帳戶的 Fluz 餘額。若無法覆蓋此次轉帳，請自你的資金來源發起存入。在你這一側隔離或保留使用者資金，以防轉帳進行期間的重複支出。
- 使用者輸入提領金額並點擊你的按鈕。
- 小工具呈現確認畫面。
- 已確認 → 我們會自你的營運消費帳戶向使用者帳戶發起轉帳。
- 已拒絕或關閉 → 我們會送出事件。
- 你會收到完成或失敗事件。
- 小工具會顯示給使用者其提領已完成，並提供直接存取其 Fluz 虛擬卡。
每個移動資金的呼叫都需要在權杖中使用唯一的
jti 以確保冪等性，並在 API 端使用唯一的 idempotencyKey。請見冪等性。下一步
新增小工具
從範本建立你的第一個應用。
設定 OAuth 與權限
Scopes、origin、redirect URI、webhook。
設定你的伺服器
以你的語言產生預先核准交易權杖。
嵌入小工具
Script 標籤、初始化呼叫、按鈕綁定。
Enrollment 小工具
以你選定的順序執行 KYC、資金來源與 PIN。僅限測試環境。
Secure Elements
在你的頁面中內嵌顯示卡片細節，無需小工具模態。
終止工作階段
在使用者完成前，取消你已交付的小工具付款。
API 的全部能力
完整能力面，全部可於伺服器端使用。
打造平台
以客戶範圍的權杖在連結帳戶上執行每項能力。