Virtual Card Return事件現在會帶有isReversal：授權保留被釋放時為true（無論由發卡機構或 Fluz 釋放），商家退款時為false。2026-09-25 20:15 UTC 之前推送的退回不帶此值；對於這些事件，以及少數我們仍無法分類的退回，請依撤銷與退款所述，透過referenceId與原始授權來分辨已釋放的保留與退款。屬於加成且向後相容。
- 商家分類現在可透過 API 取得，不再需要匯出 CSV 來顯示或依分類篩選。
getMerchants在每個商家上回傳categories——為清單，因為一個商家可屬於多個分類；若未分類則為空——並接受categoryId參數以僅回傳屬於單一分類的商家。新的getMerchantCategories查詢列出分類及其 id，與 Fluz 型錄中使用的分類法相同。分類 id 具穩定性，若你快取對應關係，請儲存 id 而非名稱。兩者都需要LIST_OFFERS權限範圍。屬於加成且向後相容。請參考 Get Catalog。
- 新的 webhook 事件
FUNDING_SOURCE_STATUS_UPDATE，目前僅在staging提供——尚未於 production 投遞。當使用者新增、重新命名或移除資金來源時觸發。單一事件類型涵蓋三種情況——請依changeType（ADDED、UPDATED、DELETED）分支，而非依事件名稱。承載的內容包含fundingSourceId、fundingSourceType（BANK_ACCOUNT、BANK_CARD、PAYPAL）、brand、lastFour、nickname、status與時間戳；絕不包含完整卡號與帳號。需要LIST_PAYMENT權限範圍，且會投遞給私有應用與 OAuth 應用。事件是由資金來源本身的變更所發出，因此不論使用者是在行動 App、網頁 App，或嵌入式小工具上變更，都會觸發。使用者的 Fluz 現金餘額不是資金來源，且不會產生事件。請參考 Webhooks。
- 交易 webhook 現在攜帶
isReversal。對於授權沖正為true，對於被我們分類為其他類型之交易為false，而當我們無法分類時則缺席。出現在TRANSACTION_CREATE、TRANSACTION_UPDATE與TRANSACTION_DECLINE。覆蓋範圍仍為部分：目前只有卡片驗證的作廢會被標記為true，退貨則完全不帶值，因此此欄位尚無法分辨已釋放的預授權與商家退款。將缺席視為未知，切勿視為false。屬於加成且向後相容。請參考 Webhooks。
createTransfer與requestAccountTransfer的輸入型別現在接受選用的useRewardsBalance。當為true時，匯款除了使用解析出的消費帳戶，亦會動用寄件者的獎勵餘額（先用現金，剩餘以獎勵補足）。省略或傳false以維持既有的僅現金行為。這些 mutations 沒有預付款欄位。屬於加成且向後相容。請參考 Fund account transfers with rewards。
getUserPurchases現在在其filter參數上接受purchaseDisplayId，因此你可以用購買時回傳的參考 ID 來擷取單一訂單，而不必分頁遍歷歷史紀錄。該值與getTransactions上的referenceId相同，且購買紀錄在單一呼叫中就攜帶完整細節——用於現金回饋的seatRewardValue、付款拆解，以及關聯的giftCard。此篩選在scope之上套用，只會進一步縮小結果。scope值以 AND 結合，因此同時傳入TOKEN_USER與TOKEN_ACCOUNT僅會回傳該權杖的使用者在該權杖的帳戶上所做的購買——若僅以TOKEN_ACCOUNT作為scope，則其他使用者下的訂單也會回傳。屬於加成且向後相容。請參考UserPurchaseFilterInput。
getVirtualCardBalance現在除了消費數據外，還會回傳status、locked與authorizationSetting，因此你可以在一次呼叫中讀取多張卡片的狀態，而不必對每張卡都呼叫revealVirtualCardByVirtualCardId並觸發發卡方的速率限制。被鎖定的卡仍會回報status: ACTIVE，因此請使用locked，其涵蓋持卡人自行鎖定、Fluz 於鎖定日期後鎖定，以及 Fluz 客服鎖定。authorizationSetting與 reveal 回傳的物件相同。屬於加成且向後相容。請參考 Get Virtual Card Balance。
- 說明金融卡用於資金移動的方式。從金融卡存入
CASH_BALANCE可能會以帳戶資金交易（AFT）處理，其有獨立的手續費率——請從回應讀取depositFee，而非自行計算。推送至卡的提領（method: BANK_CARD）會以原始入帳交易（OCT）送達。卡片對於存入與提領兩個方向的適用性無法事先得知，且彼此獨立——使用者可存入的卡片不一定能作為提領目的地。請參考 Deposit From External Accounts 與 Withdraw to External Account。 WithdrawCashBalanceInput上的isExpedited現在控制推送至卡的交付速度：true立即送達卡片，false或省略則以標準時程結算。標準的推卡提領在提交後仍可能失敗，並退回來源餘額——因此PENDING的提領尚未定案。- 在 Withdraw to External Account 文件中補充了
getWithdrawFeeEstimate用於在提交前預覽fee、netAmount、feePercent、feeMaxCap與settlementDelayDays。 - 更正 Withdraw to External Account：所需 scope 為
MAKE_WITHDRAWAL（非MANAGE_PAYMENT），錯誤代碼為實際的WDR-*/ARG-*/HN-*/BC-*/G-*，且雖然FLUZPAY存在於WithdrawMethods列舉中，但不是可用的提領方法：withdrawCashBalance會以WDR-0004拒絕，getWithdrawFeeEstimate則以ARG-0001拒絕。
- 交易上的數位錢包訊號。
TRANSACTION_CREATE與TRANSACTION_UPDATEwebhook 事件以及getTransactionsAPI 現在包含digitalWalletProvider（APPLE_PAY、GOOGLE_PAY，或缺席），讓你能辨識卡片交易是否透過行動錢包進行，另外還有digitalWalletToken（網路代碼 token id）。請以digitalWalletProvider作為錢包使用的訊號——digitalWalletToken在非錢包的網路代碼情境也會被設定，因此僅憑其存在並不代表有使用錢包。屬於加成且向後相容。請參考 Webhooks。
- Open Loop Cards：收件人在初次啟用流程中不再被要求建立 PIN，且卡片在領取時不再自動揭露。現在揭露卡片時會提示收件人輸入其 PIN，或在尚未設定時建立 PIN。請參考 Recipient Experience。
- 更新 Open Loop Cards 的 GenerateVCShareLinksInput。請參考 Open Loop Cards。
- 新的 API 端點，揭露與帳戶相關的拒絕交易。請參考 Get Declined Transactions。
GiftCard.purchaseId（UUID）——建立該禮品卡的購買；與purchaseGiftCard與getUserPurchases回傳的相同 ID。若無關聯購買則回傳null。GiftCard.purchaseDisplayId（String）——簡短、易讀的 Fluz 交易 ID（例如1047283），客服在手動審查與匯出時會引用。若無關聯購買則回傳null。GiftCard.purchaseValue（Float）——購買禮品卡時的票面金額（面額），以該卡幣別計。GiftCard.currentValue（Float）——禮品卡剩餘餘額；對於單次使用卡等於purchaseValue。GiftCard.currency（String）——禮品卡價值的 ISO 貨幣代碼（例如USD）。
getGiftCards（以及所有暴露 GiftCard 的地方）回傳，使你無需對每張卡呼叫 revealGiftCardByGiftCardId 即可進行訂單／金額對帳。屬於加成且向後相容。- 新增 Plaid Link 支援。
- 更新 Overview 頁面，加入
llms.txt資訊。 - 更新頁首，加入指向
llms.txt的 AI 連結。
- 新增
getCardProvisioningUrlquery——產生一個短效、單次使用的 URL，於行動裝置開啟時，會啟動 Fluz 並將虛擬卡加入 Apple Pay（iOS）或 Google Pay（Android）。可以 QR 碼、簡訊、電子郵件或應用內按鈕方式呈現。每個 URL 於建立後約 5 分鐘失效。需要CREATE_VIRTUALCARD權限範圍。 - 新增輸入
GetCardProvisioningUrlInput { offerId, platform }。 - 新增列舉
ProvisioningPlatform（IOS|ANDROID|OTHER）——僅影響桌面／未知裝置的後備流程；iOS 與 Android 的開啟會自動導向。 - 新增回傳型別
CardProvisioningUrl { url, expiresAt }。
- 新增
addVirtualCardAddressmutation 以儲存虛擬卡發卡所需的帳單地址。 - 更新
createVirtualCardmutation 以支援代授權使用者建立卡片。 - 新增使用
registerUser、addAuthorizedUser、addVirtualCardAddress與createVirtualCard的完整流程。 - 對於發卡方待審中且回傳
VC-0020與addressId的情況，允許重試。
redeemFluzGiftCard——使用代碼兌換 Fluz Gift Card。入帳至giftCardCashBalance。需要MAKE_DEPOSIT。請參考 Redeem a Fluz Gift Card。unlockVirtualCard——解鎖先前被鎖定的虛擬卡以恢復交易能力。需要EDIT_VIRTUALCARD。請參考 Unlock a Virtual Card。
交易相關的 webhooks
- 新增
TRANSACTION_CREATE、TRANSACTION_UPDATE與TRANSACTION_DECLINEwebhook 的描述。 - 納入 webhook 擴充後的新欄位（與 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。
- 新增
setVirtualCardPINmutation，允許使用者在符合資格的虛擬卡上設定 PIN。請參考 Set a Virtual Card PIN。
- 新增
getUserCashBalances與getUserCashBalanceById查詢。這些查詢允許使用者擷取其消費帳戶清單與在其帳戶上建立的特定消費帳戶。
企業註冊 API
- 新增查詢
getBusinessCategories: [BusinessCategory]以擷取商業分類，並新增回應型別BusinessCategory與BusinessSubCategory。 - 新增 mutation
registerBusiness(input: RegisterBusinessInput!): RegisterBusinessResult以程式化方式進行企業註冊。 - 新增輸入型別：
RegisterBusinessInput、BusinessLegalAddressInput、BusinessOwnerInput、OwnerAddressInput。 - 新增列舉：
BusinessStructure（LLC、CORPORATION、PARTNERSHIP、SOLE_PROPRIETORSHIP、COOP）與BusinessAccountUsage。 - 新增回應型別：
RegisterBusinessResult { accountId, kybStatus, success, error }與RegisterBusinessError { message, code }。 - 兩個操作都需要
REGISTER_BUSINESSOAuth 權限範圍進行驗證。
getMerchants 查詢更新getMerchants查詢現在能正確回傳所有可用的 offers。getMerchants查詢現在可回傳exclusiveRateId欄位（位於offers物件內）。此值可在purchaseGiftCard中指定你要購買的專屬費率 offer。
提領與消費帳戶 APIs
- 新增
withdrawCashBalancemutation，需要MAKE_WITHDRAWAL權限範圍。 - 新增
WithdrawMethods列舉，支援PAYPAL、BANK_ACH、BANK_CARD與VENMO方法。 - 新增
WithdrawSource列舉，支援CASH_BALANCE與REWARDS_BALANCE來源。 - 新增
WithdrawCashBalanceInput（含冪等性支援），以及Withdraw與WithdrawCashBalanceResponse型別，提供包含費用、狀態與時間戳在內的完整提領紀錄細節。 - 新增
transferUserCashBalancemutation，需要MAKE_INTERNAL_TRANSFER權限範圍，並包含TransferInternalBalanceInput與TransferInternalBalanceResponse型別。 - 在
EditVirtualCardInput新增userCashBalanceId，以便透過editVirtualCard將資金來源變更為指定的消費帳戶。 - 在
TransactionFilterInput新增userCashBalanceIds以便透過getTransactions依消費帳戶篩選交易，並在getGiftCards新增userCashBalanceId以依消費帳戶篩選禮品卡。 - 新增
updateUserCashBalance與closeUserCashBalancemutations，需要MANAGE_PAYMENT權限範圍，並包含支援的輸入與回應型別（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：可用於建立的所有有效虛擬卡 offer 的完整清單，包括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參數，允許你僅回傳擁有特定deliveryFormat之 offers 的商家。
- 強化
getMerchants查詢，新增offerTypes輸入參數，允許依giftCardOffers、cardLinkedOffers，或兩者進行篩選。預設情況下，若未提供offerTypes，查詢僅回傳禮品卡 offers。
- 新增查詢
getReferralUrl，可基於商家輸入回傳推薦字串，並新增MerchantInput型別。 - 在
purchaseGiftCardmutation 上引入自動重購機制。若使用銀行卡、銀行帳戶或 PayPal 的禮品卡購買失敗，系統會自動嘗試改以 Fluz 餘額重新購買。 - 在
PurchaseGiftCardInput新增defaultToBalance欄位，當主要付款方式失敗時，設定以 Fluz 餘額作為後備付款方式。預設為true。
- 新增存取權限範圍
CREATE_VIRTUALCARD以建立虛擬卡。 - 新增函式
createVirtualCard，可依特定參數建立虛擬卡。 - 新增查詢
getBINs，以擷取與虛擬卡相關的 BIN。 - 在現金餘額存款新增
merchantCategoryCode輸入，以利更佳的交易分類。 - 新增查詢
getMccList，以擷取商家分類代碼列表。 - 強化
getApplicationScopes查詢的權限範圍驗證，並改善 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取得帳戶。 - 新增
AccountType列舉以將帳戶分類為CONSUMER或BUSINESS，以及新的Account、Business與Seat物件。
- 修正
depositCashBalance平台通道輸入，讓存款交易日誌來源被記錄為API。