Ciclo de vida de las transacciones

Una compra con una tarjeta emitida por Fluz no es un evento único. Es una conversación entre el comercio, la red de tarjetas y Fluz que se desarrolla en segundos, horas o a veces semanas — y produce varios registros de tu lado antes de terminar. Esta página explica qué sucede en cada etapa, qué registros y webhooks produce Fluz en cada una, y los lugares donde una integración ingenua se equivoca en la aritmética.

Esta página cubre transacciones de tarjetas open-loop — gasto en tarjetas virtuales que Fluz emite en las redes de tarjetas. Las compras de tarjetas de regalo, depósitos, retiros y transferencias de la billetera no pasan por este ciclo de vida; se liquidan en sus propios rieles. Consulta Resumen de transacciones para el libro mayor unificado que las contiene a todas.

Las tres etapas

Etapa	Qué sucede	De quién se mueve el dinero
Autorización	La red pregunta a Fluz si se puede cobrar la tarjeta. Fluz revisa los controles y el financiamiento de la tarjeta y responde.	Aún nada. Los fondos se reservan, no se mueven.
Compensación (clearing)	El comercio envía el monto final. Fluz finaliza el registro contra los fondos retenidos.	La retención se convierte en un débito real.
Liquidación (settlement)	La red mueve fondos entre el banco adquirente y el banco emisor.	Banco a banco. Invisible para tu integración.

La liquidación es un proceso bancario que corre detrás de la compensación según el propio calendario de la red. Fluz representa la compensación y la liquidación como un solo evento — cuando una transacción se compensa en Fluz, trátala como final.

Una compra, varios registros

Una sola compra puede producir una autorización, una o más compensaciones, y posiblemente un reverso o un reembolso. Fluz expone esto mediante tres consultas que responden a preguntas diferentes:

Feed	Consulta	Qué muestra
Actividad de tarjeta	`getVirtualCardTransactions`	Gasto en una o más tarjetas, con comercio, MCC, FX y campos de respuesta de red
Libro de cuenta	`getTransactions`	Cada movimiento de dinero en la cuenta, con instantáneas de balance después de cada registro
Autorizaciones declinadas	`getDeclinedTransactions`	Autorizaciones que fueron rechazadas y nunca se convirtieron en transacciones

Tres compras, y los registros que deja cada una:

Acme Hardware — $50.00
├── Authorization        $50.00 debit      held against the card
└── Clearing             $50.00 debit      hold converted, record final

Riverside Hotel — $240.00
├── Authorization       $200.00 debit      pre-auth at check-in
├── Incremental auth     $75.00 debit      incidentals added mid-stay
└── Clearing            $240.00 debit      final folio, less than authorized

Acme Hardware — $50.00, later refunded
├── Authorization        $50.00 debit
├── Clearing             $50.00 debit
└── Refund               $50.00 credit     separate record, not a reversal

Un reembolso es un registro nuevo, no una edición del anterior.Los reembolsos llegan como su propia transacción REFUND. Nada del registro PURCHASE original cambia — su monto permanece igual. Si tu sistema reduce la compra original cuando llega un reembolso, contarás el crédito doble. Reconcilia a nivel de registros; nunca modifiques el original.

Flujos de un solo mensaje y de dos mensajes

Cuántos mensajes envía la red depende del comercio y del tipo de transacción. Ambos flujos son normales, y tu integración debe manejar ambos.

Un solo mensaje

La red envía un solo mensaje que autoriza y compensa al mismo tiempo. Común para débito con PIN, retiros en cajero y tránsito. No hay ventana de pendiente — la transacción es casi inmediatamente final.

Dos mensajes

La red envía primero una autorización, y el comercio envía la compensación después — normalmente la misma noche, pero hasta varios días para hoteles, alquiler de autos y viajes. El intervalo entre ambos es la ventana de pendiente, y es donde viven la mayoría de los errores de conciliación.

El monto compensado puede diferir del monto autorizado. Propinas, bombas de combustible, conversión de moneda y envíos parciales producen una compensación mayor o menor que la retención original. Toma el monto compensado como autoritativo y nunca trates el monto de una autorización como final.

Dónde se sienta el dinero

El mismo ciclo de vida, visto desde la cuenta en lugar de la red:

Qué registra Fluz en cada etapa

