Transacciones - Lerian

Una Transacción en Midaz registra un evento financiero completo. Una transacción suele usar múltiples cuentas y saldos. Midaz funciona con un sistema de contabilidad de partida doble que mantiene equilibrado cada movimiento financiero. Con la función de múltiples saldos, cada operación especifica la cuenta y la clave de saldo que se usará. Luego puedes debitar o acreditar distintos saldos lógicos de la misma cuenta (por ejemplo, credit, operational o collateral).

Si no proporcionas una balanceKey, la transacción usa el saldo predeterminado.

Contabilidad de partida doble

El sistema de partida doble sigue un solo principio. Cada transacción tiene dos asientos: un débito y un crédito. Esta estructura registra toda la actividad financiera y mantiene tus cuentas equilibradas. Cada transacción afecta a dos cuentas y las mantiene en equilibrio:

Los débitos muestran el valor recibido o los recursos consumidos.
Los créditos muestran el valor entregado o los recursos proporcionados.

Midaz registra y equilibra automáticamente cada débito y crédito.

Ejemplo

En este ejemplo, transfieres R$1000 de una cuenta a otra. La transacción tiene dos operaciones:

Una operación para debitar R$1,000.00 de la cuenta de origen.
Una operación para acreditar R$1,000.00 en la cuenta de destino.

Midaz captura ambos asientos automáticamente. Puedes ver y analizar estos movimientos mediante la API o Lerian Console.

Transacciones N:N (muchos a muchos)

Los sistemas financieros tradicionales limitan las transacciones a relaciones de uno a uno o de uno a muchos. Midaz admite transacciones N:N. Una sola transacción puede usar múltiples cuentas de origen y destino.

Ejemplos

Pago de marketplace: una sola cuenta escrow paga a varios vendedores, y cada vendedor paga una comisión de la plataforma.
Persona a persona con comisiones: una transacción debita al pagador y acredita tanto al receptor como a una cuenta de comisiones.

Midaz procesa cada caso como una sola transacción atómica. Debita y acredita a todas las partes en conjunto.

Atomicidad e integridad

Las transacciones son atómicas. O todas las operaciones se ejecutan correctamente, o ninguna lo hace. No se producen eventos financieros parciales. Si alguna parte de una transacción no pasa la validación (por ejemplo, una cuenta no tiene fondos suficientes), Midaz no aplica la transacción. El ledger permanece consistente.

Origen de la transacción

Una transacción en Midaz puede iniciarse desde una sola fuente o desde múltiples fuentes.

La suma de los valores en source debe ser igual al valor que sigue a send. También debe ser igual a la suma de los valores en distribute.

Fuente única

En una transacción de fuente única, Midaz toma el monto de una cuenta de origen. También puedes indicar un saldo específico.

Ejemplo

En este ejemplo (Figura 1):

Midaz toma BRL 30.00 de @account1 (saldo credit).
Envía el 100% a @destinationAccount1 (saldo operational)

Transacción de fuente única que mueve BRL 30.00 de una cuenta de origen a una sola cuenta de destino — Figura 1. Ejemplo de una transacción de fuente única.

Ejemplos de código

{
  "description": "single source transaction",
  "send": {
    "asset": "BRL",
    "value": "30.00",
    "source": {
      "from": [
        {
          "accountAlias": "@account1",
          "balanceKey": "credit", // optional
          "amount": {
            "asset": "BRL",
            "value": "30.00"
          }
        }
      ]
    },
    "distribute": {
      "to": [
        {
          "accountAlias": "@destinationAccount1",
          "balanceKey": "operational", // optional
          "share": {
            "percentage": 100
          }
        }
      ]
    }
  }
}

Múltiples fuentes

En una transacción de múltiples fuentes, Midaz toma fondos de varias cuentas o saldos.

Ejemplo

En este ejemplo (Figura 2):

Midaz envía BRL 30.00 a la cuenta de destino (@destinationAccount1).
- BRL 15.00 de @account1 (saldo default).
- BRL 15.00 de @account2 (saldo investment).
La cuenta de destino recibe el 100% del monto.

Transacción de múltiples fuentes en la que se toman BRL 30.00 de dos cuentas de origen y se envían a una sola cuenta de destino — Figura 2. Ejemplo de una transacción de múltiples fuentes.

Ejemplos de código

