Secure Elements 概觀

僅限 Staging，且僅提供揭示功能。 Secure Elements 正在積極開發中。本頁與 Card Reveal 頁面目前皆連線至 Fluz 的 staging 環境 — 生產環境主機尚未確認。本節僅文件化 Card Reveal 能力；實體卡收集（代碼化）尚未涵蓋。

Secure Elements 是什麼

Secure Elements 是一個 JavaScript SDK，@fluz/secure-elements，可將由 Fluz 代管、相互隔離的框架直接掛載進你頁面上的容器元素中。該框架負責渲染卡片資料；你的頁面與伺服器只會持有一個短效、不透明的權杖，用於授權單一次的特定動作。這是展示使用者自身卡片詳細資訊的第三種方式，與你已具備的兩種方式並列：

路徑	卡片資料可讀取的位置	需求條件
`revealVirtualCardByVirtualCardId`	你的自有伺服器，在 API 回應中	`PCI_COMPLIANCE` — 僅授予已證明符合 PCI DSS 規範的開發者，且由 Fluz 管理的 scope。（個人/私人應用程式可豁免。）
Embedded Widget	Fluz 代管的模態框，全螢幕覆蓋你的頁面	除了 OAuth 授權外無需其他條件 — Fluz 擁有整個介面，包含揭示流程。
Secure Elements Card Reveal	由 Fluz 代管的框架，內嵌於你自有版面配置之中	以你現有的 OAuth access token 鑄造的 client token。無需 `PCI_COMPLIANCE` 授權 — 你的頁面不會接收資料，因此不在其合規範圍之內。

若你已經在所有情境下使用 Embedded Widget，就不需要這個工具。Secure Elements 適用於無頭或 API 駆動的整合，仍需向使用者顯示 PAN、到期日與 CVV，但不想開啟完整小工具模態框，或不打算追求 PCI_COMPLIANCE。

運作方式

Your backend  →  mint client token  →  Your frontend  →  SDK mounts Fluz frame  →  callback with result

你的後端鑄造 client token

將你現有的 Fluz OAuth access token 交換成短效的 client token，其範圍限於單次揭示。

你的前端掛載框架

將 client token 交給 @fluz/secure-elements，它會把 Fluz 代管的框架掛載到你提供的容器中 — 直接內嵌於頁面，而非模態框。

SDK 透過回呼回報結果

你的頁面永不讀取原始卡片資料。它只能接收成功、錯誤或掛載事件。

先決條件

你的應用程式已向 Fluz 註冊，且在你的 access token 上啟用了 CREATE_VIRTUALCARD scope。
你擁有狀態為 ACTIVE、且屬於欲揭示之帳戶的虛擬卡 id，將在鑄造 client token 時一併傳入。

在動手寫任何程式碼前，請先請 Fluz 將你的來源網域加入允許清單。 若頁面來源未事先獲 Fluz 核准，框架將拒絕渲染 — 目前沒有自助開關，若延後處理可能會卡關。請寄信至 partnerships@fluz.app（或聯繫你的客戶經理，如有）並提供你的應用程式名稱或 ID，以及需要核准的每個來源網域 — 包含每個你用於開發的 http://localhost:PORT、以及 staging 與 production 網域。Fluz 會在後端加入允許清單；完成後你這端無需額外設定。

環境

環境	基底 URL
Staging	`https://staging.secure.fluz.app`
Production	`https://secure.fluz.app`

在 Fluz 與處理方的整合完成前，Staging 的揭示目前會回傳模擬結果。請使用 staging 以端到端驗證你的整合 — 生產可用性將另行確認。

frameHostOrigin 在 createCardViewer 中為選填 — 省略時預設為生產環境（https://secure.fluz.app）。若要指向 staging，請明確傳入。僅接受上述兩個精確的來源；傳入其他值會在呼叫 createCardViewer 時立即擲出 FluzElementsError（error.code === "INVALID_FRAME_HOST_ORIGIN"），在任何框架掛載前就中止。

載入 SDK

@fluz/secure-elements 不會發佈到 npm — 請以 <script> 標籤從 Fluz 的 CDN 載入瀏覽器全域（IIFE）版本。它會暴露一個 FluzSecureElements 全域：

<script src="https://secure-cdn-staging.fluz.app/secure-elements/v0.1.0/index.global.js"></script>
<script>
  const { createCardViewer } = FluzSecureElements;

  const viewer = createCardViewer({
    /* ... */
  });
</script>

本頁與 Card Reveal 上的每個程式碼範例皆假設你已載入上述的 script 並從 FluzSecureElements 解構所需成員。每次發佈都會提供不可變的鎖定版本路徑（.../v0.1.0/index.global.js）以及一個浮動的 .../latest/index.global.js，永遠指向最新版本。除原型外，請鎖定至特定版本 — latest 可能在未通知的情況下變動。

目前僅 staging 的 CDN 主機上線（secure-cdn-staging.fluz.app）。生產環境的託管將與生產 API 可用性一併確認。

鑄造 client token

你的後端使用你已透過標準 OAuth 授權流程取得的 Fluz OAuth access token 呼叫此端點。切勿將該 access token 傳至瀏覽器 — 僅將此端點回傳的 clientToken / loadToken 配對提供給前端。

POST {baseUrl}/v1/client-token
Authorization: Bearer <your Fluz OAuth access token>
Content-Type: application/json

{
  "purpose": "reveal",
  "virtualCardId": "<uuid>"
}

