> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.
# Midaz con Rutas de Transacción Pix
> Modela flujos Pix validados y reutilizables con Transaction y Operation Routes, desde pagos entre personas hasta cobro de tarifas.
Cada transacción Pix sigue un patrón: debitar al emisor, acreditar al receptor, quizás cobrar una tarifa. Cuando ese patrón existe solo en el código de la aplicación, cada equipo que toca Pix debe reimplementar la misma lógica de validación — y cada implementación es una oportunidad para inconsistencias.
Las Transaction Routes mueven ese patrón al ledger mismo. Defines las reglas una vez, y Midaz las aplica en cada transacción automáticamente. El resultado son menos errores de integración, un rastro de auditoría claro y una única fuente de verdad sobre cómo fluye el dinero Pix a través de tu sistema.
Esta página recorre dos escenarios del mundo real — una transferencia simple entre pares y una transferencia con cobro de tarifa — mostrando cómo configurar rutas y qué gana tu equipo al usarlas.
## 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 |
Para una mirada más profunda sobre cómo funcionan las Transaction Routes y las Operation Routes, consulta [Rutas Contables](/es/midaz/transaction-routing-entities).
## 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 `checking` antes de procesar
* Hacer este patrón reutilizable para cada transferencia Pix entre cuentas corrientes
### Configurando las rutas
Esta ruta define el lado de débito de la transferencia. La regla `account_type` significa que cualquier cuenta del tipo `checking` es válida como origen — la ruta no codifica un emisor específico.
```json theme={null}
POST /v1/organizations/{org_id}/ledgers/{ledger_id}/operation-routes
{
"title": "PIX - Debit Sender",
"description": "Debits the sender's checking account in a Pix transfer",
"code": "PIX-SEND-SRC",
"operationType": "source",
"account": {
"ruleType": "account_type",
"validIf": ["checking"]
},
"metadata": {
"payment_method": "pix",
"direction": "outbound"
}
}
```
Guarda el `id` devuelto — lo necesitarás al construir la Transaction Route.
Esta ruta define el lado de crédito. Mismo tipo de regla: cualquier cuenta `checking` califica como receptor válido.
```json theme={null}
POST /v1/organizations/{org_id}/ledgers/{ledger_id}/operation-routes
{
"title": "PIX - Credit Receiver",
"description": "Credits the receiver's checking account in a Pix transfer",
"code": "PIX-SEND-DST",
"operationType": "destination",
"account": {
"ruleType": "account_type",
"validIf": ["checking"]
},
"metadata": {
"payment_method": "pix",
"direction": "inbound"
}
}
```
Agrupa ambas Operation Routes en una sola Transaction Route. Este es el patrón que representa "Transferencia Pix" en tu sistema.
```json theme={null}
POST /v1/organizations/{org_id}/ledgers/{ledger_id}/transaction-routes
{
"title": "PIX Transfer",
"description": "Standard Pix transfer between two checking accounts",
"operationRoutes": [
"",
""
],
"metadata": {
"payment_rail": "pix",
"spi_message_type": "pacs.008",
"regulation": "BCB_PIX"
}
}
```
Reemplaza los IDs de ejemplo con los IDs reales de las Operation Routes devueltos en los pasos anteriores.
### 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.
```json theme={null}
POST /v1/organizations/{org_id}/ledgers/{ledger_id}/transactions/json
{
"chartOfAccountsGroupName": "PIX",
"description": "Pix transfer from Alice to Bob",
"code": "PIX-20260306-001",
"route": "",
"send": {
"asset": "BRL",
"value": 15000,
"source": {
"from": [
{
"accountAlias": "@alice_checking",
"amount": { "asset": "BRL", "value": 15000 },
"description": "Pix sent to Bob",
"route": ""
}
]
},
"distribute": {
"to": [
{
"accountAlias": "@bob_checking",
"amount": { "asset": "BRL", "value": 15000 },
"description": "Pix received from Alice",
"route": ""
}
]
}
},
"metadata": {
"pix_end_to_end_id": "E123456782026030614300000000001",
"pix_key_type": "cpf",
"pix_key": "123.456.789-00"
}
}
```
### Qué sucede internamente
La solicitud incluye el ID de la Transaction Route en el campo `route`. Midaz carga la configuración de la ruta.
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.
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.
Ambas validaciones pasan, así que Midaz crea la transacción atómicamente: debita `@alice_checking` en R\$ 150,00 y acredita `@bob_checking` en R\$ 150,00.
Si Alice intentara enviar desde una cuenta `savings`, Midaz rechazaría la transacción — la ruta solo acepta cuentas `checking` como origen. No se necesita validación del lado de la aplicación.
## 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
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.
```json theme={null}
POST /v1/organizations/{org_id}/ledgers/{ledger_id}/operation-routes
{
"title": "PIX - Fee Collection",
"description": "Credits the bank's revenue account with the Pix transfer fee",
"code": "PIX-FEE-DST",
"operationType": "destination",
"account": {
"ruleType": "alias",
"validIf": "@revenue_pix_fees"
},
"metadata": {
"fee_type": "pix_transfer_fee"
}
}
```
Esta ruta agrupa las rutas de origen y destino originales con la nueva ruta de tarifa. Es una Transaction Route separada de la transferencia simple — tu sistema puede ofrecer ambas variantes.
```json theme={null}
POST /v1/organizations/{org_id}/ledgers/{ledger_id}/transaction-routes
{
"title": "PIX Transfer with Fee",
"description": "Pix transfer between checking accounts with fee collection",
"operationRoutes": [
"",
"",
""
],
"metadata": {
"payment_rail": "pix",
"includes_fee": true
}
}
```
### 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.
```json theme={null}
POST /v1/organizations/{org_id}/ledgers/{ledger_id}/transactions/json
{
"chartOfAccountsGroupName": "PIX",
"description": "Pix transfer from Alice to Bob (with fee)",
"code": "PIX-20260306-002",
"route": "",
"send": {
"asset": "BRL",
"value": 15150,
"source": {
"from": [
{
"accountAlias": "@alice_checking",
"amount": { "asset": "BRL", "value": 15150 },
"description": "Pix sent to Bob + transfer fee",
"route": ""
}
]
},
"distribute": {
"to": [
{
"accountAlias": "@bob_checking",
"amount": { "asset": "BRL", "value": 15000 },
"description": "Pix received from Alice",
"route": ""
},
{
"accountAlias": "@revenue_pix_fees",
"amount": { "asset": "BRL", "value": 150 },
"description": "Pix transfer fee",
"route": ""
}
]
}
},
"metadata": {
"pix_end_to_end_id": "E123456782026030614300000000002",
"fee_amount": 150
}
}
```
**Resultado:** Alice es debitada R\$ 151,50. Bob recibe R\$ 150,00. El banco cobra R\$ 1,50 en tarifas. Todo en una única transacción atómica — completamente balanceada, completamente auditable.
### 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 |
Puedes combinar ambos tipos de regla dentro de una sola Transaction Route. El Escenario 2 hace exactamente eso: `account_type` para el emisor y receptor dinámicos, `alias` para la cuenta de tarifas fija.
## 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** | Habilita la validación de rutas mediante la API de Configuración del Ledger: `PATCH /v1/organizations/{org_id}/ledgers/{ledger_id}/settings` con `{"validateRoutes": true}` |
| **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 las Rutas Contables](/es/midaz/transaction-routing-entities#trabajando-con-las-rutas-contables) para los pasos de configuración.
## Próximos pasos
***
Entiende cómo funcionan las Operation Routes y Transaction Routes a un nivel más profundo.
Aprende sobre el modelo de transacciones de doble entrada de Midaz y las capacidades N:N.
Combina el Plugin Pix con el Fees Engine para la gestión automatizada de tarifas.
Explora la arquitectura completa del Plugin Pix y los modelos de conexión.