{
  "description": "multi-source transaction",
  "send": {
    "asset": "BRL",
    "value": "30.00",
    "source": {
      "from": [
        {
          "accountAlias": "@account1",
          "balanceKey": "default",
          "amount": {
            "asset": "BRL",
            "value": "15.00"
          }
        },
        {
          "accountAlias": "@account2",
          "balanceKey": "investment",
          "amount": {
            "asset": "BRL",
            "value": "15.00"
          }
        }
      ]
    },
    "distribute": {
      "to": [
        {
          "accountAlias": "@destinationAccount1",
          "share": {
            "percentage": 100
          }
        }
      ]
    }
  }
}

Destino de la transacción

Al igual que las fuentes, los destinos pueden ser únicos o múltiples.

Destino único

En una transacción de destino único, Midaz envía el monto a una sola cuenta de destino.

Ejemplo

En este ejemplo (Figura 3):

Midaz toma BRL 30.00 de una cuenta externa (@external/BRL).
Envía el 100% a la cuenta de destino (@destinationAccount1).

Transacción de destino único que mueve BRL 30.00 de una cuenta externa a una cuenta de destino — Figura 3. Ejemplo de una transacción de destino único.

Ejemplos de código

{
   "description":"single destination transaction",
   "send":{
      "asset":"BRL",
      "value":"30.00",
      "source":{
         "from":[
            {
               "accountAlias":"@external/BRL",
               "amount":{
                  "asset":"BRL",
                  "value":"30.00"
               }
            }
         ]
      },
      "distribute":{
         "to":[
            {
               "accountAlias":"@destinationAccount1",
               "share":{
                  "percentage":100
               }
            }
         ]
      }
   }
}

Múltiples destinos

En una transacción de múltiples destinos, Midaz divide el monto entre varias cuentas de destino. Puedes distribuir los valores por porcentajes, montos fijos o el saldo restante.

Ejemplo

En este ejemplo (Figura 4):

Midaz toma BRL 100 de la cuenta de origen (@account1).
El 38% del monto va a la cuenta 2 (@account2).
El 50% va a la cuenta 3 (@account3).
Un monto fijo de BRL 2.00 va a la cuenta 4 (@account4).
El monto restante va a la cuenta 5 (@account5).

Transacción de múltiples destinos que divide BRL 100.00 de una cuenta de origen entre cinco cuentas de destino por porcentaje y montos fijos — Figura 4 Ejemplo de una transacción de múltiples destinos.

Ejemplo de código

{
   "description":"multi-destination transaction",
   "send":{
      "asset":"BRL",
      "value":"100.00",
      "source":{
         "from":[
            {
               "accountAlias":"@account1",
               "amount":{
                  "asset":"BRL",
                  "value":"100.00"
               }
            }
         ]
      },
      "distribute":{
         "to":[
            {
               "accountAlias":"@account2",
               "share":{
                  "percentage":38
               }
            },
            {
               "accountAlias":"@account3",
               "share":{
                  "percentage":50
               }
            },
            {
               "accountAlias":"@account4",
               "amount":{
                  "asset":"BRL",
                  "value":"2.00"
               }
            },
            {
               "accountAlias":"@account5",
               "remaining":"remaining"
            }
         ]
      }
   }
}

Múltiples fuentes y múltiples destinos

Estas transacciones usan múltiples fuentes y múltiples destinos. Son útiles en casos como una campaña de crowdfunding. Midaz agrupa las contribuciones y las distribuye entre varios destinatarios.

Ejemplo

En este ejemplo (Figura 5):

La donación es de BRL 4,000.00. Midaz la toma de cuatro cuentas distintas.
- El 25% proviene de la cuenta 1 (@account1).
- El 25% proviene de la cuenta 2 (@account2).
- El 40% proviene de la cuenta 3 (@account3)
- El 10% proviene de la cuenta 4 (@account4).
Midaz distribuye las donaciones entre cuatro cuentas independientes. Cada cuenta recibe un porcentaje del 25% del total.

Transacción de múltiples fuentes y múltiples destinos que toma BRL 4,000.00 de cuatro cuentas y lo distribuye de forma equitativa entre cuatro cuentas de destino — Figura 5. Ejemplo de una transacción de múltiples fuentes y múltiples destinos.

Ejemplos de código

