總覽 - Fluz

先決條件： 需要具備 CREATE_SHARE_LINK 權限範圍的 Bearer 存取權杖。基本驗證會被拒絕。請聯絡你的業務代表以啟用存取權。請參閱 Authentication。

「託管」/「開放式迴路」的意義。 託管連結會指向 Fluz 託管的啟用頁面。開放式迴路 表示產生的虛擬卡為網路卡（Visa/Mastercard 類型），可依你的方案規則在多家商家使用——而非單一品牌的封閉式禮品卡。

運作方式

你產生連結

以優惠、卡片限額、數量、資金來源與交付方式呼叫 generateVCShareLinks。每個連結代表一張擁有自己限額的卡片，並由你指定的消費帳戶資助。

Fluz 為每個連結建立一筆分享請求

每個連結對應到一筆分享請求（PENDING）和一個託管 URL。

連結被交付

使用 GENERATE_URL 時，你會拿回要自行分發的網址。使用 EMAIL 或 PHONE_NUMBER 時，Fluz 會代你將連結送達每位收件人。

收件人啟用並領取卡片

收件人開啟連結後，以一次性驗證碼驗證手機號碼並設定卡片 PIN——無需下載 App、無需密碼。卡片限額會在領取時自你的消費帳戶扣撥，而非在產生連結時。他們之後可檢視卡片資訊、線上消費，並一鍵把卡片加入 Apple Pay 或 Google Pay。

收件人只會成為該虛擬卡物件的授權使用者——他們不會取得你帳戶、餘額或其他卡片的存取權。觀賞收件人實際體驗流程：桌面版流程 · 行動版流程。 Send cards flow diagram

可用性與範圍

功能	狀態
一次性加值虛擬卡	✅ 支援
單次使用 / 可重複加值卡	❌ 不支援
透過 API 產生連結	✅ 支援
透過 CSV 匯入產生連結	❌ 即將推出
託管型「禮品卡」連結	❌ 不在範圍內（僅限虛擬卡）

卡片分享連結物件類型為 VIRTUAL_CARD，卡片類型為 SINGLE_LOAD。

禮品卡： 儘管更廣泛的計畫以「虛擬卡與禮品卡」為主題，目前沒有託管的禮品卡領取流程。禮品卡餘額只會在此處以「潛在的資金來源」出現（規劃中，尚未啟用）。請僅以虛擬卡進行文件撰寫與開發。

作業參考

共有三個公開作業，全部受 CREATE_SHARE_LINK 權限範圍控管：

作業	類型	目的
`generateVCShareLinks`	Mutation	建立一或多個託管虛擬卡連結
`getVCShareLinks`	Query	列出/檢視先前產生的連結
`deactivateVCShareLinks`	Mutation	停用（使失效）你產生的連結

所有 Send Cards 作業皆在 Fluz GraphQL API 上，POST https://<your-fluz-api-host>/api/v1/graphql，並附上 Authorization: Bearer <access_token> 標頭。權杖必須包含 CREATE_SHARE_LINK 權限範圍——否則每個作業都會回傳「Missing permissions! Please contact your sales rep to get access to generate VC share links.」。

generateVCShareLinks

建立 quantity 筆分享請求，並為每筆請求回傳一個託管連結。

mutation GenerateVCShareLinks($input: GenerateVCShareLinksInput!) {
  generateVCShareLinks(input: $input) {
    shareLinks
  }
}

輸入欄位

欄位	類型	必填	說明
`cardLimit`	`Int!`	是	每張卡的消費上限（亦為加值金額），單位為整數貨幣單位。必須為整數且 ≥ 方案下限。
`offerId`	`String!`	是	卡片綁定之商家優惠的 UUID v4。該優惠必須為啟用狀態，且其商家必須可分享。
`quantity`	`Int!`	是	要產生的連結數量。每個單位會建立一個不同的託管 URL。
`shareMethod`	`ShareMethodType!`	是	連結的交付方式：`GENERATE_URL`、`EMAIL` 或 `PHONE_NUMBER`。
`userCashBalanceId`	`UUID`	是*	用於資助卡片的消費帳戶。雖然在綱要中標示為選填，但實務上為必填——省略會驗證失敗。
`daysUntilExpiration`	`Int`	否	連結到期的天數。最少為 1。若省略，預設為方案預設值（30 天）。此日期同時也會成為卡片的鎖定/凍結日期——詳見 Expiration & freeze。
`recipientListEmail`	`[String]`	條件式	當 `shareMethod = EMAIL` 時為必填且不可為空；長度必須等於 `quantity`。否則必須留空。
`recipientListPhone`	`[String]`	條件式	當 `shareMethod = PHONE_NUMBER` 時為必填且不可為空；長度必須等於 `quantity`。否則必須留空。

