> ## Documentation Index > Fetch the complete documentation index at: https://docs.fluz.app/llms.txt > Use this file to discover all available pages before exploring further. # Ciclo de vida de las transacciones > Cómo una compra con tarjeta viaja desde la terminal del comercio hasta tu libro mayor — autorización, compensación, liquidación, reversos y reembolsos — y qué registra Fluz en cada paso. 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](/features/transactions-details-overview) 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: ```text theme={null} 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. ```mermaid theme={null} sequenceDiagram autonumber participant M as Merchant participant N as Card network participant F as Fluz participant Y as Your integration M->>N: Purchase, $25.00 N->>F: Authorize and clear F->>F: Spend controls + funding check F-->>N: Approved N-->>M: Approved F->>Y: TRANSACTION_CREATE F->>Y: TRANSACTION_UPDATE (cleared) ``` ### 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. ```mermaid theme={null} sequenceDiagram autonumber participant M as Merchant participant N as Card network participant F as Fluz participant Y as Your integration M->>N: Authorization request, $50.00 N->>F: Authorize F->>F: Spend controls + funding check F-->>N: Approved, funds held N-->>M: Approved F->>Y: TRANSACTION_CREATE (pending) Note over M,F: Hours to days pass M->>N: Batch submitted, $54.00 with tip N->>F: Clear F->>F: Match to authorization, finalize F->>Y: TRANSACTION_UPDATE (cleared, $54.00) ``` **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: ```mermaid theme={null} stateDiagram-v2 [*] --> Available: Funds in the spend account Available --> Held: Authorization approved Held --> Available: Reversal or expiration Held --> Cleared: Clearing received Available --> Cleared: Single-message transaction Cleared --> Credited: Refund received Credited --> [*] Cleared --> [*] ``` *** ## 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](/concepts/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](/features/decline-codes). *** ## 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. * 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 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: 1. La cuenta de gasto indicada en `userCashBalanceId`, o la predeterminada de la cuenta 2. El saldo de prepago (tarjeta de regalo), a menos que `usePrepaymentBalance: false` 3. El saldo de recompensas, a menos que `useRewardsBalance: false` 4. 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](/Manage-Virtual-Card-Funding-Sources) 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. 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](/features/decline-codes) ### 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](/features/transactions-details-overview#reconciling-against-your-own-system) *** ## 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 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. `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](/fluz-dashboard/webhooks) 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. 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. 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](/Simulate-Virtual-Card-Transactions) *** ## Próximos pasos El libro mayor unificado — qué contiene un registro y cómo reconciliarlo. Actividad a nivel de tarjeta, filtros, campos FX y paginación. Autorizaciones que nunca se convirtieron en transacciones. Cada razón y categoría de rechazo, y qué hacer con cada una. Realiza un gasto de prueba en una tarjeta de staging y observa el ciclo de vida en acción. Suscríbete a eventos de transacciones, verifica firmas, maneja reintentos.