- 文件化借記卡在資金流動中的使用方式。從借記卡存入
CASH_BALANCE可能會以帳戶資金交易（AFT）處理，該類交易有其專屬費率 — 請從回應中讀取depositFee，而不是自行計算。推卡提款（method: BANK_CARD）會以原始入帳交易（OCT）送達。卡片對兩者的適用性無法事先得知，且依方向獨立 — 使用者可用於存款的卡片，未必能用於提款。請參考 從外部帳戶存款 與 提領至外部帳戶。 WithdrawCashBalanceInput上的isExpedited現在控制推卡的交付速度：true會立即將資金送至卡片；false或省略則依標準時程結算。標準推卡提款在提交後仍可能失敗，並退回來源餘額 — 因此PENDING的提款尚未最終確定。- 已在 提領至外部帳戶 文件化
getWithdrawFeeEstimate，可在提交提款前預覽fee、netAmount、feePercent、feeMaxCap與settlementDelayDays。 - 更正 提領至外部帳戶：所需 scope 為
MAKE_WITHDRAWAL（非MANAGE_PAYMENT），錯誤代碼為實際的WDR-*/ARG-*/HN-*/BC-*/G-*代碼，且FLUZPAY— 儘管存在於WithdrawMethodsenum 上 — 並非可用的提領方式：withdrawCashBalance會以WDR-0004拒絕，getWithdrawFeeEstimate則以ARG-0001拒絕。
- 交易上的數位錢包訊號。
TRANSACTION_CREATE與TRANSACTION_UPDATEwebhook 事件以及getTransactionsAPI 現在包含digitalWalletProvider（APPLE_PAY、GOOGLE_PAY，或缺省）以判斷卡片交易是否透過行動錢包完成，另有digitalWalletToken（網路代碼 ID）。請以digitalWalletProvider作為錢包使用訊號 —digitalWalletToken也會在非錢包的網路代碼情境下被設定，因此僅其存在不代表使用了錢包。屬於加值且相容變更。請見 Webhooks。
- 開放式卡片（Open Loop Cards）：收件人在初次啟用流程中不再被提示建立 PIN，且卡片在領取時不會自動揭露。如今揭露卡片會提示收件者輸入其 PIN；若尚未設定，則會引導建立。請見 收件者體驗。
- 更新 Open Loop Cards 的 GenerateVCShareLinksInput。請見 Open Loop Cards。
- 更新了 主要與備用資金來源頁面。
GiftCard.purchaseId(UUID) — 建立該禮品卡的購買；與purchaseGiftCard與getUserPurchases回傳的相同 ID。若無關聯購買則回傳null。GiftCard.purchaseDisplayId(String) — 簡短、易讀的 Fluz 交易 ID（例如1047283），支援在人工審查與匯出時參照。若無關聯購買則回傳null。GiftCard.purchaseValue(Float) — 在該卡幣別中的購買面額（denomination）。GiftCard.currentValue(Float) — 禮品卡剩餘餘額；對於單次使用卡等於purchaseValue。GiftCard.currency(String) — 禮品卡面額的 ISO 貨幣代碼（例如USD）。
getGiftCards（以及任何暴露 GiftCard 的地方）會回傳以上五個欄位，使你不必對每張卡呼叫 revealGiftCardByGiftCardId 即可進行訂單/金額對帳。屬於加值且相容變更。- 新增 Plaid Link 支援。
- 使用
llms.txt資訊更新 Overview 頁。 - 更新頁首，新增指向
llms.txt的 AI 連結。
- 新的
getCardProvisioningUrlquery — 產生短效、一次性 URL，於行動裝置開啟時會啟動 Fluz 並將虛擬卡新增至 Apple Pay（iOS）或 Google Pay（Android）。可顯示為 QR code、SMS、email 或 App 內按鈕。每個 URL 於建立後約 5 分鐘失效。需要CREATE_VIRTUALCARDscope。 - 新增輸入
GetCardProvisioningUrlInput { offerId, platform }。 - 新的 enum
ProvisioningPlatform（IOS|ANDROID|OTHER）— 僅影響桌面/未知裝置的後備流程；iOS 與 Android 的開啟會自動導向。 - 新的回傳型別
CardProvisioningUrl { url, expiresAt }。
- 新增
addVirtualCardAddressmutation 以儲存發行虛擬卡所需的帳單地址。 - 更新
createVirtualCardmutation 以支援代表授權使用者建立卡片。 - 新增完整流程，使用
registerUser、addAuthorizedUser、addVirtualCardAddress與createVirtualCard。 - 針對帶有
VC-0020與回傳addressId的發卡行待審核可重試。
redeemFluzGiftCard— 使用代碼兌換 Fluz 禮品卡。入帳至giftCardCashBalance。需要MAKE_DEPOSIT。請見 兌換 Fluz 禮品卡。unlockVirtualCard— 解除先前鎖定的虛擬卡以恢復交易能力。需要EDIT_VIRTUALCARD。請見 解除鎖定虛擬卡。
交易相關的 webhooks
- 新增
TRANSACTION_CREATE、TRANSACTION_UPDATE與TRANSACTION_DECLINEwebhook 的說明。 - 納入 webhook enrichment 後的新欄位（與 MCC 相關、
virtualCardId等）。
- 在
VirtualCardTransaction新增mcc、merchantCountryCode、originalCurrencyCode、originalCurrencyAmount與currencyConversionRate。現在由getVirtualCardTransactions回傳。 getVirtualCardTransactions的virtualCardIds改為選填 — 省略即可查詢已驗證帳戶下所有卡片的交易。新增dateRangeStart與dateRangeEnd篩選。當省略virtualCardIds時預設limit為 100；limit上限為 500。對於無結算金額的紀錄（例如僅 AVS 拒絕紀錄），transactionAmount現在可為 null。- 在
CreateVirtualCardInput新增usePrepaymentBalance與useRewardsBalance。createVirtualCard現已接受。兩者預設為true（維持既有行為）。將兩者皆設為false可限制卡片僅自指定的userCashBalanceId提領資金，排除預付（禮品卡）與獎勵資金。
- 新增
shortDescription（Merchant）與termsAndConditions（Offer）。現在由getMerchants與getOfferQuote回傳。 - 新增
deliveryFormat（GiftCard）。現在由getGiftCards回傳 — 請對已購買卡片使用deliveryFormat。
- 新增
getUserCashBalances與getUserCashBalanceByIdqueries。這些查詢允許使用者檢索其消費帳戶清單以及帳戶上建立的特定消費帳戶。
分享虛擬卡 API
- 「管理虛擬卡」下新增「分享虛擬卡」功能。請聯絡業務以取得存取權。
- 在 應用程式 scopes 頁面新增
CREATE_SHARE_LINKscope。
商業註冊 API
- 新增查詢
getBusinessCategories: [BusinessCategory]以取得商業類別，並包含回應型別BusinessCategory與BusinessSubCategory。 - 新增 mutation
registerBusiness(input: RegisterBusinessInput!): RegisterBusinessResult以程式化完成商業註冊。 - 新增輸入型別：
RegisterBusinessInput、BusinessLegalAddressInput、BusinessOwnerInput、OwnerAddressInput。 - 新增 enums：
BusinessStructure（LLC、CORPORATION、PARTNERSHIP、SOLE_PROPRIETORSHIP、COOP）與BusinessAccountUsage。 - 新增回應型別：
RegisterBusinessResult { accountId, kybStatus, success, error }與RegisterBusinessError { message, code }。 - 兩個操作皆需具備
REGISTER_BUSINESSOAuth scope 的驗證。
getMerchants 查詢更新getMerchants查詢現在能正確回傳所有可用的 offers。getMerchants查詢現在可在offers物件中回傳exclusiveRateId欄位。此值可於purchaseGiftCard中指定為你要購買的專屬費率 offer。
提領與消費帳戶 API
- 新增
withdrawCashBalancemutation，需具備MAKE_WITHDRAWALscope。 - 新增
WithdrawMethodsenum，支援PAYPAL、BANK_ACH、BANK_CARD與VENMO方法。 - 新增
WithdrawSourceenum，支援CASH_BALANCE與REWARDS_BALANCE來源。 - 新增
WithdrawCashBalanceInput，支援冪等性，另有Withdraw與WithdrawCashBalanceResponse型別，包含完整的提領紀錄細節（含費用、狀態與時間戳）。 - 新增
transferUserCashBalancemutation，需具備MAKE_INTERNAL_TRANSFERscope，並新增TransferInternalBalanceInput與TransferInternalBalanceResponse型別。 - 在
EditVirtualCardInput新增userCashBalanceId，以便透過editVirtualCard將資金來源變更為指定的消費帳戶。 - 在
TransactionFilterInput新增userCashBalanceIds以便透過getTransactions依消費帳戶篩選交易，並在getGiftCards新增userCashBalanceId以依消費帳戶篩選禮品卡。 - 新增
updateUserCashBalance與closeUserCashBalancemutations，需具備MANAGE_PAYMENTscope，並新增支援的輸入與回應型別（UpdateUserCashBalanceInput、CloseUserCashBalanceInput、CloseUserCashBalanceResponse、ClosedUserCashBalance、CloseUserCashBalanceResponseVirtualCard）。 - 新增應用程式動作記錄以供稽核追蹤。
- 在
getWallet查詢的UserBalances型別新增userCashBalances欄位。透過paginate（limit/offset）回傳個別使用者現金餘額帳戶的詳細資訊，並依建立日期排序（最新在前）。包含userCashBalanceId、totalCashBalance、availableCashBalance、lifetimeCashBalance、nickname、status與createdAt— 讓你能追蹤每位使用者的多個現金餘額帳戶，含自訂暱稱與狀態監控。
- 在
DepositCashBalanceInput新增userCashBalanceId欄位，以指定要將資金存入的現金餘額（消費帳戶）。
- 新增管理已儲存銀行卡的 mutations：
updateBankCardNickname、updateBankCardPreferredMerchantCategoryCode與deleteBankCard，以及相對應的輸入型別。 - 在
BankCard型別新增nickname欄位。 - 在
AddBankCardInput新增選填欄位：nickname與preferredMerchantCategoryCode（MCC，正規化為 4 位數）。
getVirtualCardBalance：新的查詢，可檢索一組虛擬卡的餘額資訊，包括spentAmount、remainingBalance、spendLimit與spendLimitDuration。getVirtualCardTransactions：新的查詢，可檢索一組虛擬卡的交易，並提供如transactionTypes等篩選條件。
getUserPurchases查詢現在包含新的選填變數UserPurchaseFilterInput，可篩選回應中的購買紀錄。可篩選使用者所做、帳戶所做，或兩者皆包含的購買。
revealVirtualCardByVirtualCardIdmutation 的回應現在包含新的authorizationSetting欄位。- 大量虛擬卡 API：新增可非同步建立與管理大量虛擬卡的 API。
createVirtualCardBulkOrdermutation：提交大量訂單並取得唯一的orderId。getVirtualCardBulkOrderStatusquery：透過輪詢追蹤訂單狀態，並在完成後取得卡片詳細資料。- 大量卡片建立為非同步流程 — 請檢查訂單狀態以取得卡片詳細資料。
- 新查詢
getVirtualCardOffers：完整列出所有可供建立的活動虛擬卡 offers，包括offerId（建立卡片必需）、programName、bankName、rewardValue與詳細的計畫限制（每日、每週、每月消費上限）。 - 更新 mutation
createVirtualCard：透過提供offerId（來自getVirtualCardOffers）、spendLimit與可自訂屬性如cardNickname、spendLimitDuration，以程式化發行虛擬卡。 - 新 mutation
editVirtualCard：更新既有虛擬卡的關鍵參數 —spendLimit、spendLimitDuration、lockDate、lockCardNextUse與cardNickname。 - 新 mutation
lockVirtualCard：立即鎖定虛擬卡，阻止任何後續交易。
getMerchants回應中的Offer型別現包含deliveryFormat欄位，指定 offer 的兌付方式：URL、CODES、PIN_AS_CODE或PIN_WITH_URL。getMerchants查詢新增filterBy參數，允許你僅回傳其 offers 符合特定deliveryFormat的商家。
- 強化
getMerchants查詢，新增offerTypes輸入參數，允許依giftCardOffer、cardLinkedOffer或兩者皆有進行篩選。預設情況下，若未提供offerTypes，查詢僅回傳禮品卡 offers。
- 新增查詢
getReferralUrl，可根據商家輸入回傳推薦字串，並新增MerchantInput型別。 - 在
purchaseGiftCardmutation 上新增自動重購嘗試。若使用銀行卡、銀行帳戶或 PayPal 購買禮品卡失敗，系統會自動嘗試改用 Fluz 餘額再購買。 - 在
PurchaseGiftCardInput新增defaultToBalance欄位，當主要付款方式失敗時，設定以 Fluz 餘額作為後備付款方式。預設為true。
- 新增存取 scope：
CREATE_VIRTUALCARD，用於建立虛擬卡。 - 新增函式
createVirtualCard，可依特定參數建立虛擬卡。 - 新增查詢
getBINs，以取得與虛擬卡相關的 BIN。 - 在現金餘額存款加入
merchantCategoryCode輸入，以強化交易分類。 - 新增查詢
getMccList，以取得商家類別代碼清單。 - 強化
getApplicationScopes查詢的 scope 驗證，並改善 GraphQL 型別定義管理。
- 加強商家 offer 的庫存資訊處理：
Offer物件的stockInfo欄位現在會依固定或可變 offer 分別回傳StockInfoFixedType或StockInfoVariableType。 - 強化錯誤處理並提供更直覺的錯誤訊息 — 改善
purchaseGiftCard無 offer 錯誤與帳戶與付款方式不符的回應。
v0.0.21
- 在
depositCashBalance與purchaseGiftCards新增idempotencyKey參數，以防止重複請求。 - 新增
purchaseGiftCardInput型別，以精簡交易參數處理。 - 在
UserPurchase型別新增purchaseDisplayId欄位，提供購買的顯示 ID。 - 修正
Offer物件的offeringMerchantId欄位，改為回傳offering_merchant_id，而非offer_id。
- 在
generateUserAccessToken新增accountId必填要求。 - 實作新查詢
getAccountsByUserId，可依userId取回帳戶。 - 新增
AccountTypeenum，將帳戶分類為CONSUMER或BUSINESS，並新增Account、Business、Seat物件。
- 修正
depositCashBalance平台通道輸入，使存款交易記錄的來源記為API。