資金來源。 目前唯一支援的資金來源為消費帳戶（userCashBalanceId），且必須屬於你（寄件者）的帳戶。其他資金來源（銀行帳戶、銀行卡、預付款/獎勵餘額）尚未開放。

交付方式（`shareMethod`）

值	行為	收件人清單
`GENERATE_URL`	Fluz 在回應中回傳託管 URL。你自行分發。	兩個清單都必須為空/省略。
`EMAIL`	Fluz 代你以電子郵件將連結寄給每位收件人。	需要 `recipientListEmail`；長度必須等於 `quantity`。
`PHONE_NUMBER`	Fluz 代你以簡訊將連結傳給每位收件人。	需要 `recipientListPhone`；長度必須等於 `quantity`。

驗證規則

cardLimit 必須為整數且至少達到方案下限。
offerId 必須為啟用中之優惠且其 商家可分享 的有效 UUID v4。
quantity 必須為整數。
若以 EMAIL 或 PHONE_NUMBER 交付，對應之收件人清單長度必須等於 quantity。若不相符會回傳明確錯誤，且不會建立任何紀錄。
只能提供一個資金來源。userCashBalanceId 必須為寄件者帳戶所擁有的有效 UUID v4。
無效的卡片類型或格式錯誤的輸入會回傳明確錯誤，且不會建立任何紀錄。

範例

{
  "input": {
    "cardLimit": 25,
    "offerId": "11111111-2222-3333-4444-555555555555",
    "daysUntilExpiration": 30,
    "quantity": 3,
    "shareMethod": "GENERATE_URL",
    "userCashBalanceId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
  }
}

{
  "input": {
    "cardLimit": 25,
    "offerId": "11111111-2222-3333-4444-555555555555",
    "daysUntilExpiration": 30,
    "quantity": 2,
    "shareMethod": "EMAIL",
    "recipientListEmail": ["recipient1@example.com", "recipient2@example.com"],
    "userCashBalanceId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
  }
}

{
  "input": {
    "cardLimit": 25,
    "offerId": "11111111-2222-3333-4444-555555555555",
    "daysUntilExpiration": 30,
    "quantity": 2,
    "shareMethod": "PHONE_NUMBER",
    "recipientListPhone": ["+12125550101", "+12125550102"],
    "userCashBalanceId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
  }
}

回應

{
  "data": {
    "generateVCShareLinks": {
      "shareLinks": [
        "https://fluz.app/virtual-prepaid-card/3f8a...c1",
        "https://fluz.app/virtual-prepaid-card/9b2d...77",
        "https://fluz.app/virtual-prepaid-card/0c41...e3"
      ]
    }
  }
}

shareLinks 是託管 URL 的陣列，數量等於 quantity，其格式為 https://fluz.app/virtual-prepaid-card/{share_request_id}。

回應只會回傳 URL。若要擷取你剛建立的連結所需的批次 ID 與 顯示 ID（用於清單與停用），請使用 getVCShareLinks 並以狀態做篩選。

getVCShareLinks

列出先前產生的分享連結，以便你檢視狀態、收件人、到期日與已發行卡片。

query GetVCShareLinks($input: GetVCShareLinksInput!) {
  getVCShareLinks(input: $input) {
    senderAppId
    shareRequestBatchId
    shareRequestDisplayId
    shareObjectStatus
    recipientPhone
    recipientEmail
    linkExpirationDate
    virtualCardId
    linkUrl
    shareRequestDetails {
      cardLimit
      offerId
      daysUntilExpiration
      quantity
      shareMethod
      recipientListEmail
      recipientListPhone
      userCashBalanceId
    }
  }
}

輸入欄位