{
   "description":"multi-source and multi-destination transaction",
   "send":{
      "asset":"BRL",
      "value":"4000.00",
      "source":{
         "from":[
            {
               "accountAlias":"@account1",
               "share":{
                  "percentage":25
               }
            },
            {
               "accountAlias":"@account2",
               "share":{
                  "percentage":25
               }
            },
            {
               "accountAlias":"@account3",
               "share":{
                  "percentage":40
               }
            },
            {
               "accountAlias":"@account4",
               "share":{
                  "percentage":10
               }
            }
         ]
      },
      "distribute":{
         "to":[
            {
               "accountAlias":"@donation1",
               "share":{
                  "percentage":25
               }
            },
            {
               "accountAlias":"@donation2",
               "share":{
                  "percentage":25
               }
            },
            {
               "accountAlias":"@donation3",
               "share":{
                  "percentage":25
               }
            },
            {
               "accountAlias":"@donation4",
               "share":{
                  "percentage":25
               }
            }
         ]
      }
   }
}

Estados de la transacción

Cada transacción en Midaz tiene un estado. El estado refleja su etapa actual en el ciclo de vida. Necesitas estos estados para diseñar flujos de transacciones, configurar consumidores de eventos y leer los datos del ledger.

Estado	Qué significa	¿Afecta los saldos?	Cómo se crea
`CREATED`	Se inició una transacción de reversión y se está procesando. Es un estado transitorio que avanza automáticamente a `APPROVED` cuando se completa la reversión.	Sí	Revierte una transacción
`APPROVED`	La transacción se completó correctamente. Los fondos se movieron entre cuentas.	Sí	Transacción directa (sin el flag `pending`), confirmación de una transacción `PENDING`, o progresión automática desde `CREATED`
`PENDING`	Una transacción de dos fases está a la espera de confirmación. Los fondos están reservados en `on_hold` pero aún no se transfirieron.	Sí (reserva)	Crea una transacción con `"pending": true`
`CANCELED`	Se canceló una transacción de dos fases. Los fondos reservados se liberan de vuelta a `available`.	Sí (liberación)	Cancela una transacción pendiente
`NOTED`	Una transacción de anotación registrada en el ledger sin afectar los saldos. Las operaciones conservan la estructura de partida doble, pero todos los campos de saldo quedan en cero.	No	Crea una anotación de transacción

Usa el estado NOTED para importar transacciones heredadas, registrar registros de auditoría y dejar constancia de eventos de cumplimiento. Se adapta a cualquier caso en el que la transacción deba existir en el ledger, pero los saldos ya se hayan liquidado en otro lugar.

Transiciones de estado

Las transacciones siguen rutas predecibles a través de estos estados:

Flujo estándar: → APPROVED (un solo paso)
Flujo de dos fases: → PENDING → APPROVED (confirmación) o CANCELED (cancelación)
Flujo de reversión: → CREATED → APPROVED (automático)
Flujo de anotación: → NOTED (terminal, sin transiciones)

Una vez que una transacción llega a NOTED o CANCELED, no puede transicionar más. Ambos son estados terminales.

Flujo de la transacción

Cuando una transacción se inicia, Midaz valida:

Las cuentas involucradas.
Los saldos especificados (balanceKey, o default si no se indica).
Los permisos (allowSending, allowReceiving).
Fondos disponibles suficientes en el saldo seleccionado.

Si la validación se aprueba y la transacción no está pendiente (flujo de transacción de dos fases), Midaz transfiere el monto de inmediato. Mueve el monto de la cuenta de origen a la cuenta de destino, desde el saldo disponible. Este proceso es síncrono. Si se completa correctamente, el estado de la transacción pasa a APPROVED.

Inicia este tipo de transacción solo si tienes la intención de confirmarla en el ledger de inmediato.

Para las transacciones que necesitan validación o aprobación primero, usa el flag pending para crear una transacción de dos fases.

Transacción de dos fases

En este flujo, Midaz crea la transacción con el estado PENDING. Midaz no mueve los fondos de inmediato. En cambio, reserva el monto en el saldo correcto (balanceKey, o default si no proporcionas uno).

Midaz mueve los fondos reservados de available a on_hold.
Midaz registra una operación, con el tipo ON_HOLD, en el saldo de origen. El saldo de destino permanece intacto: aún no se registra ningún débito ni crédito.
Debes ejecutar explícitamente commit para hacer la transferencia, o cancel para liberar los fondos.

La función de transacción de dos fases da soporte a Flowker. Reservas los fondos al inicio de un workflow y ejecutas las validaciones más adelante. Midaz garantiza la ejecución si el workflow aprueba la transacción.

En la Figura 6, puedes ver un ejemplo de una transacción de dos fases con antifraude.

