Si no se proporciona ninguna
balanceKey, la transacción utiliza automáticamente el saldo predeterminado.Contabilidad de doble entrada
El sistema de doble entrada opera sobre un principio simple pero transformador: para cada transacción, hay dos entradas correspondientes, un débito y un crédito. Este marco asegura que todas las actividades financieras se registren holísticamente, proporcionando una vista completa y equilibrada de sus cuentas. Cada transacción impacta dos cuentas, manteniendo el equilibrio en el ecosistema financiero:
- Los Débitos reflejan el valor recibido o los recursos consumidos.
- Los Créditos indican el valor dado o los recursos proporcionados.
Ejemplo
Considere este ejemplo: realice una transacción para transferir R$ 1000 de una cuenta a otra. Este proceso tendrá 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 a la cuenta de destino.
Transacciones N:N (Muchos a Muchos)
A diferencia de los sistemas financieros tradicionales que limitan las transacciones a relaciones uno a uno o uno a muchos, Midaz habilita transacciones N:N, permitiendo múltiples cuentas de origen y destino dentro de una sola transacción.
Ejemplos
- Pago de marketplace: múltiples vendedores (varias fuentes) reciben pago de una única cuenta de depósito en garantía, y cada vendedor paga una comisión a la plataforma.
- Peer-to-peer con comisiones: una transacción debita al pagador y acredita tanto al beneficiario como a una cuenta de comisiones.
Atomicidad e integridad
Las transacciones son operaciones atómicas; o todas las operaciones constituyentes tienen éxito, o ninguna lo hace. Esto asegura que no ocurran eventos financieros parciales. Si alguna parte de una transacción falla la validación (por ejemplo, fondos insuficientes en una cuenta), la transacción completa no se aplicará, preservando la integridad del libro contable.
Origen de la transacción
Las transacciones en Midaz pueden iniciarse desde una o múltiples fuentes.
La suma de los valores en
source siempre debe ser igual al valor especificado justo después de send e igual a la suma de los valores en distribute.Origen único
En una transacción de origen único, la cantidad especificada se toma directamente de una cuenta de origen y, opcionalmente, de un saldo específico.Ejemplo
En este ejemplo (Figura 1):- BRL 30,00 se toma de
@account1(saldocredit). - 100% se envía a
@destinationAccount1(saldooperational)

Figura 1. Ejemplo de una transacción de origen único.
Múltiples orígenes
En una transacción de múltiples orígenes, los fondos se extraen de múltiples cuentas y/o saldos.Ejemplo
En este ejemplo (Figura 2):- BRL 30,00 se enviarán a la cuenta de destino (
@destinationAccount1).- BRL 15,00 de
@account1(saldodefault). - BRL 15,00 de
@account2(saldoinvestment).
- BRL 15,00 de
- La cuenta de destino recibirá el 100% de la cantidad enviada.

Figura 2. Ejemplo de una transacción de múltiples orígenes.
Destino de la transacción
Similar a los orígenes, los destinos pueden ser únicos o múltiples.
Destino único
En una transacción de destino único, la cantidad se envía a solo una cuenta de destino.Ejemplo
En este ejemplo (Figura 3):- BRL 30,00 se toma de una cuenta externa (
@external|BRL). - 100% se envía a la cuenta de destino (
@destinationAccount1).

Figura 3. Ejemplo de una transacción de destino único.
Múltiples destinos
En transacciones de múltiples destinos, la cantidad de la transacción se divide entre múltiples cuentas de destino. Los valores pueden distribuirse por acciones, cantidades fijas o saldo restante.Ejemplo
En este ejemplo (Figura 4):- BRL 100 se toma de la cuenta de origen (
@account1). - 38% de la cantidad va a la cuenta 2 (
@account2). - 50% va a la cuenta 3 (
@account3). - Un BRL 2,00 fijo va a la cuenta 4 (
@account4). - La cantidad restante va a la cuenta 5 (
@account5).