欄位	類型	說明
`shareObjectStatuses`	`[ShareObjectStatus]`	以狀態篩選：`PENDING`、`ISSUED`、`USED`、`EXPIRED`。
`shareRequestBatchIds`	`[String]`	僅回傳屬於這些批次的連結。
`shareRequestDisplayIds`	`[String]`	僅回傳具有這些顯示 ID 的連結。

建議流程。 第一次呼叫時，僅以 shareObjectStatuses 篩選。回應會提供 shareRequestBatchId 與 shareRequestDisplayId；在後續呼叫（以及停用時）使用這些值做更精準的篩選。

回應欄位（`GeneratedShareLink`）

欄位	類型	說明
`senderAppId`	`String`	產生該連結的應用程式/開發者應用。
`shareRequestBatchId`	`String`	在一次呼叫中產生的所有連結共用的批次識別。
`shareRequestDisplayId`	`String`	針對每個連結的人類可讀識別。
`shareObjectStatus`	`ShareObjectStatus`	`PENDING`、`ISSUED`、`USED` 或 `EXPIRED`。
`recipientEmail`	`String`	若以電子郵件交付，則為收件人信箱。
`recipientPhone`	`String`	若以 SMS 交付，則為收件人電話。
`linkExpirationDate`	`DateTime`	連結到期 / 卡片凍結時間。
`virtualCardId`	`String`	已領取後所發行的虛擬卡 ID。
`linkUrl`	`String`	該連結的託管 URL。
`shareRequestDetails`	`ShareRequestDetails`	原始設定（卡片限額、優惠、數量、交付、資金）。

範例

{ "input": { "shareObjectStatuses": ["PENDING", "ISSUED"] } }

{ "input": { "shareRequestBatchIds": ["ABC123", "XYZ789"] } }

{ "input": { "shareRequestDisplayIds": ["SR-000001", "SR-000002"] } }

deactivateVCShareLinks

停用（使失效）你產生的連結——例如，若批次誤發，或你需要撤銷未被領取的連結。停用連結會將其狀態設為 EXPIRED；未領取的連結將無法再被領取。

mutation DeactivateVCShareLinks($input: DeactivateVCShareLinksInput!) {
  deactivateVCShareLinks(input: $input)
}

輸入欄位

欄位	類型	說明
`shareRequestBatchIds`	`[String]`	停用這些批次中的所有連結。
`shareRequestDisplayIds`	`[String]`	僅停用具有這些顯示 ID 的連結。

從 getVCShareLinks 取得批次 ID。

{ "input": { "shareRequestBatchIds": ["ABC123"] } }

回傳人類可讀的確認字串，例如："3 share requests successfully deactivated!"。

若收件人已經領取連結（狀態為 ISSUED/USED），停用連結不會回收已發行的卡片。若要停止已發行卡片的消費，請使用相應的卡片生命週期/凍結控制。

收件人體驗

當收件人開啟託管連結（https://fluz.app/virtual-prepaid-card/{share_request_id}）時：

進入頁面與登入

收件人會看到帶有寄件商標示的啟用頁面。他們透過 Fluz 驗證入口登入（新收件人在此進行導入）。

雙重驗證

初次載入時，既有使用者會被導向 2FA 畫面。必須完成 2FA 才能檢視或領取卡片。

帳單地址（若需要）

若收件人尚未留存帳單地址，系統會提示新增。線上交易需要帳單地址。

PIN（若尚未發行）

在卡片發行前，收件人需設定 PIN。

卡片發行與領取

系統會建立一張一次性加值虛擬卡並指派給收件人，資金來自寄件者帳戶，鎖定日期等同於連結的到期日。

使用卡片

領取後，收件人可查看卡片資訊、交易紀錄，並（在支援的情況下）將卡片加入行動錢包。

已被領取了嗎？ 若同一位使用者開啟他已領取的連結，會看到自己的卡片資訊。若_不同_使用者開啟已被他人領取的連結，通過 2FA 後會看到拒絕存取的狀態。

到期與凍結

連結的到期日具備雙重用途：

