- 记录了借记卡在资金流转中的使用方式。从借记卡存入
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— 尽管存在于WithdrawMethods枚举中 — 并非可用的提现方式：withdrawCashBalance将以WDR-0004拒绝，getWithdrawFeeEstimate将以ARG-0001拒绝。
- 交易上的数字钱包信号。
TRANSACTION_CREATE与TRANSACTION_UPDATEWebhook 事件以及getTransactionsAPI 现在包含digitalWalletProvider（APPLE_PAY、GOOGLE_PAY或缺省）以便区分何时通过移动钱包完成的卡交易，并包含digitalWalletToken（网络令牌 ID）。请使用digitalWalletProvider作为钱包信号 — 对于非钱包的网络令牌，digitalWalletToken也会被设置，因此仅凭其存在并不代表使用了钱包。为增量改动且向后兼容。参见 Webhooks。
- 开环卡：收件人在初始激活流程中不再被提示创建 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_VIRTUALCARDscope。 - 新增输入
GetCardProvisioningUrlInput { offerId, platform }。 - 新增枚举
ProvisioningPlatform（IOS|ANDROID|OTHER）— 仅控制桌面/未知设备的回退路径；iOS 与 Android 的打开会自动路由。 - 新增返回类型
CardProvisioningUrl { url, expiresAt }。
- 新增
addVirtualCardAddress变更，用于保存虚拟卡发卡所需的账单地址。 - 更新
createVirtualCard变更以支持代表授权用户创建卡片。 - 新增完整流程，使用
registerUser、addAuthorizedUser、addVirtualCardAddress与createVirtualCard。 - 对带有
VC-0020的待处理发卡方审批进行重试，并返回addressId。
redeemFluzGiftCard— 使用代码兑换 Fluz 礼品卡。入账至giftCardCashBalance。需要MAKE_DEPOSIT。参见兑换 Fluz 礼品卡。unlockVirtualCard— 解锁先前锁定的虚拟卡以恢复交易能力。需要EDIT_VIRTUALCARD。参见解锁虚拟卡。
与交易相关的 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。
- 新增
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 scope 进行认证。
对
getMerchants 查询的更新getMerchants查询现在可正确返回所有可用的优惠。getMerchants查询现在可在offers对象内返回exclusiveRateId字段。该值可在purchaseGiftCard中用于指定你希望购买的专属费率优惠。
提现与消费账户 APIs
- 新增
withdrawCashBalance变更，需MAKE_WITHDRAWALscope。 - 新增
WithdrawMethods枚举，支持PAYPAL、BANK_ACH、BANK_CARD与VENMO方式。 - 新增
WithdrawSource枚举，支持CASH_BALANCE与REWARDS_BALANCE来源。 - 新增带幂等支持的
WithdrawCashBalanceInput，以及包含完整提现记录详情（含费用、状态与时间戳）的Withdraw与WithdrawCashBalanceResponse类型。 - 新增
transferUserCashBalance变更，需MAKE_INTERNAL_TRANSFERscope，另含TransferInternalBalanceInput与TransferInternalBalanceResponse类型。 - 在
EditVirtualCardInput中新增userCashBalanceId，以便通过editVirtualCard将资金来源更改为指定的消费账户。 - 在
TransactionFilterInput中新增userCashBalanceIds，用于通过getTransactions以消费账户过滤交易；并在getGiftCards中新增userCashBalanceId用于以消费账户过滤礼品卡。 - 新增
updateUserCashBalance与closeUserCashBalance变更，需MANAGE_PAYMENTscope，同时新增支持的输入与响应类型（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输入参数，支持按giftCardOffers、cardLinkedOffers 或两者过滤。默认情况下，若未提供offerTypes，查询仅返回礼品卡优惠。
- 引入新查询
getReferralUrl，基于商户输入返回推荐字符串，并新增MerchantInput类型。 - 在
purchaseGiftCard变更中引入自动重购尝试。若使用银行卡、银行账户或 PayPal 购买礼品卡失败，系统会自动尝试使用 Fluz 余额重新购买。 - 在
PurchaseGiftCardInput上新增defaultToBalance字段，以在主要支付方式失败时将 Fluz 余额设为回退支付方式。默认true。
- 引入新的访问范围
CREATE_VIRTUALCARD，用于创建虚拟卡。 - 引入新函数
createVirtualCard，以指定参数创建虚拟卡。 - 新增查询
getBINs，以检索与虚拟卡关联的 BIN。 - 为现金余额存款引入
merchantCategoryCode输入，以便增强交易分类。 - 新增查询
getMccList，用于检索商户类别代码列表。 - 增强
getApplicationScopes查询的 scope 校验，并改进 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。