Ciclo de vida de la transacción

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

Esta página cubre transacciones de tarjetas de circuito abierto — 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 ver 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 le pregunta a Fluz si se puede cobrar la tarjeta. Fluz verifica los controles y la financiación de la tarjeta, y responde.	Aún nada. Los fondos se retenen, no se mueven.
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	La red mueve fondos entre el banco adquirente y el banco emisor.	De banco a banco. Invisible para tu integración.

La liquidación es un proceso bancario que corre detrás del clearing según el calendario de la red. Fluz representa el clearing y la liquidación como un solo evento: cuando una transacción se liquida (clears) en Fluz, trátala como final.

Una compra, varios registros

Una sola compra puede generar una autorización, uno o más clearings y, posiblemente, una reversión o un reembolso. Fluz expone esto mediante tres consultas que responden preguntas distintas:

Feed	Consulta	Qué muestra
Actividad de la tarjeta	`getVirtualCardTransactions`	Gasto en una o más tarjetas, con comercio, MCC, FX y campos de respuesta de la red
Libro mayor de la cuenta	`getTransactions`	Todo movimiento de dinero en la cuenta, con instantáneas de saldo después de cada registro
Autorizaciones rechazadas	`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 original PURCHASE cambia: su monto permanece donde estaba. Si tu sistema reduce la compra original cuando llega un reembolso, vas a contar el crédito dos veces. Haz la conciliación a nivel de registro; 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.

De un solo mensaje

La red envía un mensaje que autoriza y liquida al mismo tiempo. Común en débito con PIN, retiros en cajeros automáticos y transporte. No hay ventana de pendiente: la transacción es casi inmediatamente final.

De dos mensajes

La red envía primero una autorización y el comercio envía el clearing después, típicamente 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 ahí es donde viven la mayoría de los errores de conciliación.

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

Dónde se sienta el dinero

El mismo ciclo de vida, visto desde la cuenta y no desde la red:

Qué registra Fluz en cada etapa

Mensaje de la 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`, revertido pronto	`PENDING`, liberado	`TRANSACTION_CREATE` + `TRANSACTION_UPDATE`
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 liquidar	retención liberada	registro liberado	`TRANSACTION_UPDATE`
Refund	Valor devuelto después de que una compra fue liquidada	`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 rechazo no es una transacción. Las autorizaciones rechazadas nunca ingresan al libro mayor 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 aprobar un cargo, Fluz evalúa la solicitud contra la tarjeta, la cuenta y la financiación detrás de la tarjeta. Todo sucede en bien menos de un segundo, porque la red hará timeout.

Qué se verifica

Que la tarjeta esté ACTIVE — no bloqueada, vencida, pasada su lockDate, ni 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 cubran el monto
Que no se excedan los límites del propio programa bancario

De dónde viene el dinero

Una tarjeta no tiene un saldo propio. Se financia, en el momento de la autorización, desde la pila de fondos configurada al emitir 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, ambos difieren, y el monto aprobado es el que se retiene. Lee el monto del registro de Fluz en lugar de suponer que coincide con lo que pidió el comercio.

Rechazos

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 bloqueada por 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
$0 /$ 0.01 probe	Un comercio confirmando que la tarjeta está activa antes de almacenarla o cobrarla después	Espéralo y no lo cuentes como gasto. Se revierte por sí solo.
Preautorización	Una retención colocada antes de conocer el monto final — hoteles, alquiler de autos, surtidores de combustible	Espera un clearing por un monto diferente, a menudo días después.
Incremental	Una retención adicional apilada sobre una preautorización abierta	Suma las retenciones; no trates la segunda como una segunda compra.
Surtidor de combustible	Un monto fijo establecido por reglas de la red, sin relación con lo efectivamente cargado	El clearing 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 liquida:

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

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

Reversiones

Una reversión cancela una autorización antes de que liquide. La retención se libera y los fondos regresan a la tarjeta. Las reversiones pueden ser totales o parciales. Causas comunes:

El comercio abandonó la venta o el terminal hizo timeout
El artículo estaba agotado, o el titular canceló antes del envío
Se envió una autorización duplicada
La autorización expiró sin un clearing

Una “reversión” después del clearing es realmente un reembolso.Una vez que una transacción ha liquidado, ya no hay retención que 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 un clearing correspondiente es la línea divisoria entre ambos casos.

Clearing y liquidación

El clearing es el comercio enviando el monto final, generalmente como parte de un lote nocturno. Fluz lo concilia con 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 cambian el número.
Puede haber más de un clearing. Un envío dividido liquida en piezas contra una sola autorización, y las piezas pueden llegar fuera de orden.
Puede llegar un clearing sin autorización. Las redes permiten que un comercio haga force-post en algunas situaciones — terminales offline, compras en vuelo, agregación de tarifas de transporte. Fluz monitorea estos casos, pero tu libro mayor debe aceptar una compra que aparece ya liquidada sin fase pendiente.
La conciliación no está garantizada. En casos raros, los identificadores en un clearing no se alinean con la autorización a la que pertenece y el clearing aparece como su propio registro.

No concilies solo con identificadores de referencia de la 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 momento de crear tu orden, guarda el record_id y reference_id de Fluz contra tu propio pedido. → Conciliación contra tu propio sistema

Reembolsos

Cuando un comercio devuelve valor, envía un crédito de vuelta a través de la red. Fluz lo registra como un REFUND en el feed de la tarjeta y como un crédito en el libro mayor. Puede llegar como una autorización que luego liquida, o como un clearing por sí solo. Dos casos que rompen el emparejamiento ingenuo:

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 compras diferentes pueden compartir identificadores de red y llegar agrupados.

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

Moneda extranjera

Una compra realizada en otra moneda liquida en USD, con el monto original preservado en el registro:

Campo	Significado
`originalCurrencyCode`	Código ISO 4217 de la moneda en la que cobró el comercio
`originalCurrencyAmount`	El monto original en unidades menores — `6300` HKD son 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 ocurre en el clearing, por lo que una autorización en moneda extranjera y su clearing suelen diferir en 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, transporte — 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 una folio de hotel por debajo de la preautorización
`AUTHORIZE` → `AUTHORIZE` → `CLEAR`	Preautorización más autorización incremental, liquidado una vez
`AUTHORIZE` → `CLEAR` → `CLEAR`	Envío dividido, liquidando en piezas
`AUTHORIZE` → `REVERSAL`	Venta abandonada antes del clearing
`AUTHORIZE` → `REVERSAL` (parcial) → `CLEAR`	Parte de la retención liberada, el resto liquidado
`AUTHORIZE` → (expiry)	Nunca llega el clearing; la retención se libera al expirar
`CLEAR` with no `AUTHORIZE`	Force post — terminal offline, en vuelo, agregación de transporte
`AUTHORIZE` → `CLEAR` → `REFUND`	Compra reembolsada después, total o parcialmente
`VERIFICATION` ($0.00)	Validación de tarjeta en archivo, revertida poco después

Construyendo contra el ciclo de vida

Trata pendiente y liquidado como cosas distintas

Nunca muestres una autorización pendiente como una compra completada y nunca sumes autorizaciones y clearings juntos. Si necesitas un solo número, suma los registros liquidados 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 para siempre en su monto de autorización. → Webhooks

Sincroniza con updatedGte, no con createdGte

Un registro creado como PENDING y liquidado después cambia su marca de tiempo de actualización, no su marca de tiempo de creación. Una sincronización por fecha de creación se pierde silenciosamente cada liquidación.

Concilia saldos desde instantáneas

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

Haz que los handlers sean idempotentes

Los webhooks reintentan y los clearings pueden llegar fuera de orden. Clavea con el identificador de registro de Fluz y haz que la reejecución no tenga efecto.

Probando el ciclo de vida

Las tarjetas de staging son registros reales de tarjetas pero no están en una red en vivo, por lo que las transacciones se inyectan contra ellas en lugar de pasarlas por un lector. Puedes ejercitar una autorización, un clearing separado, un rechazo, una reversión, 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 conciliarlo.

Obtener transacciones de Tarjetas Virtuales

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

Obtener transacciones rechazadas

Autorizaciones que nunca se convirtieron en transacciones.

Códigos de rechazo

Cada motivo y categoría de rechazo, y qué hacer con cada uno.

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 transacción, verifica firmas, maneja reintentos.

​Las tres etapas

​Una compra, varios registros

​Flujos de un solo mensaje y de dos mensajes

​De un solo mensaje

​De dos mensajes

​Dónde se sienta el dinero

​Qué registra Fluz en cada etapa

​Autorización

​Autorizaciones que no son compras

​Fondos retenidos

​Reversiones

​Clearing y liquidación

​Reembolsos

​Moneda extranjera

​Secuencias de mensajes comunes

​Construyendo contra el ciclo de vida

​Probando el ciclo de vida

​Próximos pasos

Resumen de transacciones

Obtener transacciones de Tarjetas Virtuales

Obtener transacciones rechazadas

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

De un solo mensaje

De dos mensajes

Dónde se sienta el dinero

Qué registra Fluz en cada etapa

Autorización

Autorizaciones que no son compras

Fondos retenidos

Reversiones

Clearing y liquidación

Reembolsos

Moneda extranjera

Secuencias de mensajes comunes

Construyendo contra el ciclo de vida

Probando el ciclo de vida

Próximos pasos