Transacción de dos fases en un workflow antifraude, que reserva los fondos primero y los confirma o cancela después de la validación — Figura 6. Ejemplo de workflow antifraude

Flujo de la transacción de dos fases

1. Crea una transacción de dos fases

Usa el endpoint Crea una transacción con JSON con "pending": true.

Midaz valida las cuentas, los saldos especificados (balanceKey), los permisos (allowSending, allowReceiving) y los fondos disponibles. Si es válida:

Midaz reserva los fondos en el saldo correcto.
Midaz establece el estado de la transacción en PENDING.
Midaz almacena los metadatos y registra la operación ON_HOLD de origen. Todavía no llega ningún débito ni crédito al destino.

2. Confirma o cancela la transacción pendiente

Confirmar: finaliza la transacción. Los fondos se mueven de on_hold al saldo de destino, y Midaz agrega las operaciones DEBIT y CREDIT. Una transacción de dos fases confirmada tiene un total de tres operaciones (ON_HOLD, DEBIT, CREDIT).
- Usa el endpoint Confirma una transacción pendiente.
- Estado: APPROVED.
Cancelar: libera los fondos reservados de vuelta a available en el mismo saldo.
- Usa el endpoint Cancela una transacción pendiente.
- Estado: CANCELED.

Transacciones pasadas

Midaz también admite transacciones pasadas. Las instituciones pueden importar eventos financieros heredados y mantener la precisión histórica.

Usa el campo opcional transactionDate para establecer la fecha original de la transacción.
Las transacciones con impacto financiero recalculan el estado histórico del saldo como si Midaz las hubiera procesado en esa fecha.
Las transacciones creadas mediante el endpoint Crea una anotación de transacción validan la estructura, pero no afectan los saldos. Son adecuadas para auditorías, cumplimiento e importaciones donde los saldos deben permanecer sin cambios.

Ejemplo

{
  "description": "past transaction example",
  "transactionDate": "2025-01-01T13:38:31.064Z", // optional
  "send": {
    "asset": "BRL",
    "value": "1000",
    "source": {
      "from": [
        {
          "accountAlias": "@external/BRL",
          "amount": {
            "asset": "BRL",
            "value": "1000"
          }
        }
      ]
    },
    "distribute": {
      "to": [
        {
          "accountAlias": "@account1_BRL",
          "amount": {
            "asset": "BRL",
            "value": "1000"
          }
        }
      ]
    }
  }
}

Envía todas las transacciones pasadas antes de iniciar las operaciones en vivo. Así, Midaz recalcula los saldos de forma consistente en todo el ledger.

Transacciones sin impacto financiero

Midaz puede crear transacciones que registra en el ledger, pero que no afectan los saldos de las cuentas. Estas transacciones mantienen la integridad estructural y dejan los saldos sin cambios. Esta función es útil cuando necesitas:

Importar transacciones heredadas sin modificar los saldos.
Registrar eventos de auditoría o cumplimiento.
Agregar operaciones de negocio que el ledger debe rastrear, pero que no mueven fondos.

¿Cómo funciona?

Cuando creas una transacción sin impacto financiero:

Midaz almacena los campos balance y balanceAfter como 0 para preservar la validación de partida doble.
Cada operación tiene un campo balanceAffected (booleano):
- true → la operación afecta el saldo de la cuenta.
- false → Midaz registra la operación en el ledger, pero no modifica los saldos.

Incluso cuando Midaz no actualiza ningún saldo, aplica las reglas de partida doble. Esto mantiene la consistencia en todas las transacciones del ledger.

Ejemplo

{
  "description": "annotation example",
  "transactionDate": "2025-01-01T13:38:31.064Z",
  "send": {
    "asset": "BRL",
    "value": "1000",
    "source": {
      "from": [
        {
          "accountAlias": "@external/BRL",
          "amount": {
            "asset": "BRL",
            "value": "1000"
          },
          "balanceAffected": false
        }
      ]
    },
    "distribute": {
      "to": [
        {
          "accountAlias": "@account1_BRL",
          "amount": {
            "asset": "BRL",
            "value": "1000"
          },
          "balanceAffected": false
        }
      ]
    }
  }
}

Endpoint relacionado

Crea una anotación de transacción: registra una transacción sin impacto financiero en el ledger.

Publicación de eventos en tiempo real