Mensaje de red	Qué significa	Card feed `transactionType`	Ledger `status`	Webhook
Verification	Una sonda de $0.00 o$ 0.01 para confirmar que la tarjeta está activa	`PURCHASE`, se revierte pronto	`PENDING`, liberado	`TRANSACTION_CREATE`
Authorization	Reservar fondos en espera de un monto final	`PURCHASE`	`PENDING`	`TRANSACTION_CREATE`
Authorize and clear	Aprobar y finalizar en un solo mensaje	`PURCHASE`	`SETTLED`	`TRANSACTION_CREATE` + `TRANSACTION_UPDATE`
Clearing	Finalizar una transacción previamente autorizada	`PURCHASE`	`SETTLED`	`TRANSACTION_UPDATE`
Decline	La autorización fue rechazada	`DECLINE`	sin registro en el libro	`TRANSACTION_DECLINE`
Reversal	Una autorización liberada antes de compensar	hold released	registro liberado	`TRANSACTION_UPDATE`
Refund	Valor devuelto después de que una compra se compensó	`REFUND`	crédito `SETTLED`	`TRANSACTION_CREATE`

Dos feeds, dos vocabularios de estado.

getVirtualCardTransactions devuelve valores transactionStatus como PROCESSING y CLEARED.
getTransactions devuelve valores status de PENDING y SETTLED.

Describen el mismo ciclo de vida desde dos ángulos. No escribas código que espere un vocabulario en ambos lugares. → Cómo funciona la API GraphQL

Un decline no es una transacción. Las autorizaciones rechazadas nunca ingresan al libro de la cuenta, por lo que no aparecerán en getTransactions en ningún estado. Consúltalas mediante getDeclinedTransactions y lee la razón en Códigos de rechazo.

Autorización

Cuando la red le pide a Fluz que apruebe un cargo, Fluz evalúa la solicitud contra la tarjeta, la cuenta y la financiación detrás de la tarjeta. Todo sucede en mucho menos de un segundo, porque la red agotará el tiempo de espera.

Qué se verifica

Que la tarjeta esté ACTIVE — no bloqueada, expirada, pasada su lockDate, o ya consumida por una regla de un solo uso
Que el monto encaje dentro de spendLimit para el spendLimitDuration de la tarjeta
Que el comercio coincida con el bloqueo de marca de la tarjeta, si la tarjeta se emitió en un programa con bloqueo de marca
Que el titular de la cuenta haya pasado la verificación de identidad
Que las fuentes de fondos detrás de la tarjeta puedan cubrir el monto
Que no se excedan los límites del programa bancario

De dónde viene el dinero

Una tarjeta no tiene un balance propio. Toma fondos, en el momento de la autorización, de la pila de financiamiento configurada cuando se emitió la tarjeta:

La cuenta de gasto indicada en userCashBalanceId, o la predeterminada de la cuenta
El saldo de prepago (tarjeta de regalo), a menos que usePrepaymentBalance: false
El saldo de recompensas, a menos que useRewardsBalance: false
Una cuenta bancaria externa, cuando primaryFundingSource es BANK_ACCOUNT

Una autorización que excede lo que esas fuentes pueden cubrir es rechazada, incluso cuando el spendLimit de la tarjeta es mayor. → Administrar fuentes de fondos de Tarjetas Virtuales

Monto aprobado vs monto solicitado

La red solicita un monto; Fluz registra lo que aprueba. En una aprobación parcial los dos difieren, y el monto aprobado es lo que se retiene. Lee el monto del registro de Fluz en lugar de asumir que coincide con lo que pidió el comercio.

Declines

Una autorización rechazada devuelve un código de respuesta al comercio y produce un declineReason y declineCategory del lado de Fluz. Las causas más comunes son un monto por encima del límite de gasto, una tarjeta bloqueada, fondos insuficientes detrás de la tarjeta, una tarjeta con bloqueo de marca en el comercio equivocado, y discrepancia de CVV o AVS. → Códigos de rechazo

Autorizaciones que no son compras

Tipo	Qué es	Qué hacer con ello
Sonda de $0 /$ 0.01	Un comercio confirmando que la tarjeta está activa antes de guardarla o cobrarla después	Espérala, y no la cuentes como gasto. Se revierte sola.
Pre-autorización	Una retención colocada antes de conocer el monto final — hoteles, alquileres de autos, bombas de combustible	Espera una compensación por un monto diferente, a menudo días después.
Incremental	Una retención adicional apilada sobre una pre-autorización abierta	Suma las retenciones; no trates la segunda como una segunda compra.
Surtidor de combustible	Un monto fijo definido por reglas de la red, no relacionado con lo efectivamente cargado	La compensación lleva el monto real.

