> ## 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 y, a veces, cobrar una tarifa. Cuando ese patrón vive solo en el código de la aplicación, cada equipo que toca Pix reimplementa la misma lógica de validación. Cada implementación es otra oportunidad de inconsistencia.
Las Transaction Routes mueven ese patrón al ledger. Defines las reglas una vez, y Midaz las aplica en cada transacción. El resultado es una única fuente de verdad sobre cómo fluye el dinero Pix por tu sistema.
Esta página recorre dos escenarios — una transferencia simple entre pares y una transferencia con tarifa. Cada escenario muestra cómo configurar las rutas y qué gana tu equipo con ellas.
## Por qué esto importa
***
Para **equipos de producto y operaciones**, las Transaction Routes te dan flujos Pix auditables sin cumplimiento a nivel de aplicación. Cada transacción lleva una referencia a la ruta que siguió, así las revisiones de cumplimiento y las investigaciones de incidentes se mantienen simples.
Para **equipos de ingeniería**, las rutas eliminan código de validación repetitivo. Configuras las reglas de cuenta y de tarifa una vez. Luego Midaz las aplica a nivel de ledger en cada integración Pix.
| 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 son montos decimales. Para BRL, `150.00` significa R\$ 150,00.
## 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
### Configurar las rutas
Esta ruta define el lado de débito de la transferencia. La regla `account_type` acepta cualquier cuenta del tipo `checking` 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 necesitas al construir la Transaction Route.
Esta ruta define el lado de crédito. Usa el 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. Esta ruta 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 de los pasos anteriores.
### Ejecutar una transferencia Pix
Con la ruta establecida, cada transferencia Pix hace referencia al ID de la Transaction Route en el campo `routeId`. Midaz valida que las cuentas coincidan con las reglas de la ruta antes de procesar la transacción.
```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",
"routeId": "",
"send": {
"asset": "BRL",
"value": "150.00",
"source": {
"from": [
{
"accountAlias": "@alice_checking",
"amount": { "asset": "BRL", "value": "150.00" },
"description": "Pix sent to Bob",
"routeId": ""
}
]
},
"distribute": {
"to": [
{
"accountAlias": "@bob_checking",
"amount": { "asset": "BRL", "value": "150.00" },
"description": "Pix received from Alice",
"routeId": ""
}
]
}
},
"metadata": {
"pix_end_to_end_id": "E123456782026030614300000000001",
"pix_key_type": "cpf",
"pix_key": "123.456.789-00"
}
}
```
### Qué sucede internamente
La solicitud lleva el ID de la Transaction Route en el campo `routeId`. 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`, así que 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`, así que 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 envía desde una cuenta `savings`, Midaz rechaza la transacción. La ruta acepta solo cuentas `checking` como origen, y no escribes validación del lado de la aplicación.
## Escenario 2: Transferencia Pix con cobro de tarifa
***
Este flujo coincide con el Escenario 1, pero ahora el banco cobra una tarifa de R\$ 1,50 en cada transferencia Pix. El flujo 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. Agregas una Operation Route para la tarifa y una nueva Transaction Route que agrupa las tres.
| Entidad | Alias | Tipo | Propósito |
| ------------------------------ | ------------------- | --------- | ------------------------------------------------------- |
| Cuenta de ingresos por tarifas | `@revenue_pix_fees` | `revenue` | Cuenta interna que recauda tarifas de transferencia Pix |
### Configurar la ruta de tarifa
Las rutas anteriores usan `account_type`. Esta usa el tipo de regla `alias` en su lugar. Apunta a una cuenta específica — `@revenue_pix_fees` — y ninguna otra cuenta califica.
```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, así que 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
}
}
```
### Ejecutar 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",
"routeId": "",
"send": {
"asset": "BRL",
"value": "151.50",
"source": {
"from": [
{
"accountAlias": "@alice_checking",
"amount": { "asset": "BRL", "value": "151.50" },
"description": "Pix sent to Bob + transfer fee",
"routeId": ""
}
]
},
"distribute": {
"to": [
{
"accountAlias": "@bob_checking",
"amount": { "asset": "BRL", "value": "150.00" },
"description": "Pix received from Alice",
"routeId": ""
},
{
"accountAlias": "@revenue_pix_fees",
"amount": { "asset": "BRL", "value": "1.50" },
"description": "Pix transfer fee",
"routeId": ""
}
]
}
},
"metadata": {
"pix_end_to_end_id": "E123456782026030614300000000002",
"fee_amount": "1.50"
}
}
```
**Resultado:** Midaz debita a Alice R\$ 151,50. Bob recibe R\$ 150,00. El banco cobra R\$ 1,50. 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 variantes simple y con tarifa comparten las Operation Routes de origen y destino. 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** — para agregar una tarifa basada en porcentaje o una división entre cuentas de ingresos, crea nuevas Operation Routes y compón una nueva Transaction Route. Los flujos existentes permanecen intactos.
## Entender los tipos de regla
***
Los dos tipos de regla sirven propósitos diferentes. La elección correcta depende de si la cuenta en una ruta es 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 `{"accounting": {"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 |
Debes habilitar la validación de Transaction Route para cada 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.