- 交易中的数字钱包信号。
TRANSACTION_CREATE和TRANSACTION_UPDATEwebhook 事件以及getTransactionsAPI 现在包含digitalWalletProvider（APPLE_PAY、GOOGLE_PAY，或缺省）以便识别卡交易是否通过移动钱包完成，另含digitalWalletToken（网络代币 ID）。请使用digitalWalletProvider作为钱包信号——digitalWalletToken也会在非钱包网络代币上设置，因此其存在并不必然表示使用了钱包。为增量且向后兼容。参见 Webhooks。
- 开环卡：受领人在初始激活流程中不再被提示创建 PIN，且认领时不再自动展示卡片。现在在展示卡片时将提示受领人输入其 PIN，若尚未设置则引导创建。参见 Recipient Experience。
- 为开环卡更新 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 支持。
- 在概览页更新了
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 }。
- 为 Generate Share Links 增加了示例。
- 新增
addVirtualCardAddress变更，用于保存开立虚拟卡所需的账单地址。 - 更新
createVirtualCard变更以支持代表授权用户创建卡片。 - 新增完整流程：使用
registerUser、addAuthorizedUser、addVirtualCardAddress和createVirtualCard。 - 对带有
VC-0020且返回了addressId的发行方待审批进行重试。
redeemFluzGiftCard— 使用兑换码兑换 Fluz 礼品卡。记入giftCardCashBalance。需要MAKE_DEPOSIT。参见 Redeem a Fluz Gift Card。unlockVirtualCard— 解锁先前被锁定的虚拟卡以恢复交易能力。需要EDIT_VIRTUALCARD。参见 Unlock a Virtual Card。
与交易相关的 webhook
- 为
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现在可为空。 - 向
CreateVirtualCardInput新增usePrepaymentBalance与useRewardsBalance。createVirtualCard现已支持。两者默认true（保持现有行为）。将两者均设为false可将卡片资金来源限制为仅使用指定的userCashBalanceId，不包含预付（礼品卡）与奖励资金。
- 新增
shortDescription（Merchant）与termsAndConditions（Offer）。现在由getMerchants和getOfferQuote返回。 - 新增
deliveryFormat（GiftCard）。现在由getGiftCards返回——请对已购卡使用deliveryFormat。
- 新的
setVirtualCardPIN变更，允许用户在符合条件的虚拟卡上设置 PIN。参见 Set a Virtual Card PIN。
- 新增
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查询现在可以返回exclusiveRateId字段（位于offers对象内）。该值可在purchaseGiftCard中用于指定你希望购买的专属费率优惠。
提现与消费账户 API
- 新增
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。