Midaz admite la publicación de eventos en tiempo real mediante RabbitMQ. Puedes hacer seguimiento del estado de tus transacciones a medida que ocurren. Después de habilitarlo, cada transacción genera un evento: APPROVED, PENDING, CANCELED, CREATED o NOTED. Los sistemas externos se suscriben a estos eventos mediante enrutamiento basado en temas. Para más información sobre cómo publicar y consumir eventos de transacciones, consulta la página Publicador de eventos.

Entradas, salidas y cuentas externas

Midaz usa un ledger de partida doble. Todo el valor que entra o sale del sistema debe pasar por una cuenta especial: la Cuenta externa. Midaz representa esta cuenta como @external/{{assetCode}}. Actúa como el puente entre Midaz y el mundo financiero externo (bancos, PSP, rieles de pago, etc.).

¿Por qué importa esto?

Cuando inicializas el ledger por primera vez, todas las cuentas, incluida @external, empiezan con saldo cero. Para reflejar los saldos del mundo real, como los fondos institucionales que se mantienen fuera de Midaz, debes iniciar una transacción que inyecte fondos en las cuentas de Midaz y debite la cuenta externa. Esta es la única forma de ingresar fondos a Midaz.

Entradas: agregar valor al ledger

Para acreditar una cuenta interna desde fuera del ledger:

Origen: @external/{{assetCode}} (por ejemplo, @external/BRL).
Destino: una o más cuentas internas (por ejemplo, @organization.main).

Ejemplo: primer depósito en el ledger Tu institución mantiene R$10,000 en un banco del mundo real y quiere ingresarlos a Midaz. Creas una transacción:

Origen	Destino	Monto
@external/BRL	@accountA	BRL 10,000

Esto debita la cuenta externa y acredita tu cuenta interna. La cuenta externa ahora muestra un saldo negativo. Esto es lo esperado: representa el monto total que tu organización ingresó al ledger.

Salidas: mover valor fuera del ledger

Para mover valor del ledger a un destino externo:

Origen: una o más cuentas de Midaz.
Destino: @external/{{assetCode}}.

Ejemplo: una transferencia Pix del ledger a un banco externo

Origen	Destino	Monto
@accountA	@external/BRL	BRL 1,000

Esto debita @accountA y acredita la cuenta externa. Luego, tu sistema transfiere los fondos al destinatario mediante SPI u otra integración.

Comportamiento y reglas de saldo

@external/{{assetCode}} puede tener un saldo cero o negativo, pero nunca positivo.
Su saldo siempre es el inverso del saldo combinado de todas las cuentas de Midaz que tienen ese activo.
Cada entrada aumenta la liquidez interna y reduce el saldo de la cuenta externa (es decir, simula un depósito).
Cada salida hace lo contrario.

Todo el valor que se mueve entre el mundo exterior y el ledger de Midaz debe pasar por la cuenta externa.Nada entra o sale del sistema sin una transacción formal.

Establecer una fecha de transacción personalizada

El campo transactionDate permite establecer una fecha personalizada para una transacción, independiente del momento en que la envías a la API.

Opcional. Si lo omites, Midaz usa la marca de tiempo actual.
Formatos aceptados:
- ISO 8601 con zona horaria: 2026-01-15T10:30:00Z
- ISO 8601 sin zona horaria: 2026-01-15T10:30:00
- Solo fecha: 2026-01-15
Restricción: no puedes usar una fecha futura. Una fecha futura devuelve el error 0121.
Restricción: no puedes usarlo en transacciones PENDING. Un transactionDate con "pending": true devuelve el error 0122.

Casos de uso

Registrar transacciones ocurridas en el pasado (por ejemplo, correcciones del mismo día)
Importar datos financieros históricos a un ledger nuevo
Conciliar con sistemas externos que usan una fecha de registro distinta

Transaction Routes

La API de Transaction Routes permite el procesamiento estructurado y validado de transacciones en Midaz.

Lerian Console y la documentación del producto llaman a este concepto Accounting Routes. El recurso y los endpoints de la API mantienen el nombre transactionRoute / Transaction Routes. Ambos se refieren a la misma ruta en el nivel de transacción.

