Por qué esto importa
Para equipos de producto y operaciones, las Transaction Routes significan flujos Pix predecibles y auditables sin depender de la aplicación para su cumplimiento. Cada transacción lleva una referencia a la ruta que siguió, lo que hace que las revisiones de cumplimiento y las investigaciones de incidentes sean directas. Para equipos de ingeniería, las rutas eliminan código de validación repetitivo. En lugar de verificar tipos de cuenta y destinos de tarifas en cada integración Pix, configuras las reglas una vez y dejas que Midaz se encargue de la aplicación a nivel de ledger.
| Sin Rutas | Con Rutas |
|---|---|
| Cada integración debe aplicar sus propias reglas de cuenta | Define las reglas una vez, reutiliza en todas las transacciones Pix |
| Sin validación automática — las restricciones viven en el código de la aplicación | Midaz rechaza transacciones que no coinciden con las reglas de la ruta |
| Agregar tarifas requiere cambios en cada integración Pix | Agrega una nueva Operation Route, crea una nueva variante de Transaction Route |
| Difícil rastrear qué patrón debía seguir una transacción | Cada transacción almacena su ID de ruta — fácil de auditar |
Requisitos previos
Ambos escenarios asumen un entorno Midaz con la siguiente estructura ya establecida:
| Entidad | Alias | Tipo | Propósito |
|---|---|---|---|
| Cuenta de Alice | @alice_checking | checking | Emisor — cuenta corriente principal de Alice |
| Cuenta de Bob | @bob_checking | checking | Receptor — cuenta corriente principal de Bob |
| Activo BRL | — | — | Real brasileño, registrado como el activo operativo |
Los valores en Midaz se representan en la unidad más pequeña de la moneda. Para BRL,
15000 significa R$ 150,00 (centavos).Escenario 1: Transferencia Pix simple
Alice envía R$ 150,00 a Bob vía Pix. El dinero se mueve de una cuenta corriente a otra — sin tarifas, sin divisiones, solo una transferencia limpia entre pares.
El objetivo
- Debitar la cuenta corriente de Alice en R$ 150,00
- Acreditar la cuenta corriente de Bob en R$ 150,00
- Validar que ambas cuentas sean del tipo
checkingantes de procesar - Hacer este patrón reutilizable para cada transferencia Pix entre cuentas corrientes
Configurando las rutas
Crear la Operation Route de origen
Esta ruta define el lado de débito de la transferencia. La regla Guarda el
account_type significa que cualquier cuenta del tipo checking es válida como origen — la ruta no codifica un emisor específico.id devuelto — lo necesitarás al construir la Transaction Route.Crear la Operation Route de destino
Esta ruta define el lado de crédito. Mismo tipo de regla: cualquier cuenta
checking califica como receptor válido.Ejecutando una transferencia Pix
Con la ruta establecida, cada transferencia Pix hace referencia al ID de la Transaction Route. Midaz valida que las cuentas coincidan con las reglas de la ruta antes de procesar.Qué sucede internamente
Midaz recibe la transacción
La solicitud incluye el ID de la Transaction Route en el campo
route. Midaz carga la configuración de la ruta.Validación del origen
Para cada entrada
from, Midaz verifica la cuenta contra las reglas de la Operation Route de origen. La cuenta de Alice es del tipo checking — coincide con la regla account_type. La validación pasa.Validación del destino
Para cada entrada
to, Midaz verifica la cuenta contra las reglas de la Operation Route de destino. La cuenta de Bob es del tipo checking — la validación pasa.Escenario 2: Transferencia Pix con cobro de tarifa
El mismo flujo que el Escenario 1, pero ahora el banco cobra una tarifa de R$ 1,50 en cada transferencia Pix. Esto agrega una tercera Operation Route para el destino de la tarifa, y el débito total de Alice aumenta a R$ 151,50.
Qué cambia
Ya tienes las Operation Routes de origen y destino del Escenario 1. Necesitas una Operation Route adicional para la tarifa y una nueva Transaction Route que agrupe las tres.| Entidad | Alias | Tipo | Propósito |
|---|---|---|---|
| Cuenta de ingresos por tarifas | @revenue_pix_fees | revenue | Cuenta interna que recauda tarifas de transferencia Pix |
Configurando la ruta de tarifa
Crear la Operation Route de tarifa
A diferencia de las rutas anteriores que usan
account_type, esta usa el tipo de regla alias. Eso significa que apunta a una cuenta específica — @revenue_pix_fees — y ninguna otra cuenta puede ser utilizada.Ejecutando una transferencia Pix con tarifa
Alice envía R$ 150,00 a Bob. El banco cobra R$ 1,50. El débito total de Alice es R$ 151,50.Qué habilita esto
- Cobro de tarifas transparente — la tarifa es una entrada de ledger de primera clase, no metadatos ocultos. Los equipos de finanzas y cumplimiento ven exactamente a dónde fueron los R$ 1,50.
- Bloques de construcción reutilizables — las Operation Routes de origen y destino se comparten entre las variantes simple y con tarifa. Solo agregas lo que cambia.
- Control a nivel de ruta — tu sistema puede ofrecer tanto “Transferencia PIX” como “Transferencia PIX con Tarifa” como productos distintos, cada uno respaldado por su propia Transaction Route.
- Evolución fácil — ¿necesitas una tarifa basada en porcentaje? ¿Una división entre múltiples cuentas de ingresos? Agrega nuevas Operation Routes y compón una nueva Transaction Route. Los flujos existentes permanecen intactos.
Entendiendo los tipos de regla
Los dos tipos de regla tienen propósitos diferentes. Elegir el correcto depende de si la cuenta en una ruta debe ser dinámica o fija.
| Tipo de regla | Formato validIf | Comportamiento | Cuándo usar |
|---|---|---|---|
account_type | Array de strings — ej., ["checking"] o ["checking", "savings"] | Acepta cualquier cuenta que coincida con uno de los tipos especificados | Participantes dinámicos — el emisor o receptor puede ser cualquier cuenta de ese tipo |
alias | String — ej., "@revenue_pix_fees" | Debe apuntar a una cuenta específica por su alias | Participantes fijos — la ruta siempre apunta a la misma cuenta, como una cuenta de tarifas o liquidación |
Qué necesitas para comenzar
| Requisito | Detalles |
|---|---|
| Midaz (v3.x.x+) | Ledger core con validación de Transaction Route habilitada |
| Configuración de validación de rutas | Configura TRANSACTION_ROUTE_VALIDATION en el .env del servicio Transaction para incluir tu organization_id:ledger_id |
| Cuentas y activo | Como mínimo: dos cuentas de cliente y un activo BRL registrado en el ledger |
| Operation Routes | Una por tramo de operación (origen, destino, tarifa) |
| Transaction Route | Agrupa las Operation Routes en un patrón reutilizable |
La validación de Transaction Route debe habilitarse explícitamente por ledger. Consulta Trabajando con Transaction Routing para los pasos de configuración.
Próximos pasos
Transaction Routing
Entiende cómo funcionan las Operation Routes y Transaction Routes a un nivel más profundo.
Transacciones
Aprende sobre el modelo de transacciones de doble entrada de Midaz y las capacidades N:N.
Pix con tarifas automatizadas
Combina el Plugin Pix con el Fees Engine para la gestión automatizada de tarifas.
Pix Switch
Explora la arquitectura completa del Plugin Pix y los modelos de conexión.