Fondos retenidos

Una autorización aprobada reduce lo que la tarjeta aún puede gastar sin mover dinero fuera de la cuenta. Hasta que compense:

El remainingBalance de la tarjeta refleja la retención
El registro del libro se queda en PENDING
expectedClearedDate te indica cuándo volver a mirar

Si nunca llega una compensación, la retención no se queda allí para siempre — las reglas de expiración de la red la liberan y los fondos regresan al balance disponible de la tarjeta. La mayoría de las autorizaciones expiran en aproximadamente una semana; las retenciones de viajes y hospedaje duran más. La ventana exacta la fijan la red y el comercio, no Fluz.

Reversos

Un reverso cancela una autorización antes de que compense. La retención se libera y los fondos regresan a la tarjeta. Los reversos pueden ser totales o parciales. Causas comunes:

El comercio abandonó la venta, o la terminal agotó el tiempo
El artículo no tenía stock, o el titular canceló antes del envío
Se envió una autorización duplicada
La autorización expiró sin una compensación

Un “reverso” después de compensar es realmente un reembolso.Una vez que una transacción se ha compensado, ya no queda una retención por liberar. El dinero que regresa después de ese punto llega como un crédito — un registro REFUND separado — y debe manejarse como tal. La presencia de una compensación correspondiente es la línea divisoria entre ambos casos.

Compensación y liquidación

La compensación es el comercio enviando el monto final, usualmente como parte de un lote nocturno. Fluz la asocia a la autorización abierta usando los identificadores de referencia de la red y finaliza el registro. Realidades para las que debes construir:

El monto cambia. Propinas, combustible, FX y envíos parciales mueven el número.
Puede haber más de una compensación. Un envío dividido se compensa en partes contra una autorización, y las partes pueden llegar fuera de orden.
Puede llegar una compensación sin autorización. Las redes permiten al comercio forzar la contabilización en algunas situaciones — terminales offline, compras en vuelo, agregación de tarifas de tránsito. Fluz monitorea estos casos, pero tu libro debe aceptar una compra que aparece ya compensada sin fase pendiente.
La coincidencia no está garantizada. En casos raros los identificadores de una compensación no se alinean con la autorización a la que pertenecen, y la compensación aparece como su propio registro.

No concilies solo con identificadores de referencia de red. No están garantizados para mantenerse consistentes a lo largo de la vida de una transacción, y no son estables entre redes. Al crear tu orden, guarda el record_id y reference_id de Fluz en tu propio sistema. → Conciliación contra tu propio sistema

Reembolsos

Cuando un comercio devuelve valor, envía un crédito de regreso por la red. Fluz lo publica como un REFUND en el feed de la tarjeta y como un crédito en el libro. Puede llegar como una autorización que luego compensa, o como una compensación por sí sola. Dos casos que rompen la vinculación ingenua:

Reembolsos no vinculados. La red puede enviar el crédito sin referencia a la compra original, o con identificadores diferentes. Llega como un crédito independiente sin nada a lo cual unirse.
Reembolsos por lotes. Varios reembolsos de diferentes compras originales pueden compartir identificadores de red y llegar agrupados.

Por ambas razones, no asumas una relación uno-a-uno entre reembolsos y compras. Reconcilia los reembolsos como créditos independientes contra la tarjeta, y deja que el balance sea la fuente de verdad.

Moneda extranjera

Una compra hecha en otra moneda compensa en USD, con el monto original preservado en el registro:

Campo	Significado
`originalCurrencyCode`	Código ISO 4217 de la moneda en que el comercio cobró
`originalCurrencyAmount`	El monto original en unidades menores — `6300` HKD es HK$63.00
`currencyConversionRate`	La tasa aplicada para llegar a USD. `1.0` para transacciones domésticas

Estos tres campos se devuelven juntos — todos poblados, o todos nulos. La conversión sucede al compensar, por lo que una autorización extranjera y su compensación comúnmente difieren en términos de USD incluso cuando el comercio cobró el mismo monto.

Secuencias de mensajes comunes

Más allá de los dos caminos felices, estas son las secuencias para las que vale la pena tener cobertura de pruebas.