La API de Transactions ejecuta eventos financieros: débitos y créditos entre cuentas. Transaction Routes define plantillas para cómo estructurar y validar estos eventos. Esto los mantiene consistentes y correctos. Piensa en esto como la capa de validación. Hace que las transacciones de negocio sigan patrones predefinidos y mantengan una estructura financiera adecuada. Por ejemplo, una comisión, un depósito o un pago pueden necesitar distintos tipos de cuenta, reglas de validación y estructuras. No gestionas la validación por separado para cada transacción. En cambio, configuras reglas predefinidas. Estas reglas le indican a Midaz: “Cuando el usuario envíe este tipo de transacción, valídala contra estos requisitos de cuenta y patrones de estructura.” Cada Transaction Route combina varias Operation Routes. Una Operation Route define un componente de una transacción. Establece los requisitos de cuenta, la dirección (origen o destino) y las reglas de validación para cada “tramo” del evento financiero.

No uses el campo route en las entradas FromTo. Usa routeId en su lugar. routeId acepta un UUID que hace referencia a una Operation Route creada mediante la API de Operation Routes. Midaz mantiene el campo route por compatibilidad con versiones anteriores, pero lo eliminará en una versión futura.

¿Por qué importa esto?

Con Transaction Routes, puedes:

Mantener una estructura de transacción consistente en toda tu aplicación.
Validar eventos financieros contra patrones predefinidos.
Configurar plantillas de transacción sin cambios de código.
Mantener la integridad de los datos mediante validación estructurada.

Iniciar una transacción

Cuando creas transacciones mediante la API, implementa siempre la idempotencia para evitar el procesamiento duplicado. Midaz ofrece soporte de idempotencia integrado mediante el encabezado X-Idempotency. Valida el encabezado de respuesta X-Idempotency-Replayed para distinguir las transacciones nuevas de las repeticiones almacenadas en caché. Consulta Reintentos e idempotencia para más detalles.

Usa la API de transacciones JSON para iniciar una transacción.

Forma de la solicitud JSON en v2

Cada lado de la transacción usa una representación: from o sources, e independientemente to o destinations. No envíes ambas representaciones para el mismo lado, y no envíes un null explícito para un campo escalar sin usar. Cada elemento de sources o destinations requiere account y exactamente una expresión de valor: amount o share. La expresión remaining no se acepta en v2. Cada arreglo acepta como máximo 500 elementos. share.percentage va de 1 a 100; share.percentageOfPercentage va de 0 a 100, donde 0 significa sin restricción adicional. Las solicitudes de creación en v2 tienen un límite de cuerpo de 1 MiB.

Uso del endpoint JSON

Para crear una transacción con JSON, usa el endpoint Crea una transacción con JSON.

Si necesitas reservar fondos antes de completar la transferencia, establece el campo pending en true (flujo de transacción de dos fases).

Revertir una transacción

Midaz admite la reversión de transacciones. Puedes deshacer una transacción aprobada. Midaz crea una transacción espejo que invierte los débitos y créditos originales. Este mecanismo conserva registros de auditoría completos y anula el impacto financiero en los saldos de las cuentas.

La reversión crea una transacción nueva que compensa la original. La transacción original permanece en el historial del ledger para una trazabilidad completa.

La reversión no envía una clave de idempotencia propia, por lo que Midaz deriva una. Lee el encabezado de respuesta X-Idempotency-Replayed: true significa que recibiste una reversión almacenada en caché en lugar de una recién creada. Trata una repetición como una señal para verificar el estado del origen antes de reintentar.

¿Cómo funciona?

Cuando reviertes una transacción, Midaz automáticamente:

Invierte las operaciones:
- Las operaciones CREDIT se convierten en operaciones de origen (from).
- Las operaciones DEBIT se convierten en operaciones de destino (to).
Crea una transacción nueva con:
- El mismo monto y código de activo.
- La misma descripción y los mismos metadatos.
- Operaciones invertidas (los destinatarios se convierten en remitentes, y los remitentes en destinatarios).
- Estado inicial: CREATED (no PENDING) → luego avanza a APPROVED.
- parentTransactionID que hace referencia a la transacción original.
Procesa la reversión mediante el flujo estándar de transacciones: validación, actualización de saldos y registro en el historial.

Ejemplo

Transacción original:

Cuenta A (débito -100) → Cuenta B (crédito +100)

Transacción de reversión creada:

Cuenta B (débito -100) → Cuenta A (crédito +100)

Resultado:

La cuenta A vuelve a su saldo anterior (recibe de vuelta los -100).
La cuenta B vuelve a su saldo anterior (pierde los +100).
Ambas transacciones permanecen en el historial del ledger con fines de auditoría.
La transacción de reversión incluye un parentTransactionID que apunta a la original.

Restricciones de la reversión

Midaz aplica reglas estrictas para mantener la integridad del ledger. Una reversión falla en estos casos:

