OAUTH_USER_LINKEDwebhook 事件现在携带spendAccountAccess，目前仅限 staging——尚未在生产环境投递。它说明该链接可以操作用户的哪些消费账户：restricted: true并附带已授予的userCashBalanceIds；或当授权覆盖用户当前及未来的全部消费账户时，restricted: false且userCashBalanceIds: null。受限授权还携带includesFutureSpendAccounts，说明用户之后开设的消费账户是否会自动加入该授权。借此您可以在链接完成后立即调用getSpendAccountPaymentInstructions等消费账户操作，而无需额外查询。仅包含 ID——昵称和余额来自getWallet，它仍是已允许消费账户的事实来源。每当授权变化时（包括仅更换已授予的消费账户），该事件都会携带更新后的值再次触发。为增量且向后兼容。见消费账户访问权限。
Virtual Card Return事件现在携带isReversal：授权冻结被释放时为true（无论由发卡行还是 Fluz 释放），商户退款时为false。2026-09-25 20:15 UTC 之前推送的退回不带该值；对于这些事件，以及少数我们仍无法分类的退回，请按撤销 vs 退款所述，通过referenceId和原始授权来区分已释放的冻结与退款。为增量且向后兼容。
- 现在可通过 API 获取商户分类，无需再用 CSV 导出即可展示或按分类筛选。
getMerchants会在每个商户上返回categories—— 这是一个列表（商户可以属于多个分类；未分类时为空）—— 并接受categoryId参数以仅返回属于某一分类的商户。新增的getMerchantCategories查询会列出带有 id 的分类，与 Fluz 商品目录中的分类体系一致。分类 id 是稳定的，因此若你缓存映射，请存 id 而非名称。两者都需要LIST_OFFERS范围。为增量且向后兼容。参见 获取目录。
- 新增 webhook 事件
FUNDING_SOURCE_STATUS_UPDATE，目前仅在 staging 可用 —— 生产环境尚未投递。当用户添加、重命名或移除资金来源时触发。单一事件类型覆盖三种情况 —— 请基于changeType（ADDED、UPDATED、DELETED）进行分支，而非事件名。负载包含fundingSourceId、fundingSourceType（BANK_ACCOUNT、BANK_CARD、PAYPAL）、brand、lastFour、nickname、status和时间戳；从不包含完整卡号或账户号。需要LIST_PAYMENT范围，并会投递给私有应用与 OAuth 应用。该事件由资金来源本身的变更触发，因此无论用户在移动端、网页端或嵌入式组件中进行变更，都会触发。用户的 Fluz 现金余额不是资金来源，不会产生该事件。参见 Webhooks。
- 交易类 webhook 现在携带
isReversal。对授权撤销为true，被分类为其他类型的交易为false，无法分类时缺省不返回。出现在TRANSACTION_CREATE、TRANSACTION_UPDATE和TRANSACTION_DECLINE上。当前覆盖仍不完整：目前仅持卡验证撤销会标记为true，而退货不会包含任何值，因此暂时无法仅凭该字段区分已释放的预授权与商户退款。缺省值请视为未知，切勿当作false。为增量且向后兼容。参见 Webhooks。
createTransfer与requestAccountTransfer的输入类型新增可选useRewardsBalance。当为true时，转账将除了使用解析出的消费账户外，还会使用发起人的奖励余额共同出资（先现金，再奖励补足）。省略或传false则维持现有仅现金的行为。这些变更中没有预付字段。为增量且向后兼容。参见 使用奖励为账户转账提供资金。
getUserPurchases现在在其filter参数上接受purchaseDisplayId，因此你可以通过购买时返回的参考 ID 直接获取单个订单，而无需分页遍历历史记录。该值与getTransactions上暴露的referenceId相同，而 purchase 记录在一次调用中携带完整细节 —— 用于返现的seatRewardValue、支付拆分以及关联的giftCard。该筛选在scope之上生效，只会进一步收窄结果。scope值之间为 AND 组合，因此同时传TOKEN_USER和TOKEN_ACCOUNT只会返回该令牌的用户在该令牌的账户上所做的购买 —— 当scope仅为TOKEN_ACCOUNT时，由其他用户下的订单也会返回。为增量且向后兼容。参见UserPurchaseFilterInput。
getVirtualCardBalance现在与消费数据一并返回status、locked和authorizationSetting，这样你可以在一次调用中读取多张卡的状态，而不必逐张调用revealVirtualCardByVirtualCardId并触发发卡行的速率限制。被锁定的卡仍会报告status: ACTIVE，因此请使用locked字段，它覆盖持卡人设置的锁、到达锁定日期后 Fluz 设置的锁，以及 Fluz 支持设置的锁。authorizationSetting与 reveal 返回的对象一致。为增量且向后兼容。参见 获取虚拟卡余额。
- 文档化借记卡在资金流动中的使用方式。从借记卡充值到
CASH_BALANCE可能会作为账户入账交易（AFT）处理，并具有其独立费率 —— 请从响应中读取depositFee而非自行计算。推送到卡的提现（method: BANK_CARD）会作为原始贷记交易（OCT）交付。两者的卡片可用性无法预先得知，且每个方向相互独立 —— 用户可用于充值的卡不一定可用于接收提现。参见 从外部账户充值 和 提现到外部账户。 WithdrawCashBalanceInput上的isExpedited现在控制推送到卡的交付速度：true为即时入卡，false或省略为标准结算进度。标准的推卡提现在提交后仍可能失败并退回至来源余额 —— 因此PENDING的提现尚未最终确定。- 在 提现到外部账户 中补充了
getWithdrawFeeEstimate用于在提交提现前预览fee、netAmount、feePercent、feeMaxCap与settlementDelayDays。 - 对 提现到外部账户 的更正：所需范围为
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（网络代币 id）。请使用digitalWalletProvider作为钱包信号 ——digitalWalletToken也会对非钱包网络代币设置，因此仅凭其存在并不意味着使用了钱包。为增量且向后兼容。参见 Webhooks。
- 开放式卡（Open Loop Cards）：接收人在初始激活流程中不再被提示创建 PIN，卡片在认领时也不再自动展示信息。现在在展示卡片信息时会提示接收人输入其 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）—— 礼品卡的购买面值（面额），按卡片货币计价。GiftCard.currentValue（Float）—— 礼品卡的剩余余额；对一次性卡等于purchaseValue。GiftCard.currency（String）—— 礼品卡价值的 ISO 货币代码（例如USD）。
getGiftCards 返回（以及任何暴露 GiftCard 的位置），可在无需逐卡调用 revealGiftCardByGiftCardId 的情况下完成订单/金额对账。为增量且向后兼容。- 新增对 Plaid Link 的支持。
- 在概览页面加入
llms.txt相关信息。 - 更新页头，新增指向
llms.txt的 AI 链接。
- 新增
getCardProvisioningUrl查询 —— 生成一个短的单次使用 URL，在移动设备上打开时会启动 Fluz 并将虚拟卡添加到 Apple Pay（iOS）或 Google Pay（Android）。可将其展示为二维码、通过短信/邮件发送或在应用内提供按钮。每个 URL 在创建后约 5 分钟过期。需要CREATE_VIRTUALCARD范围。 - 新增输入
GetCardProvisioningUrlInput { offerId, platform }。 - 新增枚举
ProvisioningPlatform（IOS|ANDROID|OTHER）—— 仅控制桌面/未知设备的回退；iOS 与 Android 会自动路由。 - 新增返回类型
CardProvisioningUrl { url, expiresAt }。
- 新增
addVirtualCardAddress变更，用于保存虚拟卡发卡所需的账单地址。 - 更新
createVirtualCard变更以支持代表授权用户创建卡片。 - 新增完整流程，使用
registerUser、addAuthorizedUser、addVirtualCardAddress与createVirtualCard。 - 对于发卡行待审批状态，请使用返回的
addressId并对VC-0020进行重试。
redeemFluzGiftCard—— 使用代码兑换 Fluz 礼品卡。入账到giftCardCashBalance。需要MAKE_DEPOSIT。参见 兑换 Fluz 礼品卡。unlockVirtualCard—— 解锁先前被锁定的虚拟卡以恢复交易能力。需要EDIT_VIRTUALCARD。参见 解锁虚拟卡。
与交易相关的 webhooks
- 补充了
TRANSACTION_CREATE、TRANSACTION_UPDATE与TRANSACTION_DECLINE的描述。 - 加入 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。
- 新增
getUserCashBalances与getUserCashBalanceById查询。这些查询允许用户检索其消费账户列表以及其账户上创建的特定消费账户。
企业注册 API
- 新增查询
getBusinessCategories: [BusinessCategory]以检索企业分类，响应类型为BusinessCategory与BusinessSubCategory。 - 新增变更
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查询现在能正确返回所有可用的优惠。getMerchants查询现在可在offers对象中返回exclusiveRateId字段。该值可用于purchaseGiftCard来指定你希望购买的专属费率优惠。
提现与消费账户 APIs
- 新增
withdrawCashBalance变更，要求MAKE_WITHDRAWAL范围。 - 新增
WithdrawMethods枚举，支持PAYPAL、BANK_ACH、BANK_CARD和VENMO方法。 - 新增
WithdrawSource枚举，支持CASH_BALANCE和REWARDS_BALANCE来源。 - 新增
WithdrawCashBalanceInput（支持幂等），以及Withdraw与WithdrawCashBalanceResponse类型，包含完整的提现记录细节，包括费用、状态与时间戳。 - 新增
transferUserCashBalance变更，要求MAKE_INTERNAL_TRANSFER范围，另有TransferInternalBalanceInput与TransferInternalBalanceResponse类型。 - 在
EditVirtualCardInput中新增userCashBalanceId，以便通过editVirtualCard将资金来源更改为指定的消费账户。 - 在
TransactionFilterInput中新增userCashBalanceIds以便通过getTransactions按消费账户筛选交易，并在getGiftCards中新增userCashBalanceId以按消费账户筛选礼品卡。 - 新增
updateUserCashBalance与closeUserCashBalance变更，要求MANAGE_PAYMENT范围，并配套输入和响应类型（UpdateUserCashBalanceInput、CloseUserCashBalanceInput、CloseUserCashBalanceResponse、ClosedUserCashBalance、CloseUserCashBalanceResponseVirtualCard）。 - 新增应用操作日志用于审计追踪。
- 在
getWallet查询的UserBalances类型中新增userCashBalances字段。通过paginate（limit/offset）进行分页，按创建日期倒序（最新在前）返回单个用户现金余额账户的详细信息。包含userCashBalanceId、totalCashBalance、availableCashBalance、lifetimeCashBalance、nickname、status与createdAt—— 从而可对每位用户的多个现金余额账户进行追踪，支持自定义昵称与状态监控。
- 在
DepositCashBalanceInput中新增字段userCashBalanceId，用于指定要充值到的现金余额（消费账户）。
- 新增管理已保存银行卡的变更：
updateBankCardNickname、updateBankCardPreferredMerchantCategoryCode与deleteBankCard，以及对应的输入类型。 - 在
BankCard类型中新增nickname字段。 - 在
AddBankCardInput中新增可选字段：nickname与preferredMerchantCategoryCode（MCC，标准化为 4 位）。
getVirtualCardBalance：新增查询，检索一组虚拟卡的余额信息，包括spentAmount、remainingBalance、spendLimit与spendLimitDuration。getVirtualCardTransactions：新增查询，检索一组虚拟卡的交易，支持如transactionTypes等过滤器。
getUserPurchases查询现在支持通过新的可选变量UserPurchaseFilterInput来筛选返回的购买记录。可按用户、账户或两者进行筛选。
revealVirtualCardByVirtualCardId变更的响应现包含新字段authorizationSetting。- 批量虚拟卡 API：新增异步创建与管理大量虚拟卡的 API。
createVirtualCardBulkOrder变更：提交批量订单并接收唯一的orderId。getVirtualCardBulkOrderStatus查询：轮询以跟踪订单状态并在完成后获取卡片详情。- 批量制卡流程是异步的 —— 请检查订单状态以获取卡片详情。
- 新增查询
getVirtualCardOffers：返回所有可用于创建的有效虚拟卡优惠的完整列表，包括offerId（制卡必需）、programName、bankName、rewardValue以及详细的项目限制（每日、每周、每月消费限额）。 - 更新变更
createVirtualCard：通过提供offerId（来自getVirtualCardOffers）、spendLimit以及可自定义属性如cardNickname和spendLimitDuration来以编程方式发行虚拟卡。 - 新增变更
editVirtualCard：更新现有虚拟卡的关键参数 ——spendLimit、spendLimitDuration、lockDate、lockCardNextUse与cardNickname。 - 新增变更
lockVirtualCard：立即锁定虚拟卡，阻止任何进一步交易。
getMerchants响应中的Offer类型现包含deliveryFormat字段，用于指定优惠的履约方式：URL、CODES、PIN_AS_CODE或PIN_WITH_URL。getMerchants查询新增filterBy参数，允许仅返回deliveryFormat符合特定值的商户优惠。
- 为
getMerchants查询增强了新的offerTypes输入参数，允许按giftCardOffer、cardLinkedOffer或两者进行过滤。默认情况下，若未提供offerTypes，查询仅返回礼品卡优惠。
- 新增查询
getReferralUrl，基于商户输入返回推荐字符串，并新增MerchantInput类型。 - 在
purchaseGiftCard变更中引入自动重购尝试。当使用银行卡、银行账户或 PayPal 购买礼品卡失败时，系统会自动尝试使用 Fluz 余额重新购买。 - 在
PurchaseGiftCardInput上新增defaultToBalance字段，以在主要支付方式失败时将 Fluz 余额设为回退支付方式。默认为true。
- 新增访问范围
CREATE_VIRTUALCARD，用于创建虚拟卡。 - 新增函数
createVirtualCard，可按特定参数创建虚拟卡。 - 新增查询
getBINs，检索与虚拟卡关联的 BIN。 - 在现金余额充值中新增
merchantCategoryCode输入，以增强交易分类。 - 新增查询
getMccList，检索商户类别码列表。 - 增强了对
getApplicationScopes查询的范围校验，并改进 GraphQL 类型定义管理。
- 增强商户优惠的库存信息处理：
Offer对象的stockInfo字段现在会根据优惠是固定还是可变，返回StockInfoFixedType或StockInfoVariableType。 - 增强错误处理并提供更直观的错误消息响应 —— 改进了
purchaseGiftCard无可用优惠时的响应，以及账户与支付方式不匹配时的响应。
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。