> ## 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 de transferencia Pix reutilizables en Midaz con rutas de transacción y rutas de operación, y aplica las reglas de cuenta y de comisión directamente en el ledger.
Cada transacción Pix sigue un patrón: debitar al remitente, acreditar al receptor y a veces cobrar una comisión. 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 rutas de transacción 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 de Pix por tu sistema.
Esta página recorre dos escenarios: una transferencia simple entre pares y una transferencia con comisión. Cada escenario muestra cómo configurar las rutas y qué gana tu equipo con ellas.
## Por qué importa
***
Para los **equipos de producto y de operaciones**, las rutas de transacción dan flujos Pix auditables sin aplicación de reglas en el nivel de la aplicación. Cada transacción lleva una referencia a la ruta que siguió, así que las revisiones de cumplimiento y las investigaciones de incidentes se mantienen simples.
Para los **equipos de ingeniería**, las rutas eliminan el código de validación repetitivo. Configuras las reglas de cuenta y de comisión una vez. Midaz entonces las aplica en el nivel del 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, reúsalas en todas las transacciones Pix |
| Sin validación automática — las restricciones viven en el código de la aplicación | Midaz rechaza las transacciones que no coinciden con las reglas de la ruta |
| Agregar comisiones requiere cambios en cada integración Pix | Agrega una ruta de operación nueva, crea una variante nueva de ruta de transacción |
| Difícil de rastrear qué patrón debía seguir una transacción | Cada transacción almacena su ID de ruta — sencillo de auditar |
Para una mirada más profunda a cómo funcionan las rutas de transacción y las rutas de operación, ve [Rutas contables](/es/products/midaz/transaction-routing-entities).
## Requisitos previos
***
Ambos escenarios suponen un entorno Midaz con la siguiente estructura ya establecida:
| Entidad | Alias | Tipo | Propósito |
| --------------- | ----------------- | ---------- | --------------------------------------------------- |
| Cuenta de Alice | `@alice_checking` | `checking` | Remitente — la cuenta corriente principal de Alice |
| Cuenta de Bob | `@bob_checking` | `checking` | Receptor — la 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 por Pix. El dinero se mueve de una cuenta corriente a otra, sin comisiones y sin divisiones.
### El objetivo
* Debitar R\$ 150.00 de la cuenta corriente de Alice
* Acreditar R\$ 150.00 en la cuenta corriente de Bob
* Validar que ambas cuentas son de 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 de tipo `checking` como origen. La ruta no fija un remitente específico en el código.
```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 cuando construyes la ruta de transacción.
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 rutas de operación en una sola ruta de transacción. Esta ruta representa "Pix Transfer" 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 marcador de posición con los IDs reales de las rutas de operación de los pasos anteriores.
### Ejecutar una transferencia Pix
Con la ruta establecida, cada transferencia Pix referencia el ID de la ruta de transacción en el campo `routeId`. Midaz valida que las cuentas coinciden 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é pasa por debajo
La solicitud lleva el ID de la ruta de transacción en el campo `routeId`. Midaz carga la configuración de la ruta.
Para cada entrada `from`, Midaz revisa la cuenta contra las reglas de la ruta de operación de origen. La cuenta de Alice es de tipo `checking`, así que coincide con la regla `account_type`. La validación pasa.
Para cada entrada `to`, Midaz revisa la cuenta contra las reglas de la ruta de operación de destino. La cuenta de Bob es de tipo `checking`, así que la validación pasa.
Ambas validaciones pasan, así que Midaz crea la transacción de forma atómica. Debita R\$ 150.00 de `@alice_checking` y acredita R\$ 150.00 en `@bob_checking`.
Si Alice envía desde una cuenta `savings` en cambio, Midaz rechaza la transacción. La ruta acepta solo cuentas `checking` como origen, y no escribes ninguna validación del lado de la aplicación.
## Escenario 2: Transferencia Pix con cobro de comisión
***
Este flujo coincide con el escenario 1, pero ahora el banco cobra una comisión de R\$ 1.50 en cada transferencia Pix. El flujo agrega una tercera ruta de operación para el destino de la comisión, y el débito total de Alice sube a R\$ 151.50.
### Qué cambia
Ya tienes las rutas de operación de origen y de destino del escenario 1. Agregas una ruta de operación para la comisión y una ruta de transacción nueva que agrupa las tres.
| Entidad | Alias | Tipo | Propósito |
| --------------------------------- | ------------------- | --------- | ------------------------------------------------------------ |
| Cuenta de ingresos por comisiones | `@revenue_pix_fees` | `revenue` | Cuenta interna que cobra las comisiones de transferencia Pix |
### Configurar la ruta de comisión
Las rutas anteriores usan `account_type`. Esta usa el tipo de regla `alias` en cambio. 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 originales de origen y de destino con la ruta de comisión nueva. Es una ruta de transacción 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 comisión
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 R\$ 151.50 a Alice. Bob recibe R\$ 150.00. El banco cobra R\$ 1.50. Todo esto ocurre en una transacción atómica, balanceada y auditable.
### Qué desbloquea esto
* **Cobro de comisión transparente**: la comisión es un asiento de primera clase en el ledger, no un metadato oculto. Los equipos de finanzas y de cumplimiento ven exactamente adónde fue el R\$ 1.50.
* **Bloques de construcción reutilizables**: las variantes simple y con comisión comparten las rutas de operación de origen y de destino. Agregas solo lo que cambia.
* **Control en el nivel de la ruta**: tu sistema puede ofrecer tanto "Pix Transfer" como "Pix Transfer with Fee" como productos distintos, cada uno respaldado por su propia ruta de transacción.
* **Evolución fácil**: para agregar una comisión porcentual o una división entre cuentas de ingresos, crea rutas de operación nuevas y compón una ruta de transacción nueva. Los flujos existentes quedan intactos.
## Entender los tipos de regla
***
Los dos tipos de regla sirven para propósitos distintos. La elección correcta depende de si la cuenta en una ruta es dinámica o fija.
| Tipo de regla | Formato de `validIf` | Comportamiento | Cuándo usarlo |
| -------------- | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `account_type` | **Arreglo de cadenas** — por ejemplo, `["checking"]` o `["checking", "savings"]` | Acepta cualquier cuenta que coincida con uno de los tipos especificados | Participantes dinámicos — el remitente o el receptor puede ser cualquier cuenta de ese tipo |
| `alias` | **Cadena** — por ejemplo, `"@revenue_pix_fees"` | Debe apuntar a una cuenta específica por su alias | Participantes fijos — la ruta siempre llega a la misma cuenta, como una cuenta de comisión o de liquidación |
Puedes combinar ambos tipos de regla dentro de una sola ruta de transacción. El escenario 2 hace exactamente eso: `account_type` para el remitente y el receptor dinámicos, `alias` para la cuenta fija de comisión.
## Qué necesitas para empezar
***
| Requisito | Detalles |
| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Midaz** (v3.x.x+) | Ledger central con la validación de rutas de transacción habilitada |
| **Configuración de validación de rutas** | Habilita la validación de rutas mediante la API de Ledger Settings: `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 |
| **Rutas de operación** | Una por cada tramo de operación (origen, destino, comisión) |
| **Ruta de transacción** | Agrupa las rutas de operación en un patrón reutilizable |
Debes habilitar la validación de rutas de transacción para cada ledger. Ve [Trabajar con rutas contables](/es/products/midaz/transaction-routing-entities#working-with-accounting-routes) para los pasos de configuración.
## Próximos pasos
***
Entiende cómo funcionan las rutas de operación y las rutas de transacción en un nivel más profundo.
Conoce el modelo de transacciones de partida doble de Midaz y sus capacidades N:N.
Combina el Pix Plugin con el Fees Engine para la gestión automatizada de comisiones.
Explora la interfaz unificada para pagos, claves, cobranzas y devoluciones.