1. La transacción ya tiene una reversión

Midaz permite solo una reversión por transacción.
Esto evita múltiples reversiones de la misma transacción.

2. La transacción ya es una reversión

No puedes revertir una transacción que en sí misma es una reversión.
Esto evita “reversiones de reversiones”.

3. El estado de la transacción no es APPROVED

Solo puedes revertir transacciones aprobadas.
No puedes revertir una transacción con estado PENDING, CREATED o CANCELED.

4. La transacción no se puede revertir

Esto ocurre cuando la transacción no tiene operaciones válidas para invertir.
Por ejemplo, una transacción sin operaciones estándar CREDIT o DEBIT.

5. Una ruta de operación de la transacción no es bidireccional

Cada operación que lleve un routeId debe hacer referencia a una Operation Route cuyo operationType sea bidirectional.
Una ruta source o destination no se puede revertir: Midaz devuelve el error 0150 (Route Not Bidirectional).
Planifica esto al diseñar rutas. Consulta Accounting Routes.

Midaz revierte las operaciones CREDIT y DEBIT. No revierte las operaciones ON_HOLD ni RELEASE.

Casos de uso

La reversión de transacciones ayuda en varios escenarios operativos:

1. Reversión de un pago incorrecto

Un cliente pagó BRL 500 al proveedor equivocado.

Revierte la transacción.
Los fondos regresan a la cuenta del cliente.
El cliente puede iniciar un nuevo pago al proveedor correcto.

2. Cancelación de una compra

Una tienda procesó una venta de BRL 1,000, pero el cliente cancela la compra.

Revierte la transacción de venta.
Los fondos regresan a la cuenta del cliente.

3. Corrección de un error operativo

Un operador creó una transacción con el monto incorrecto.

Revierte la transacción incorrecta.
Crea una transacción nueva con el monto correcto.

4. Devolución de un producto

Un cliente compró y pagó BRL 200, pero devolvió el producto.

Revierte la transacción de pago.
El cliente recibe una devolución.

5. Compensación por fallo de integración

Una transacción se aprueba, pero falla en un sistema externo.

Revierte para deshacer la operación contable.
Los saldos regresan a su estado anterior.

Bloqueo y desbloqueo de fondos

Algunos escenarios requieren marcar los fondos como bloqueados (una retención de cumplimiento, una orden judicial, una investigación por fraude) y liberarlos más adelante. Midaz admite esto con dos endpoints dedicados. Estos endpoints crean transacciones cuyas operaciones tienen el tipo BLOCK y UNBLOCK. Estas transacciones aceptan el mismo cuerpo que el endpoint Crea una transacción con JSON, con dos diferencias clave:

Siempre se registran de inmediato. Midaz ignora el campo pending en el cuerpo de la solicitud y lo reemplaza por false. Las transacciones de bloqueo y desbloqueo nunca son de dos fases. Pasan directamente a APPROVED.
Las operaciones tienen el tipo BLOCK o UNBLOCK. Esta clasificación las distingue en el ledger y en las consultas de operaciones. Puedes auditar los movimientos de fondos bloqueados sin revisar los metadatos.

Midaz es independiente del motivo de negocio para bloquear o desbloquear fondos. Registra el motivo en el campo metadata.

Una transacción de bloqueo registra un movimiento en el ledger con operaciones del tipo BLOCK. Esto difiere de los controles en el nivel de saldo en Saldos: los flags de permisos (allowSending / allowReceiving) y los saldos de garantía. Esos controles restringen el movimiento, pero no registran ninguna transacción. Usa un saldo de garantía para una restricción operativa permanente. Usa una transacción de bloqueo cuando necesites un asiento auditable en el ledger.

Usa el endpoint Crea una transacción de bloqueo para bloquear fondos.
Usa el endpoint Crea una transacción de desbloqueo para liberar fondos previamente bloqueados.

Gestión de transacciones

Puedes gestionar tus Transacciones mediante la API o Lerian Console.

Mediante la API

Crea una transacción con JSON: envía una transacción directamente mediante un payload JSON.
Confirma una transacción pendiente: finaliza una transacción reservada.
Cancela una transacción pendiente: libera los fondos reservados sin ejecutar.
Revierte una transacción: crea una transacción de reversión para deshacer una transacción aprobada.
Crea una transacción de entrada: registra fondos entrantes de fuentes externas en el ledger.
Crea una transacción de salida: mueve fondos de cuentas internas al mundo externo.
Crea una transacción de bloqueo: marca fondos como bloqueados con operaciones del tipo BLOCK.
Crea una transacción de desbloqueo: libera fondos previamente bloqueados con operaciones del tipo UNBLOCK.
Enumera las transacciones: consulta todas las Transacciones de tu espacio de trabajo.
Obtén una transacción: obtén los detalles de una Transacción específica.
Actualiza una transacción: edita los metadatos de una Transacción existente.
Crea una anotación de transacción: registra una transacción sin impacto financiero en el ledger.

