Skip to main content
標準託管連結流程 將所有步驟交由收件人處理：你建立一個連結，Fluz 只會在收件人開啟連結、通過驗證並完成領取後才建立虛擬卡。 此流程則針對你已經識別的收件人相反運作。你先用 registerUser 自行註冊收件人的身分與帳單地址，然後使用 generateVCShareLinks 並設定 shareMethod: EXISTING_USER 來產生分享連結。Fluz 會在連結產生時立即建立虛擬卡，而不是在領取時，並將其綁定到該唯一收件人。連結的傳送與領取仍與一般流程相同；只是卡片建立時間點提前。資金仍然在領取時扣款，與標準流程相同——優先從 userCashBalanceId 扣款，若消費帳戶餘額不足，且已啟用，則回退使用你的預付款或獎勵餘額。
何時使用此方式，而非一般分享連結
  • 你已確知收件人是誰（以 user ID 表示），並希望在通知他們前卡片就已建立完成，而非等待他們領取。
  • 你需要嚴格保證只有目標收件人能檢視該連結——而非「第一個點擊的人」。
  • 你要發送給一批已知收件人，並需要在收件人與卡片之間建立可預期的 1:1 對應關係。

​
開始前

你需要 Bearer access token。兩個操作皆不接受基本驗證（Basic auth）。
使用者註冊預設不啟用。 registerUser 是受限的 mutation —— 你的應用程式必須先經 Fluz 明確核准，才能建立使用者。請聯絡你的 Fluz 業務代表或客戶經理以啟用此功能。 來自未核准應用程式的呼叫會失敗並回應 AUTH-0022。若收件人已擁有 Fluz 帳戶，你可以略過註冊，直接使用 generateVCShareLinks 並提供其既有的 recipientUserIds。
請參考驗證以產生具備必要範圍的權杖。

​
流程

1

註冊收件人

使用 registerUser 傳入收件人的個人資料、其帳單地址，以及其對持卡人合約的同意。
acceptCardholderAgreement 必須為 true —— 否則註冊會被拒絕。註冊失敗會以 HTTP 200 回傳，但 success: false，而非出現在 GraphQL errors 陣列中；請務必檢查 success。保留回傳的 userId —— 你會在下一步把它傳入 generateVCShareLinks。同時也會回傳 accountId 與 billingAddressId，但此流程不需要用到。
此步驟不會建立卡片或持卡人合約。 它只會建立使用者紀錄、儲存帳單地址，並記錄其已同意合約。虛擬卡與收件人對該卡片的綁定皆於下一步建立。
AUTH-0026 與 AUTH-0027 並非失敗。 它們代表此人已擁有 Fluz 帳戶——很常見，因為 Fluz 帳戶並不侷限於你的應用程式。請略過註冊，直接使用其既有的 user ID。
參數完整參考：registerUser。
2

產生分享連結

使用 shareMethod: EXISTING_USER 呼叫 generateVCShareLinks，並在 recipientUserIds 中填入註冊返回的使用者 ID（或其他已知的 Fluz 使用者 ID）。recipientUserIds 的長度必須等於 quantity。
若有多位收件人，請每張卡片提供一個使用者 ID——順序會與產生的連結一一對應：
請不要設定 recipientListEmail 與 recipientListPhone —— 在此 shareMethod 下，收件人以 recipientUserIds 識別，且 Fluz 已擁有每位已註冊使用者的聯絡方式。你可以選擇將 usePrepaymentBalance 與/或 useRewardsBalance 設為 true，讓 Fluz 在 userCashBalanceId 無法於領取時涵蓋全額時，改由你的預付款或獎勵餘額作為後援扣款：
With fallback funding
詳見資金來源。
3

Fluz 建立卡片並指派連結

與標準流程不同，虛擬卡會在此刻、也就是產生時建立，而不是延後到領取時。當呼叫返回時，收件人就已被指派到該卡片及其連結。資金仍在領取時扣款，與標準流程相同——主要從 userCashBalanceId 扣款；若你有設定 usePrepaymentBalance / useRewardsBalance 且消費帳戶餘額不足，將回退使用你的預付款或獎勵餘額。每個回傳的連結都被鎖定於其指定的收件人：只有該收件人的 Fluz 帳戶能開啟並領取。若其他使用者開啟該 URL，登入後會看到拒絕存取的狀態，與任何其他已綁定的連結相同。
4

連結已送達

連結將以與任何託管連結相同的方式傳送給收件人——透過 SMS 或電子郵件，使用 Fluz 檔案中該使用者的聯絡方式。之後收件人登入、完成 2FA，並進入其卡片頁面。由於卡片已存在，領取時不會再提示輸入帳單地址或等待卡片發卡——此時會完成資金扣款，與標準流程相同。

​
與標準流程的差異

請參考傳送 Open Loop Cards 了解標準流程，並參考收件人體驗 以取得完整領取操作說明。

​
注意事項與限制

  • recipientUserIds 必須指向既有的 Fluz 使用者。 若收件人尚未註冊，請先以 registerUser 註冊（本流程），或使用標準託管連結流程，讓 Fluz 在領取時為其導引。
  • recipientUserIds 的長度必須等於 quantity。 若不相符，會回傳驗證錯誤且不會建立任何紀錄。
  • 僅卡片建立時間提前——資金扣款不變。 虛擬卡物件與收件人綁定會在你呼叫 generateVCShareLinks 時建立，但資金仍在領取時扣款，與標準流程相同：先自 userCashBalanceId 扣款；若你設定了 usePrepaymentBalance / useRewardsBalance 且消費帳戶不足，則回退使用你的預付款或獎勵餘額。
  • 註冊權限以應用程式與環境為範圍。 在測試環境獲准的權限不會自動套用到正式環境。請參考部署到正式環境。
  • 切勿在測試環境註冊真實個人。 請參考Staging 與 Live。

​
下一步

傳送 Open Loop Cards

標準流程——產生連結，並在領取時由 Fluz 發卡。

收件人體驗

收件人在開啟並領取託管連結時所見與操作的流程。

註冊顧客

registerUser 的完整參考，包括錯誤處理與後援模式。