Secuencia	Qué es
`AUTHORIZE_AND_CLEAR`	Débito con PIN, cajero automático, tránsito — sin ventana pendiente
`AUTHORIZE` → `CLEAR`	La compra estándar
`AUTHORIZE` → `CLEAR` (mayor)	Propina agregada después de presentar la tarjeta
`AUTHORIZE` → `CLEAR` (menor)	Envío parcial, o un folio de hotel por debajo de la pre-autorización
`AUTHORIZE` → `AUTHORIZE` → `CLEAR`	Pre-autorización más autorización incremental, se compensa una vez
`AUTHORIZE` → `CLEAR` → `CLEAR`	Envío dividido, compensando en piezas
`AUTHORIZE` → `REVERSAL`	Venta abandonada antes de compensar
`AUTHORIZE` → `REVERSAL` (parcial) → `CLEAR`	Parte de la retención liberada, el resto compensado
`AUTHORIZE` → (expiry)	Nunca llega la compensación; la retención se libera por expiración
`CLEAR` sin `AUTHORIZE`	Publicación forzada — terminal offline, en vuelo, agregación de tránsito
`AUTHORIZE` → `CLEAR` → `REFUND`	Compra luego reembolsada, total o parcialmente
`VERIFICATION` ($0.00)	Validación de tarjeta en archivo, revertida poco después

Construir contra el ciclo de vida

Trata lo pendiente y lo compensado como cosas distintas

Nunca muestres una autorización pendiente como una compra completada, y nunca sumes juntas autorizaciones y compensaciones. Si necesitas un solo número, suma los registros compensados y muestra las retenciones por separado.

Suscríbete a los tres eventos de transacción

TRANSACTION_CREATE, TRANSACTION_UPDATE, y TRANSACTION_DECLINE. Una integración que solo escucha creaciones mostrará cada transacción atascada por siempre en su monto de autorización. → Webhooks

Sincroniza con updatedGte, no con createdGte

Un registro creado como PENDING y que luego compensa cambia su marca de tiempo de actualización, no su marca de creación. Una sincronización por fecha de creación omite silenciosamente cada liquidación.

Reconcilia balances desde las instantáneas

Cada registro del libro lleva el estado posterior de cada balance. Lee esos campos en lugar de sumar montos tú mismo — ya contabilizan comisiones, cashback y retenciones abiertas.

Haz que los handlers sean idempotentes

Los webhooks reintentan, y las compensaciones pueden llegar fuera de orden. Usa el identificador de registro de Fluz como clave y haz que la repetición no tenga efecto.

Probar el ciclo de vida

Las tarjetas de staging son registros de tarjeta reales pero no están en una red en vivo, así que las transacciones se inyectan contra ellas en lugar de deslizarse. Puedes ejercer una autorización, una compensación separada, un rechazo, un reverso, un reembolso y una sonda de cero dólares — cada uno produciendo los mismos registros y webhooks que en producción. → Simular transacciones de Tarjetas Virtuales

Próximos pasos

Resumen de transacciones

El libro mayor unificado — qué contiene un registro y cómo reconciliarlo.

Obtener transacciones de Tarjetas Virtuales

Actividad a nivel de tarjeta, filtros, campos FX y paginación.

Obtener transacciones declinadas

Autorizaciones que nunca se convirtieron en transacciones.

Códigos de rechazo

Cada razón y categoría de rechazo, y qué hacer con cada una.

Simular transacciones de Tarjetas Virtuales

Realiza un gasto de prueba en una tarjeta de staging y observa el ciclo de vida en acción.

Webhooks

Suscríbete a eventos de transacciones, verifica firmas, maneja reintentos.

​Las tres etapas

​Una compra, varios registros

​Flujos de un solo mensaje y de dos mensajes

​Un solo mensaje

​Dos mensajes

​Dónde se sienta el dinero

​Qué registra Fluz en cada etapa

​Autorización

​Autorizaciones que no son compras

​Fondos retenidos

​Reversos

​Compensación y liquidación

​Reembolsos

​Moneda extranjera

​Secuencias de mensajes comunes

​Construir contra el ciclo de vida

​Probar el ciclo de vida

​Próximos pasos

Resumen de transacciones

Obtener transacciones de Tarjetas Virtuales

Obtener transacciones declinadas

Códigos de rechazo

Simular transacciones de Tarjetas Virtuales

Webhooks

Las tres etapas

Una compra, varios registros

Flujos de un solo mensaje y de dos mensajes

Un solo mensaje

Dos mensajes

Dónde se sienta el dinero

Qué registra Fluz en cada etapa

Autorización

Autorizaciones que no son compras

Fondos retenidos

Reversos

Compensación y liquidación

Reembolsos

Moneda extranjera

Secuencias de mensajes comunes

Construir contra el ciclo de vida

Probar el ciclo de vida

Próximos pasos