{ "clientToken": "<token>", "loadToken": "<token>", "expiresIn": 300 }

成功鑄造會回傳 201。兩個權杖皆是單一用途且短效 — 每次揭示都需鑄造一組新配對。clientToken 用於授權實際的揭示（有效期為 expiresIn 秒，預設 300）；loadToken 的範圍更嚴格（60 秒），因為它會出現在 URL 中 — 參見 Card Reveal 的說明 — 且除了載入框架外，將在其他情境被拒絕。直接將兩者傳入 createCardViewer，並切勿自行將 clientToken 放入 URL — SDK 已幫你避免這點。

錯誤回應

狀態碼	錯誤	意義
400	`invalid_purpose`	缺少或無效的 `purpose`
400	`virtual_card_id_required`	針對揭示權杖缺少 `virtualCardId`
401	`unauthorized`	缺少 access token
401	`invalid_token`	access token 驗證失敗（格式錯誤、逾期、簽章不正確）
403	`insufficient_scope`	access token 缺少所需的 scope
403	`app_not_registered`	你的應用程式尚未註冊 — 請聯絡 Fluz
403	`forbidden`	找不到卡片，或該卡片不屬於此使用者
429	`rate_limited`	此使用者的 client-token 請求過多 — 參閱 `Retry-After` 標頭
500	`internal_error`	非預期的伺服器錯誤

欄位樣式設定

createCardViewer 可接受選填的 style 物件，將套用於其掛載的每個欄位：

const viewer = createCardViewer({
  clientToken,
  loadToken,
  frameHostOrigin: "https://staging.secure.fluz.app",
  style: {
    color: "#1a1a1a",
    fontSize: "16px",
    fontWeight: "600",
    fontFamily: "Inter",
  },
});

style 會在任何內容傳至框架前先行驗證。若某個值不符合以下文件規範，await viewer.mount(...) 會以 FluzElementsError（error.code === "INVALID_STYLE"）拒絕 — 若你本身允許可配置的樣式輸入，請以 try/catch 包覆 mount() 呼叫。

屬性	可接受值
`color`	十六進位色碼（`#1a1a1a` 或 `#111`）、`rgb(r, g, b)`，或 CSS 命名色彩（`"slategray"`）
`fontSize`	以 `px`、`pt`、`em`、或 `rem` 結尾的數值（例如 `"16px"`）
`fontWeight`	`"normal"`、`"bold"`，或 `"100"` 到 `"900"` 的 100 倍數
`fontFamily`	精確的系統字型名稱或 Google Font 家族名稱 — 見下方說明

fontFamily 必須與以下兩個允許清單之一完全、區分大小寫地匹配：

系統字型 — 常見的作業系統/安全網頁字型（system-ui、-apple-system、Helvetica Neue、Arial、Georgia、Menlo，以及通用關鍵字 monospace / serif / sans-serif 等）。這些會立即渲染，無需網路請求。
Google Fonts — 任何來自 Google Fonts 目錄的家族（"Roboto"、"Inter"、"IBM Plex Mono" 等），須與 Google 所列之名稱完全相同。SDK 會替你載入字型 — 你不需要 <link> 標籤或 @font-face 規則。

Google Font 會在欄位掛載之後取用，而非事先打包，因此在冷快取的短暫時間內，欄位會先以瀏覽器的後備字型渲染，再切換為你設定的字型。系統字型則不會有此延遲。

若你想自行驗證字型選擇或建立字型挑選器，兩份清單皆有匯出：

const { SYSTEM_FONTS, GOOGLE_FONTS, isAllowedFontFamily } = FluzSecureElements;

isAllowedFontFamily("Roboto"); // true
isAllowedFontFamily("roboto"); // false -- exact, case-sensitive match required

內容安全政策（CSP）

若你的頁面設定了 CSP，請允許你所使用的框架主機：

frame-src https://staging.secure.fluz.app;  # or https://secure.fluz.app in production

安全模型

你的 OAuth access token 永不離開你的伺服器。
前端持有的 client token 是不透明且單一用途 — 它不攜帶任何卡片資料，且無法重播至其他卡片或動作。
卡片資料只會在 Fluz 代管的框架內可讀，並與你頁面自身的 JavaScript 隔離。每個設定的欄位都會以獨立的沙箱（allow-scripts allow-same-origin allow-forms）、referrerPolicy="no-referrer" 的 iframe 掛載 — SDK 絕不會把卡片資料放在其外的 DOM 中。
框架僅會在你已事先向 Fluz 登記的來源網域中渲染。

下一步

卡片揭示

建立卡片檢視器、掛載它，並控制要揭示的欄位。

即時示範

觀看在 staging 上執行的卡片檢視器，包含完整揭示、僅揭示 CVV，以及遮罩模式。

範例整合

可執行的純 HTML 與 React 範例，皆呼叫真實的 staging 基礎設施。

OAuth 應用程式

如何取得你要用來交換 client token 的 access token。

​Secure Elements 是什麼

​運作方式

​先決條件

​環境

​載入 SDK

​鑄造 client token

​欄位樣式設定

​內容安全政策（CSP）

​安全模型

​下一步

卡片揭示

即時示範

範例整合

OAuth 應用程式

Secure Elements 是什麼

運作方式

先決條件

環境

載入 SDK

鑄造 client token

欄位樣式設定

內容安全政策（CSP）

安全模型

下一步