Mediante Lerian Console

Puedes hacer todas las acciones de gestión de Transacciones (ver, crear y cancelar) mediante Lerian Console. Obtén más información en la guía Gestión de transacciones.

​Contabilidad de partida doble

​Ejemplo

​Transacciones N:N (muchos a muchos)

​Ejemplos

​Atomicidad e integridad

​Origen de la transacción

​Fuente única

​Ejemplo

​Múltiples fuentes

​Ejemplo

​Destino de la transacción

​Destino único

​Ejemplo

​Múltiples destinos

​Ejemplo

​Múltiples fuentes y múltiples destinos

​Ejemplo

​Estados de la transacción

​Transiciones de estado

​Flujo de la transacción

​Transacción de dos fases

​Flujo de la transacción de dos fases

​1. Crea una transacción de dos fases

​2. Confirma o cancela la transacción pendiente

​Transacciones pasadas

​Ejemplo

​Transacciones sin impacto financiero

​¿Cómo funciona?

​Ejemplo

​Endpoint relacionado

​Publicación de eventos en tiempo real

​Entradas, salidas y cuentas externas

​¿Por qué importa esto?

​Entradas: agregar valor al ledger

​Salidas: mover valor fuera del ledger

​Comportamiento y reglas de saldo

​Establecer una fecha de transacción personalizada

​Casos de uso

​Transaction Routes

​¿Por qué importa esto?

​Iniciar una transacción

​Forma de la solicitud JSON en v2

​Uso del endpoint JSON

​Revertir una transacción

​¿Cómo funciona?

​Ejemplo

​Restricciones de la reversión

​1. La transacción ya tiene una reversión

​2. La transacción ya es una reversión

​3. El estado de la transacción no es APPROVED

​4. La transacción no se puede revertir

​5. Una ruta de operación de la transacción no es bidireccional

​Casos de uso

​1. Reversión de un pago incorrecto

​2. Cancelación de una compra

​3. Corrección de un error operativo

​4. Devolución de un producto

​5. Compensación por fallo de integración

​Bloqueo y desbloqueo de fondos

​Gestión de transacciones

​Mediante la API

​Mediante Lerian Console

Contabilidad de partida doble

Ejemplo

Transacciones N:N (muchos a muchos)

Ejemplos

Atomicidad e integridad

Origen de la transacción

Fuente única

Ejemplo

Múltiples fuentes

Ejemplo

Destino de la transacción

Destino único

Ejemplo

Múltiples destinos

Ejemplo

Múltiples fuentes y múltiples destinos

Ejemplo

Estados de la transacción

Transiciones de estado

Flujo de la transacción

Transacción de dos fases

Flujo de la transacción de dos fases

1. Crea una transacción de dos fases

2. Confirma o cancela la transacción pendiente

Transacciones pasadas

Ejemplo

Transacciones sin impacto financiero

¿Cómo funciona?

Ejemplo

Endpoint relacionado

Publicación de eventos en tiempo real

Entradas, salidas y cuentas externas

¿Por qué importa esto?

Entradas: agregar valor al ledger

Salidas: mover valor fuera del ledger

Comportamiento y reglas de saldo

Establecer una fecha de transacción personalizada

Casos de uso

Transaction Routes

¿Por qué importa esto?

Iniciar una transacción

Forma de la solicitud JSON en v2

Uso del endpoint JSON

Revertir una transacción

¿Cómo funciona?

Ejemplo

Restricciones de la reversión

1. La transacción ya tiene una reversión

2. La transacción ya es una reversión

3. El estado de la transacción no es APPROVED

4. La transacción no se puede revertir

5. Una ruta de operación de la transacción no es bidireccional

Casos de uso

1. Reversión de un pago incorrecto

2. Cancelación de una compra

3. Corrección de un error operativo

4. Devolución de un producto

5. Compensación por fallo de integración

Bloqueo y desbloqueo de fondos

Gestión de transacciones

Mediante la API

Mediante Lerian Console