Figura 4. Ejemplo de una transacción de múltiples destinos.
Múltiples orígenes y múltiples destinos
Estas transacciones complejas involucran múltiples orígenes y múltiples destinos. Esto es útil para escenarios como una campaña de crowdfunding, donde las contribuciones se agrupan y distribuyen entre múltiples destinatarios.
Ejemplo
En este ejemplo (Figura 5):- BRL 4.000,00 se donarán, y la cantidad se tomará de cuatro cuentas diferentes.
- 25% se tomará de la cuenta 1 (
@account1). - 25% se tomará de la cuenta 2 (
@account2). - 40% se tomará de la cuenta 3 (
@account3) - 10% se tomará de la cuenta 4 (
@account4).
- 25% se tomará de la cuenta 1 (
- Las donaciones se distribuirán a cuatro cuentas de donación separadas, y cada una recibirá una participación del 25% del total.

Figura 5. Ejemplo de una transacción de múltiples orígenes y múltiples destinos.
Flujo de transacciones
Cuando una transacción comienza, Midaz valida:
- Las cuentas involucradas.
- Los saldos especificados (
balanceKey, odefaultsi no se proporciona). - Permisos (
allowSending,allowReceiving). - Fondos disponibles suficientes en el saldo seleccionado.
APPROVED.
Los usuarios solo deben iniciar este tipo de transacción si tienen la intención de confirmarla en el libro contable inmediatamente.
pending para crear una Transacción de dos fases.
Transacción de dos fases
En este escenario, la transacción se crea con estado
PENDING. En lugar de mover fondos de inmediato, Midaz reserva la cantidad especificada en el saldo correcto (balanceKey, o default si no se proporciona).
- Los fondos reservados se mueven de
availableaon_hold. - Todavía no se registran operaciones (débitos o créditos) en el libro contable.
- Debe ejecutar explícitamente
commitpara ejecutar la transferencia, ocancelpara liberar los fondos.

Figura 6. Ejemplo de flujo de trabajo antifraude
Flujo de transacción de dos fases
1. Crear una transacción de dos fases
- Use el endpoint Crear una Transacción usando JSON con
"pending": true.
balanceKey), permisos (allowSending, allowReceiving) y fondos disponibles. Si es válido:
- Los fondos se reservan en el saldo correcto.
- El estado de la transacción se establece en
PENDING. - Se almacenan metadatos, pero aún no se registra ningún débito/crédito.
2. Confirmar o cancelar la transacción pendiente
- Confirmar: Finaliza la transacción. Los fondos se mueven de on_hold al saldo de destino, y se registran las operaciones de débito/crédito.
- Use el endpoint Confirmar una Transacción Pendiente.
- Estado:
APPROVED.
- Cancelar: Libera los fondos reservados de vuelta a disponible en el mismo saldo.
- Use el endpoint Cancelar una Transacción Pendiente.
- Estado:
CANCELED.
Transacciones pasadas
Midaz también admite transacciones pasadas, permitiendo a las instituciones importar eventos financieros heredados mientras preservan la precisión histórica.
- Use el campo opcional
createdAtpara establecer la fecha original de la transacción. - Las transacciones con impacto financiero recalculan el estado histórico de los saldos como si se hubieran procesado en esa fecha.
- Las transacciones creadas a través de Crear una Anotación de Transacción validan la estructura pero no impactan los saldos. Son útiles para auditorías, cumplimiento e importaciones donde los saldos deben permanecer sin cambios.
Ejemplo
Al importar datos heredados, envíe todas las transacciones pasadas antes de comenzar las operaciones en vivo. Esto asegura que los saldos se recalculen de manera consistente en todo el libro contable.
Transacciones sin impacto financiero
Midaz admite la creación de transacciones que se registran en el libro contable, pero no afectan los saldos de las cuentas. Estas transacciones aseguran la integridad estructural mientras mantienen los saldos sin cambios. Esta función es útil cuando necesita:
- Importar transacciones heredadas sin alterar los saldos.
- Registrar eventos de auditoría o cumplimiento.
- Agregar operaciones comerciales que deben rastrearse en el Ledger pero no requieren movimiento de fondos.
¿Cómo funciona?
Cuando se crea una transacción sin impacto financiero:- Los campos
balanceybalanceAfterse almacenan como 0 para preservar la validación de doble entrada. - El campo
balanceAffected(booleano) se ha introducido en cada operación:- true → la operación afecta el saldo de la cuenta.
- false → la operación se registra en el libro contable sin impactar los saldos.
Incluso cuando no se actualizan saldos, Midaz aplica reglas de doble entrada. Esto garantiza la consistencia en todas las transacciones del libro contable.
Ejemplo
Endpoint relacionado
- Crear una Anotación de Transacción — Registrar una transacción sin impacto financiero en el libro contable.
Publicación de eventos en tiempo real
¿Quiere rastrear el estado de sus transacciones a medida que suceden? Midaz admite la publicación de eventos en tiempo real a través de RabbitMQ. Una vez habilitado, cada transacción genera un evento, como
APPROVED, PENDING o CANCELED, al que los sistemas externos pueden suscribirse utilizando enrutamiento basado en temas.
Para obtener más información sobre cómo publicar y consumir eventos de transacciones, consulte la página Publicador de eventos.
Entradas, salidas y cuentas externas
Midaz usa un sistema de libro contable de doble entrada en el que todo el valor que entra o sale del sistema debe pasar por una cuenta especial: la Cuenta Externa. Esta cuenta—representada 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 el libro contable se inicializa por primera vez, todas las cuentas—incluida@external—comienzan con un saldo cero. Para reflejar los saldos del mundo real (por ejemplo, fondos institucionales mantenidos externamente), debe iniciar una transacción que inyecte fondos en las cuentas de Midaz debitando la cuenta externa.
Esta es la única forma de traer fondos a Midaz.
Entradas – Agregar valor al Ledger
Para acreditar una cuenta interna desde fuera del libro contable:- Origen:
@external/{{assetCode}}(por ejemplo,@external/BRL). - Destino: Una o más cuentas internas (por ejemplo,
@organization.main).
| Origen | Destino | Cantidad |
|---|---|---|
| @external/BRL | @accountA | BRL 10.000 |
Salidas – Mover valor fuera del Ledger
Para simular que el valor sale del libro contable a un destino externo:- Origen: Una o más cuentas de Midaz.
- Destino:
@external/{{assetCode}}.
| Origen | Destino | Cantidad |
|---|---|---|
| @accountA | @external/BRL | BRL 1.000 |
@accountA y acredita la cuenta externa. En la vida real, su sistema (a través de SPI u otras integraciones) transferirá los fondos al destinatario previsto.
Comportamiento y reglas de saldo
@external/{{assetCode}}puede tener un saldo cero o negativo, pero nunca positivo.- Su saldo es siempre el inverso del saldo combinado de todas las cuentas de Midaz que mantienen 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.
Todos los movimientos de valor entre el mundo exterior y el libro contable de Midaz deben pasar por la cuenta externa.Nada entra o sale del sistema sin una transacción formal, asegurando trazabilidad completa, integridad del saldo y cumplimiento con los principios de doble entrada.
Rutas de transacción
La API de Rutas de transacción habilita el procesamiento estructurado y validado de transacciones en Midaz. Mientras que la API de Transacciones maneja la ejecución de eventos financieros (débitos y créditos entre cuentas), las Rutas de Transacción definen plantillas para cómo estos eventos deben estructurarse y validarse, asegurando consistencia e integridad. Piense en ello como la capa de validación que asegura que las transacciones comerciales sigan patrones predefinidos y mantengan la estructura financiera adecuada. Por ejemplo, una transacción para una comisión, un depósito o un pago puede requerir diferentes tipos de cuenta, reglas de validación y estructuras. En lugar de manejar la validación por separado para cada transacción, configura reglas predefinidas que le dicen a Midaz: “Cuando el usuario envíe este tipo de transacción, valídela contra estos requisitos de cuenta y patrones de estructura.” Cada Ruta de Transacción combina múltiples Rutas de operación, que definen los componentes individuales de una transacción, especificando requisitos de cuenta, direcciones (origen/destino) y reglas de validación para cada “tramo” del evento financiero.
¿Por qué importa?
Al usar Rutas de transacción, usted:- Asegura una estructura de transacción consistente en toda su aplicación.
- Hace que su libro contable sea más mantenible, predecible y confiable.
- Valida eventos financieros contra patrones predefinidos.
- Habilita la configuración de plantillas de transacción sin cambios de código.
- Mantiene la integridad de datos a través de la validación estructurada.
Iniciar una transacción
Hay dos formas principales de iniciar una transacción:
Usando DSL
Un Lenguaje Específico de Dominio (DSL) simplifica la interacción del usuario al enfocarse en conceptos de dominio específicos, permitiendo a los no desarrolladores realizar tareas complejas sin habilidades técnicas. Los DSL reducen el código repetitivo e incorporan restricciones en su sintaxis, haciendo cumplir las reglas comerciales y minimizando errores. Sin embargo, sus patrones predefinidos pueden limitar la flexibilidad, dificultando la creación de analizadores personalizados o la adaptación a nuevos requisitos. El DSL de Transacciones en Midaz, llamado Gold, simplifica el procesamiento de transacciones con una sintaxis contable intuitiva. Almacena información de transacciones en archivos.gold, permitiendo a los equipos de negocio definir transacciones fácilmente y fomentando la colaboración entre flujos de trabajo técnicos y comerciales.
Para usar el DSL, siga estos pasos:
1
Cree el archivo
.gold según la estructura del DSL de Transacciones.2
Envíe el archivo usando el endpoint Crear una Transacción usando DSL.
Usando endpoint JSON
Los endpoints JSON proporcionan un estándar flexible y amigable para desarrolladores para el intercambio de datos, permitiendo un control preciso sobre las estructuras de solicitud adaptadas para flujos de trabajo personalizados y casos de uso específicos. Su amplia compatibilidad con varios lenguajes de programación facilita la integración y la depuración. Sin embargo, esta flexibilidad puede resultar en verbosidad y errores del usuario, ya que se requiere que los desarrolladores manejen la validación manualmente. Para los no desarrolladores, la complejidad de JSON puede presentar desafíos, haciéndolo menos intuitivo que un Lenguaje Específico de Dominio (DSL) para tareas cotidianas.- Para crear una transacción usando JSON, use el endpoint Crear una Transacción usando JSON.
Si necesita reservar fondos antes de completar la transferencia, establezca el campo
pending en true (flujo de Transacción de Dos Fases).Reversión de una transacción
Midaz admite la reversión de transacciones, permitiéndole deshacer transacciones aprobadas mediante la creación de una transacción espejo que invierte los débitos y créditos originales. Este mecanismo mantiene pistas de auditoría completas mientras cancela efectivamente el impacto financiero en los saldos de las cuentas.
La reversión crea una nueva transacción que compensa la original. La transacción original permanece en el historial del libro contable para completa trazabilidad.
¿Cómo funciona?
Cuando revierte 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).
- Las operaciones CREDIT se convierten en operaciones de origen (
-
Crea una nueva transacción con:
- Mismo monto y código de activo.
- Misma descripción y metadatos.
- Operaciones invertidas (los receptores se convierten en emisores, los emisores en receptores).
- Estado inicial:
CREATED(noPENDING) → luego progresa aAPPROVED. parentTransactionIDreferenciando la transacción original.
- Procesa la reversión a través del flujo estándar de transacciones, incluyendo validación, actualización de saldos y registro de historial.
Ejemplo
Considere este escenario: Transacción original:- Cuenta A (débito -100) → Cuenta B (crédito +100)
- Cuenta B (débito -100) → Cuenta A (crédito +100)
- La Cuenta A regresa a su saldo anterior (recibe de vuelta los -100).
- La Cuenta B regresa a su saldo anterior (pierde los +100).
- Ambas transacciones permanecen en el historial del libro contable para propósitos de auditoría.
- La transacción de reversión incluye
parentTransactionIDapuntando a la original.
Restricciones de reversión
Midaz aplica reglas estrictas para mantener la integridad del libro contable. Las reversiones fallarán en los siguientes casos:1. La transacción ya tiene una reversión
- Solo se permite una reversión por transacción.
- Previene múltiples reversiones de la misma transacción.
2. La transacción ya es una reversión
- No se puede revertir una transacción que ya es una reversión.
- Previene crear “reversiones de reversiones.”
3. El estado de la transacción no es APPROVED
- Solo las transacciones aprobadas pueden ser revertidas.
- Las transacciones con estado
PENDING,CREATEDoCANCELEDno pueden ser revertidas.
4. La transacción no puede ser revertida
- Ocurre cuando la transacción no tiene operaciones válidas para invertir.
- Por ejemplo, transacciones sin operaciones estándar CREDIT/DEBIT.
Solo las operaciones CREDIT y DEBIT son consideradas para reversión. Las operaciones como ON_HOLD y RELEASE no están incluidas en el proceso de reversión.
Casos de uso
La reversión de transacciones es esencial para varios escenarios operacionales:1. Reversión de pago incorrecto
Un cliente pagó BRL 500 al proveedor equivocado.- Revertir 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 compra
Una tienda procesó una venta de BRL 1,000, pero el cliente cancela la compra.- Revertir la transacción de venta.
- Los fondos regresan a la cuenta del cliente.
3. Corrección de error operacional
Un operador creó una transacción con el monto incorrecto.- Revertir la transacción incorrecta.
- Crear una nueva transacción con el monto correcto.
4. Devolución de producto
Un cliente compró y pagó BRL 200, pero devolvió el producto.- Revertir la transacción de pago.
- El cliente recibe un reembolso.
5. Compensación por falla en integración
Una transacción fue aprobada pero falló en un sistema externo.- Revertir para deshacer la operación contable.
- Los saldos regresan a su estado anterior.
Gestión de transacciones
Puede gestionar sus transacciones a través de API o mediante Midaz Console.
Vía API
- Crear una Transacción usando DSL (obsoleto) — Enviar un archivo de transacción usando el DSL de Midaz.
- Crear una Transacción usando JSON — Enviar una transacción directamente usando un payload JSON.
- Confirmar una transacción pendiente — Finalizar una transacción reservada.
- Cancelar una transacción pendiente — Liberar fondos reservados sin ejecutar.
- Revert a Transaction — Crea una transacción de reversión para deshacer una transacción aprobada.
- Crear una Transacción de Entrada — Registrar fondos entrantes de fuentes externas al Libro Contable.
- Crear una Transacción de Salida — Mover fondos de cuentas internas al mundo externo.
- Listar Transacciones — Ver todas las Transacciones en su espacio de trabajo.
- Recuperar una Transacción — Obtener detalles de una Transacción específica.
- Actualizar una Transacción — Editar los metadatos de una Transacción existente.
- Crear una Anotación de Transacción — Registrar una transacción sin impacto financiero en el libro contable.