連結到期——在此日期之後，未被領取的連結將無法再被領取。
卡片凍結 / 鎖定日——對於已發行的卡片，此日期為鎖定日（該日結束）。之後卡片會被凍結且無法消費。
卡片有效期限 將對齊凍結日所在月份的月底（例如，凍結日為 2026/6/15，卡片到期為 2026/6/30）。

請在產生時以 daysUntilExpiration 設定期間。若省略，將使用方案預設（30 天）。此日期會顯示給收件人（通常以「有效至」日期呈現）。

應告知收件人的方案規則

以下為託管（開放式迴路）虛擬卡的方案層級規則。請與你的 Fluz 代表確認你的方案之確切數值——部分屬於合作方協議內容。

規則	預設	備註
每日帳戶消費上限	$250,000/日	部分合作夥伴有自訂上限。
餐廳交易緩衝	25%	所有方案皆適用 25% 緩衝（以涵蓋餐廳小費/預授權）。
受限商家/類別	依方案而定	某些商家類別受限。
資金來源	寄件者的消費帳戶	卡片在領取時自寄件者帳戶資助。

收件人客服支援： 1-888-360-6660 · humans@fluz.app

完整的合作夥伴參考文件（術語、含截圖的收件人操作流程、資金補充指引、受限類別與支援）位於 Partner Guide — Hosted URL Virtual Cards。請向你的 Fluz 聯絡窗口索取你方案的最新版本。

狀態與錯誤參考

分享物件狀態

狀態	意義
`PENDING`	已產生連結，尚未被領取。
`ISSUED`	收件人已領取連結；虛擬卡已發行。
`USED`	已發行的卡片已有使用紀錄。
`EXPIRED`	連結到期或被停用；不可再領取。

面向收件人的連結錯誤

條件	收件人所見
連結在被領取前已到期	「Expired before issued」——連結無法再被領取。
寄件者提前停用連結	「Frozen by sender」——連結在到期前被撤銷。
卡片已被領取，且鎖定日已過	「Expired after issued」——卡片已凍結。
不同使用者開啟已被他人領取的連結	「Access denied」。

常見 API 錯誤

成因	結果
缺少/無效的 Bearer 權杖或缺少 `CREATE_SHARE_LINK` 權限範圍	請求被拒絕（未授權）。
收件人清單長度 ≠ `quantity`	明確的驗證錯誤；不會建立任何紀錄。
優惠未啟用、商家不可分享、或無效的 `offerId`	驗證錯誤；不會建立任何紀錄。
缺少/無效的 `userCashBalanceId`，或提供多於一種資金來源	驗證錯誤；不會建立任何紀錄。

備註與限制

回傳的 URL 為託管目的地，而非短連結。 內部也會以短連結服務包裝，但 API 回傳的是標準託管 URL（/virtual-prepaid-card/{share_request_id}）。請原樣分發該 URL。
即使綱要標示為選填，userCashBalanceId 在實務上為必填。
隱藏/內部欄位不屬於此 API。 物件類型與卡片類型是固定的（VIRTUAL_CARD / SINGLE_LOAD），其他資金來源欄位尚未啟用；請勿傳送。
不支援託管型禮品卡連結。 此 API 僅適用於虛擬卡。

下一步

建立大量訂單

一次發行多張卡片以利程式化分發。

​運作方式

​可用性與範圍

​作業參考

​generateVCShareLinks

​輸入欄位

​交付方式（shareMethod）

​驗證規則

​範例

​回應

​getVCShareLinks

​輸入欄位

​回應欄位（GeneratedShareLink）

​範例

​deactivateVCShareLinks

​輸入欄位

​收件人體驗

​到期與凍結

​應告知收件人的方案規則

​狀態與錯誤參考

​分享物件狀態

​面向收件人的連結錯誤

​常見 API 錯誤

​備註與限制

​下一步

建立大量訂單

運作方式

可用性與範圍

作業參考

generateVCShareLinks

輸入欄位

交付方式（`shareMethod`）

驗證規則

範例

回應

getVCShareLinks

輸入欄位

回應欄位（`GeneratedShareLink`）

範例

deactivateVCShareLinks

輸入欄位

收件人體驗

到期與凍結

應告知收件人的方案規則

狀態與錯誤參考

分享物件狀態

面向收件人的連結錯誤

常見 API 錯誤

備註與限制

下一步