Suscríbete a las actualizaciones en la Página de estado de Fluz para incidentes y notificaciones proactivas de cambios. También puedes suscribirte a este registro de cambios vía RSS.
- El evento de webhook
OAUTH_USER_LINKEDahora incluyespendAccountAccess, disponible por ahora solo en staging; aún no se entrega en producción. Indica sobre cuáles cuentas de gasto del usuario puede actuar la vinculación:restricted: truecon losuserCashBalanceIdsconcedidos, orestricted: falseconuserCashBalanceIds: nullcuando la concesión cubre todas las cuentas de gasto del usuario, actuales y futuras. Las concesiones restringidas también incluyenincludesFutureSpendAccounts, que indica si las cuentas de gasto que el usuario abra después se agregan automáticamente a la concesión. Úsalo para empezar a llamar operaciones de cuentas de gasto comogetSpendAccountPaymentInstructionsjusto después de la vinculación sin una consulta adicional. Solo IDs: los apodos y saldos vienen degetWallet, que sigue siendo la fuente de verdad para las cuentas de gasto permitidas. El evento se dispara de nuevo con el valor actualizado cada vez que cambia la concesión, incluido un cambio solo de la cuenta de gasto concedida. Aditivo y compatible hacia atrás. Ver Acceso a cuentas de gasto.
- Las categorías de comercios ahora están disponibles a través de la API, por lo que ya no necesitas una exportación CSV para mostrar o filtrar por categoría.
getMerchantsdevuelvecategoriesen cada comercio — una lista, porque un comercio puede pertenecer a más de una, vacía cuando no está categorizado — y acepta un argumentocategoryIdpara devolver solo los comercios de una categoría. La nueva consultagetMerchantCategorieslista las categorías con sus ids, que es la misma taxonomía mostrada en el catálogo de Fluz. Los ids de categoría son estables, así que guarda el id en lugar del nombre si almacenas en caché el mapeo. Ambos requieren el scopeLIST_OFFERS. Aditivo y compatible hacia atrás. Ver Obtener catálogo.
- Nuevo evento de webhook
FUNDING_SOURCE_STATUS_UPDATE, actualmente disponible en staging únicamente — aún no se entrega en producción. Se dispara cuando un usuario agrega, renombra o elimina una fuente de fondos. Un tipo de evento cubre los tres casos — ramifica segúnchangeType(ADDED,UPDATED,DELETED) en lugar del nombre del evento. La carga útil transportafundingSourceId,fundingSourceType(BANK_ACCOUNT,BANK_CARD,PAYPAL),brand,lastFour,nickname,statusy marcas de tiempo; nunca se incluyen números completos de tarjetas ni cuentas. Requiere el scopeLIST_PAYMENTy se entrega tanto a apps privadas como a apps OAuth. Se emite a partir del cambio en la propia fuente de fondos, por lo que se dispara donde sea que el usuario haya realizado el cambio — app móvil, app web o widget embebido. El saldo de efectivo de Fluz del usuario no es una fuente de fondos y no produce evento. Ver Webhooks.
- Los webhooks de transacciones ahora incluyen
isReversal. Estruepara una reversión de autorización,falsepara una transacción que clasificamos como otra cosa y ausente cuando no pudimos clasificarla. Presente enTRANSACTION_CREATE,TRANSACTION_UPDATEyTRANSACTION_DECLINE. La cobertura aún es parcial: hoy solo las anulaciones de verificación de tarjeta están marcadas comotrue, y las devoluciones no llevan ningún valor, por lo que el campo aún no puede distinguir entre una liberación de retención y un reembolso del comercio. Trata un valor ausente como desconocido, nunca comofalse. Aditivo y compatible hacia atrás. Ver Webhooks.
createTransferyrequestAccountTransferaceptanuseRewardsBalanceopcional en sus tipos de entrada. Cuando estrue, el envío se financia del saldo de recompensas del remitente además de la cuenta de gasto resuelta (primero efectivo, recompensas para el remanente). Omite o pasafalsepara el comportamiento existente solo con efectivo. No hay campo de prepago en estas mutaciones. Aditivo y compatible hacia atrás. Ver Financiar transferencias de cuenta con recompensas.
getUserPurchasesahora aceptapurchaseDisplayIden su argumentofilter, para que puedas obtener una sola orden por el ID de referencia devuelto en el momento de la compra en lugar de paginar tu historial para encontrarla. Es el mismo valor expuesto comoreferenceIdengetTransactions, y el registro de compra trae los detalles completos —seatRewardValuepara cashback, el desglose del pago y lagiftCardvinculada — en una sola llamada. El filtro aplica sobrescopey solo lo restringe. Los valores descopese combinan con AND, por lo que al pasar ambosTOKEN_USERyTOKEN_ACCOUNTse devuelven solo compras que el usuario del token realizó en la cuenta del token — una orden realizada por otro usuario se devuelve cuandoscopeesTOKEN_ACCOUNTpor sí solo. Aditivo y compatible hacia atrás. VerUserPurchaseFilterInput.
getVirtualCardBalanceahora devuelvestatus,lockedyauthorizationSettingjunto a las cifras de gasto, para que puedas leer el estado de la tarjeta para muchas tarjetas en una llamada en lugar de llamar arevealVirtualCardByVirtualCardIdpor tarjeta y toparte con el límite de tasa del emisor. Una tarjeta bloqueada aún reportastatus: ACTIVE, así que usalocked, que cubre bloqueos establecidos por el tarjetahabiente, por Fluz una vez que pasa la fecha de bloqueo, y por soporte de Fluz.authorizationSettinges el mismo objeto que devuelve reveal. Aditivo y compatible hacia atrás. Ver Obtener saldo de tarjeta virtual.
- Documentado cómo se usan las tarjetas de débito para el movimiento de dinero. Los depósitos desde una tarjeta de débito a
CASH_BALANCEpueden procesarse como transacciones de fondeo de cuenta (AFT), que tienen su propia tasa de comisión — leedepositFeede la respuesta en lugar de calcularla. Los retiros push-to-card (method: BANK_CARD) se entregan como transacciones de crédito original (OCT). La elegibilidad de la tarjeta para cualquiera no está disponible por adelantado y es independiente por dirección — una tarjeta desde la que un usuario puede depositar no es necesariamente una tarjeta a la que puedas enviar un retiro. Ver Depositar desde cuentas externas y Retirar a cuenta externa. isExpeditedenWithdrawCashBalanceInputahora controla la velocidad de entrega push-to-card:trueentrega a la tarjeta inmediatamente,falseu omitido liquida en el cronograma estándar. Un retiro push-to-card estándar aún puede fallar después de ser enviado y ser reembolsado al saldo de origen — por lo tanto, un retiroPENDINGno es definitivo todavía.- Documentado
getWithdrawFeeEstimateen Retirar a cuenta externa para previsualizarfee,netAmount,feePercent,feeMaxCapysettlementDelayDaysantes de enviar un retiro. - Correcciones en Retirar a cuenta externa: el scope requerido es
MAKE_WITHDRAWAL(noMANAGE_PAYMENT), los códigos de error son los realesWDR-*/ARG-*/HN-*/BC-*/G-*, yFLUZPAY— aunque está presente en el enumWithdrawMethods— no es un método de retiro utilizable:withdrawCashBalancelo rechaza conWDR-0004ygetWithdrawFeeEstimateconARG-0001.
- Señal de billetera digital en transacciones. Los eventos de webhook
TRANSACTION_CREATEyTRANSACTION_UPDATEy la APIgetTransactionsahora incluyendigitalWalletProvider(APPLE_PAY,GOOGLE_PAYo ausente) para que puedas saber cuándo una transacción con tarjeta se realizó a través de una billetera móvil, además dedigitalWalletToken(el id del token de red). UsadigitalWalletProvidercomo la señal de billetera —digitalWalletTokentambién se establece para tokens de red que no son de billetera, por lo que su mera presencia no significa que se usó una billetera. Aditivo y compatible hacia atrás. Ver Webhooks.
- Open Loop Cards: a los destinatarios ya no se les solicita crear un PIN durante el flujo de activación inicial, y la tarjeta ya no se revela automáticamente al canjear. Revelar una tarjeta ahora solicita al destinatario que ingrese su PIN, o que cree uno si aún no lo ha configurado. Ver Experiencia del destinatario.
- Actualizar GenerateVCShareLinksInput para Open Loop Cards. Ver Open Loop Cards.
- Actualizaciones en Página de fondos principal y de respaldo.
- Nuevo endpoint de API que expone transacciones rechazadas relacionadas con cuentas. Ver Obtener transacciones rechazadas.
GiftCard.purchaseId(UUID) — la compra que creó la tarjeta de regalo; el mismo ID devuelto porpurchaseGiftCardygetUserPurchases. Devuelvenullsi no hay compra asociada.GiftCard.purchaseDisplayId(String) — el ID corto, legible, de la transacción de Fluz (por ejemplo,1047283) que soporte referencia en revisiones manuales y exportaciones. Devuelvenullsi no hay compra asociada.GiftCard.purchaseValue(Float) — el valor nominal (denominación) al que se compró la tarjeta de regalo, en la moneda de la tarjeta.GiftCard.currentValue(Float) — el saldo restante en la tarjeta de regalo; igual apurchaseValuepara tarjetas de un solo uso.GiftCard.currency(String) — el código de moneda ISO del valor de la tarjeta de regalo (por ejemplo,USD).
getGiftCards (y dondequiera que se exponga GiftCard), lo que habilita la conciliación de pedido/valor sin llamar a revealGiftCardByGiftCardId por tarjeta. Aditivo y compatible hacia atrás.- Se añadió soporte para Plaid Link.
- Página de Descripción general actualizada con información de
llms.txt. - Encabezado actualizado con enlace de IA a
llms.txt.
- Nueva consulta
getCardProvisioningUrl— genera una URL corta de un solo uso que, al abrirse en un dispositivo móvil, lanza Fluz y agrega una tarjeta virtual a Apple Pay (iOS) o Google Pay (Android). Preséntala como un código QR, SMS, email, o botón in-app. Cada URL expira ~5 minutos después de crearse. Requiere el scopeCREATE_VIRTUALCARD. - Nueva entrada
GetCardProvisioningUrlInput { offerId, platform }. - Nuevo enum
ProvisioningPlatform(IOS|ANDROID|OTHER) — controla solo el fallback de escritorio / dispositivo desconocido; las aperturas en iOS y Android se enrutan automáticamente. - Nuevo tipo de retorno
CardProvisioningUrl { url, expiresAt }.
- Se agregaron ejemplos a Generar enlaces para compartir.
- Se agregó la mutación
addVirtualCardAddresspara guardar direcciones de facturación para la emisión de tarjetas virtuales. - Se actualizó la mutación
createVirtualCardpara admitir la creación de tarjetas en nombre de usuarios autorizados. - Se agregó el flujo completo usando
registerUser,addAuthorizedUser,addVirtualCardAddressycreateVirtualCard. - Reintentar aprobaciones pendientes del emisor con
VC-0020yaddressIddevuelto.
redeemFluzGiftCard— Canjear una tarjeta de regalo de Fluz usando un código. AcreditagiftCardCashBalance. RequiereMAKE_DEPOSIT. Ver Canjear una tarjeta de regalo de Fluz.unlockVirtualCard— Desbloquear una tarjeta virtual previamente bloqueada para restaurar la capacidad de realizar transacciones. RequiereEDIT_VIRTUALCARD. Ver Desbloquear una tarjeta virtual.
Webhooks relacionados con transacciones
- Se agregó descripción para los webhooks
TRANSACTION_CREATE,TRANSACTION_UPDATEyTRANSACTION_DECLINE. - Se incluyeron nuevos campos después del enriquecimiento del webhook (relacionados con MCC,
virtualCardId, etc.).
- Se agregaron
mcc,merchantCountryCode,originalCurrencyCode,originalCurrencyAmountycurrencyConversionRateaVirtualCardTransaction. Ahora los devuelvegetVirtualCardTransactions. - Se hizo opcional
virtualCardIdsengetVirtualCardTransactions— omítelo para consultar transacciones en todas las tarjetas de la cuenta autenticada. Se agregaron filtrosdateRangeStartydateRangeEnd.limitpredeterminado de 100 cuando se omitevirtualCardIds;limitestá limitado a 500.transactionAmountahora es anulable para filas sin un monto liquidado (por ejemplo, registros de rechazo solo AVS). - Se agregaron
usePrepaymentBalanceyuseRewardsBalanceaCreateVirtualCardInput. Ahora aceptado porcreateVirtualCard. Ambos predeterminados atrue(se conserva el comportamiento existente). Configura ambos enfalsepara restringir una tarjeta a extraer solo de lauserCashBalanceIdespecificada, excluyendo fondos prepagados (tarjeta de regalo) y recompensas.
- Se agregaron
shortDescription(Merchant) ytermsAndConditions(Offer). Ahora devueltos porgetMerchantsygetOfferQuote. - Se agregó
deliveryFormat(GiftCard). Ahora devuelto porgetGiftCards— usadeliveryFormatpara tarjetas compradas.
- Nueva mutación
setVirtualCardPIN, que permite a un usuario establecer su PIN en tarjetas virtuales elegibles. Ver Configurar un PIN de tarjeta virtual.
- Nuevas consultas
getUserCashBalancesygetUserCashBalanceById. Estas consultas permiten a un usuario recuperar una lista de sus cuentas de gasto y una cuenta de gasto específica creada en su cuenta.
API de Compartir Tarjetas Virtuales
- Nueva capacidad de “Compartir tarjetas virtuales” bajo Administrar tarjetas virtuales. Contacta a ventas para acceso.
- Se agregó el scope
CREATE_SHARE_LINKa la página de scopes de la aplicación.
API de registro de negocios
- Nueva consulta
getBusinessCategories: [BusinessCategory]para recuperar categorías de negocios, con tipos de respuestaBusinessCategoryyBusinessSubCategory. - Nueva mutación
registerBusiness(input: RegisterBusinessInput!): RegisterBusinessResultpara el registro programático de negocios. - Nuevos tipos de entrada:
RegisterBusinessInput,BusinessLegalAddressInput,BusinessOwnerInput,OwnerAddressInput. - Nuevos enums:
BusinessStructure(LLC,CORPORATION,PARTNERSHIP,SOLE_PROPRIETORSHIP,COOP) yBusinessAccountUsage. - Nuevos tipos de respuesta:
RegisterBusinessResult { accountId, kybStatus, success, error }yRegisterBusinessError { message, code }. - Ambas operaciones requieren autenticación con el scope OAuth
REGISTER_BUSINESS.
Actualizaciones a la consulta
getMerchants- La consulta
getMerchantsahora devuelve correctamente todas las ofertas disponibles. - La consulta
getMerchantsahora puede devolver un campoexclusiveRateId(dentro del objetooffers). Este valor se puede usar enpurchaseGiftCardpara especificar la oferta de tasa exclusiva con la que deseas comprar.
APIs de Retiros y Cuentas de Gasto
- Se agregó la mutación
withdrawCashBalancecon el requisito de scopeMAKE_WITHDRAWAL. - Se agregó el enum
WithdrawMethodsque admite los métodosPAYPAL,BANK_ACH,BANK_CARDyVENMO. - Se agregó el enum
WithdrawSourceque admite las fuentesCASH_BALANCEyREWARDS_BALANCE. - Se agregó
WithdrawCashBalanceInputcon soporte de idempotencia, además de los tiposWithdrawyWithdrawCashBalanceResponsecon detalles completos del registro de retiro incluyendo comisiones, estado y marcas de tiempo. - Se agregó la mutación
transferUserCashBalancecon el requisito de scopeMAKE_INTERNAL_TRANSFER, además de los tiposTransferInternalBalanceInputyTransferInternalBalanceResponse. - Se agregó
userCashBalanceIdaEditVirtualCardInputpara habilitar cambiar la fuente de fondos a una cuenta de gasto especificada víaeditVirtualCard. - Se agregó
userCashBalanceIdsaTransactionFilterInputpara filtrar transacciones por cuentas de gasto víagetTransactions, yuserCashBalanceIdagetGiftCardspara filtrar tarjetas de regalo por cuenta de gasto. - Se agregaron las mutaciones
updateUserCashBalanceycloseUserCashBalancecon el requisito de scopeMANAGE_PAYMENT, además de los tipos de entrada y respuesta de soporte (UpdateUserCashBalanceInput,CloseUserCashBalanceInput,CloseUserCashBalanceResponse,ClosedUserCashBalance,CloseUserCashBalanceResponseVirtualCard). - Se agregó el registro de acciones de la aplicación para la auditoría.
- Se agregó un nuevo campo
userCashBalancesal tipoUserBalancesen la consultagetWallet. Devuelve información detallada sobre cuentas individuales de saldo en efectivo del usuario con paginación víapaginate(limit/offset), ordenadas por fecha de creación (más reciente primero). IncluyeuserCashBalanceId,totalCashBalance,availableCashBalance,lifetimeCashBalance,nickname,statusycreatedAt— habilitando el seguimiento de múltiples cuentas de saldo en efectivo por usuario con apodos personalizados y monitoreo de estado.
- Se añadió un nuevo campo
userCashBalanceIdaDepositCashBalanceInputpara especificar el saldo de efectivo (cuenta de gasto) al que depositar los fondos.
- Nuevas mutaciones para gestionar tarjetas bancarias guardadas:
updateBankCardNickname,updateBankCardPreferredMerchantCategoryCodeydeleteBankCard, con los tipos de entrada correspondientes. - Campo
nicknameagregado al tipoBankCard. - Campos opcionales agregados a
AddBankCardInput:nicknameypreferredMerchantCategoryCode(MCC, normalizado a 4 dígitos).
getVirtualCardBalance: nueva consulta que recupera información de saldo para una lista de tarjetas virtuales, incluyendospentAmount,remainingBalance,spendLimityspendLimitDuration.getVirtualCardTransactions: nueva consulta que recupera transacciones para una lista de tarjetas virtuales, con filtros comotransactionTypes.
- La consulta
getUserPurchasesahora incluye la capacidad de filtrar las compras devueltas en la respuesta mediante una nueva variable opcionalUserPurchaseFilterInput. Filtra compras realizadas por el usuario, la cuenta o ambos.
- La respuesta de la mutación
revealVirtualCardByVirtualCardIdahora incluye un nuevo campoauthorizationSetting. - API de Tarjetas Virtuales en Lote: nueva API para crear y gestionar una gran cantidad de tarjetas virtuales de forma asíncrona.
- Mutación
createVirtualCardBulkOrder: envía una orden en lote y recibe unorderIdúnico. - Consulta
getVirtualCardBulkOrderStatus: realiza polling para rastrear el estado de la orden y recuperar los detalles de la tarjeta al completarse. - El proceso de creación de tarjetas en lote es asíncrono — verifica el estado de la orden para recuperar los detalles de la tarjeta.
- Nueva consulta
getVirtualCardOffers: lista integral de todas las ofertas activas de tarjetas virtuales disponibles para creación, incluyendoofferId(esencial para la creación de tarjetas),programName,bankName,rewardValuey límites detallados del programa (límites de gasto diarios, semanales, mensuales). - Mutación actualizada
createVirtualCard: emite tarjetas virtuales de forma programática proporcionando unofferId(degetVirtualCardOffers), unspendLimity atributos personalizables comocardNicknameyspendLimitDuration. - Nueva mutación
editVirtualCard: actualiza parámetros clave de una tarjeta virtual existente —spendLimit,spendLimitDuration,lockDate,lockCardNextUseycardNickname. - Nueva mutación
lockVirtualCard: bloquea inmediatamente una tarjeta virtual, impidiendo cualquier transacción ulterior.
- El tipo
Offeren la respuesta degetMerchantsahora incluye un campodeliveryFormatque especifica cómo se cumple la oferta:URL,CODES,PIN_AS_CODEoPIN_WITH_URL. - La consulta
getMerchantsha sido mejorada con un nuevo argumentofilterBy, que te permite filtrar resultados para incluir solo comercios con ofertas que coinciden con undeliveryFormatespecífico.
- Se mejoró la consulta
getMerchantscon un nuevo argumento de entradaofferTypes, que permite filtrar porgiftCardOffers,cardLinkedOffers o ambos. De manera predeterminada, si no se proporcionaofferTypes, la consulta devuelve solo ofertas de tarjetas de regalo.
- Se introdujo una nueva consulta
getReferralUrlque devuelve una cadena de referencia basada en la entrada del comercio, con un nuevo tipoMerchantInput. - Se introdujo un reintento automático de recompra en la mutación
purchaseGiftCard. Si una compra de tarjeta de regalo usando una tarjeta bancaria, cuenta bancaria o PayPal falla, el sistema intenta automáticamente recomprar usando el saldo de Fluz. - Se introdujo el campo
defaultToBalanceenPurchaseGiftCardInputpara establecer el saldo de Fluz como el método de pago de respaldo si falla el método de pago principal. Predeterminado atrue.
- Se introdujo un nuevo scope de acceso,
CREATE_VIRTUALCARD, para crear tarjetas virtuales. - Se introdujo una nueva función,
createVirtualCard, para crear tarjetas virtuales con parámetros específicos. - Se agregó una nueva consulta,
getBINs, para recuperar BINs asociados con tarjetas virtuales. - Se introdujo una entrada
merchantCategoryCodepara depósitos en saldo de efectivo, permitiendo una mejor categorización de transacciones. - Se agregó una nueva consulta,
getMccList, para recuperar una lista de códigos de categoría de comercio. - Se mejoró la validación de scopes para la consulta
getApplicationScopesy se mejoró la gestión de definiciones de tipos de GraphQL.
- Mejora en el manejo de información de stock para ofertas de comercios: el campo
stockInfodel objetoOfferahora devuelveStockInfoFixedTypeoStockInfoVariableTypedependiendo de si la oferta es fija o variable. - Mejora en el manejo de errores con respuestas de mensajes de error más intuitivas — respuestas mejoradas para errores de ausencia de oferta en
purchaseGiftCardy discrepancias entre cuenta y métodos de pago.
v0.0.21
- Se introdujo un parámetro
idempotencyKeyparadepositCashBalanceypurchaseGiftCardspara evitar solicitudes duplicadas. - Se agregaron tipos
purchaseGiftCardInputpara simplificar el manejo de parámetros para transacciones. - Se introdujo un nuevo campo
purchaseDisplayIden el tipoUserPurchase, que proporciona un ID de visualización para compras. - Se corrigió el campo
offeringMerchantIddel objetoOfferpara devolveroffering_merchant_iden lugar deoffer_id.
- Se agregó el requisito
accountIdagenerateUserAccessToken. - Se implementó una nueva consulta,
getAccountsByUserId, para obtener cuentas basadas enuserId. - Se agregó un nuevo enum
AccountTypepara categorizar cuentas comoCONSUMERoBUSINESS, además de nuevos objetosAccount,BusinessySeat.
- Se corrigió la entrada del canal de plataforma de
depositCashBalancepara que la fuente del registro de transacción de depósito se registre comoAPI.