Reconciliación Pix

Esta guía describe el proceso de conciliación de transacciones Pix entre Midaz Ledger y los datos de liquidación del BACEN (Banco Central de Brasil) utilizando Matcher. Cubre tanto Pix enviado (cash-out) como Pix recibido (cash-in), desde la configuración hasta la operación diaria y el manejo de excepciones. Al final de esta guía, tendrás un contexto de Matcher completamente configurado que concilia automáticamente tus transacciones Pix contra los extractos de liquidación SPI del BACEN de forma diaria.

Flujos de transacciones Pix

Comprender cómo fluyen las transacciones Pix a través del sistema es esencial para configurar la conciliación correctamente. Los dos flujos a continuación muestran lo que Matcher necesita conciliar en cada lado.

Pix enviado (cash-out)

El cliente inicia el Pix — El usuario final activa un pago Pix a través de la aplicación o API.
El plugin crea la iniciación — El plugin de Pix crea un registro de iniciación y resuelve la cuenta de destino mediante consulta DICT.
El plugin procesa el pago — El plugin debita la cuenta del cliente en Midaz (transacción en estado pending) y envía la instrucción de pago a SPI.
Liquidación confirmada — SPI envía un webhook confirmando la liquidación. La transacción en Midaz se confirma.
Matcher concilia — Matcher compara la transacción confirmada en Midaz contra la entrada correspondiente en el extracto de liquidación SPI del BACEN.

Pix recibido (cash-in)

Pix entrante llega — SPI envía un webhook sincrónico con los datos del Pix entrante.
El plugin valida — El plugin de Pix valida el payload y aprueba la transacción.
Se crea la transacción de crédito — El plugin crea una transacción CREDIT en Midaz para la cuenta del destinatario.
Liquidación confirmada — El webhook de liquidación confirma que la transacción es definitiva.
Matcher concilia — Matcher compara la transacción de crédito en Midaz contra la entrada correspondiente en el extracto de liquidación SPI del BACEN.

En ambos flujos, el endToEndId es el identificador único que vincula la transacción de Midaz con el registro de liquidación del BACEN. Esta es la clave primaria para la conciliación.

Configuración paso a paso

Crear el contexto

Crea un contexto de conciliación para transacciones Pix. Utiliza el tipo 1:1 porque cada transacción Pix tiene exactamente una entrada de liquidación correspondiente en el BACEN.

{
  "name": "Pix Daily Reconciliation",
  "type": "1:1",
  "interval": "daily",
  "feeToleranceAbs": "0",
  "feeTolerancePct": "0",
  "autoMatchOnUpload": false
}

Las transacciones Pix no tienen comisiones intermedias ni liquidaciones parciales. Un Pix de R

150,00 en Midaz debe aparecer exactamente como R

150,00 en el extracto del BACEN. Establece ambos valores de tolerancia en cero — son strings decimales, así que pasa "0".Establecer autoMatchOnUpload en false te da control sobre cuándo se ejecuta la conciliación, lo cual es importante cuando necesitas que ambas fuentes estén ingestadas antes de ejecutar.

Consulta el esquema completo de la solicitud en Crear contexto.

Crear las fuentes

Cada contexto necesita dos fuentes: una para las transacciones de Midaz y otra para el extracto de liquidación del BACEN.Fuente A — Midaz (tipo LEDGER):

{
  "name": "Midaz - Pix Transactions",
  "type": "LEDGER",
  "side": "LEFT",
  "config": {}
}

LEDGER es la categoría de Matcher para datos de ledger interno — no es un conector directo con Midaz. Exportas las transacciones Pix del día desde Midaz (incluyendo el metadato endToEndId como columna plana) y subes la exportación a esta fuente, manualmente o mediante un pipeline automatizado. Consulta Matcher y Midaz para el flujo de exportación/importación.Fuente B — Extracto SPI del BACEN (tipo CUSTOM):

{
  "name": "BACEN SPI Settlement Extract",
  "type": "CUSTOM",
  "side": "RIGHT",
  "config": {
    "description": "Daily SPI settlement file from BACEN"
  }
}

La fuente del BACEN utiliza el tipo CUSTOM porque el archivo de liquidación SPI se carga manualmente o mediante un pipeline automatizado cada día.Cada fuente debe declarar un side (LEFT o RIGHT). Un contexto concilia su fuente LEFT contra su fuente RIGHT, así que asigna un lado a Midaz y el otro al BACEN, y mantén la asignación consistente en ambas fuentes.

Consulta el esquema completo de la solicitud en Crear fuente.

Crear mapeos de campos

Los mapeos de campos le indican a Matcher cómo traducir los campos de cada fuente a los campos canónicos utilizados para la conciliación.Un mapeo de campos es un objeto JSON con la forma { "<canonicalKey>": "<sourceColumn>" }. Las claves provienen del vocabulario canónico cerrado de Matcher (external_id, amount, currency, date y los opcionales description, fee_amount, fee_currency); los valores son los nombres de columna sin procesar en cada fuente. Las búsquedas son planas: el valor de un mapeo debe nombrar una columna de nivel superior de la fila, así que la exportación de Midaz debe traer el endToEndId como columna plana propia (consulta Matcher y Midaz — mapeo de campos personalizado).

external_id es la referencia de matching entre lados: el valor que el motor compara entre las dos fuentes cuando una regla define matchReference. Mapéalo al endToEndId en ambos lados. No mapees IDs locales de cada lado (el id de la transacción en Midaz, el id_liquidacao del BACEN) en external_id: esos valores nunca coinciden entre fuentes, así que el matching por referencia jamás encontraría una contraparte.

La siguiente tabla muestra cómo cada campo canónico se mapea a la columna en cada fuente:

Campo canónico	Columna de la exportación Midaz	Columna del extracto BACEN
`external_id`	`endToEndId`	`end_to_end_id`
`amount`	`amount`	`valor`
`currency`	`asset_code`	`moeda`
`date`	`created_at`	`data_liquidacao`

Fuente Midaz — mapeo de campos:

{
  "mapping": {
    "external_id": "endToEndId",
    "amount": "amount",
    "currency": "asset_code",
    "date": "created_at"
  }
}

Fuente BACEN — mapeo de campos:

{
  "mapping": {
    "external_id": "end_to_end_id",
    "amount": "valor",
    "currency": "moeda",
    "date": "data_liquidacao"
  }
}

Consulta Crear mapeo de campos para el esquema completo de la solicitud y Mapeo de campos para el vocabulario canónico.

Crear reglas de conciliación

Las reglas de conciliación definen cómo Matcher compara transacciones entre fuentes. Para la conciliación Pix, dos reglas cubren la gran mayoría de los escenarios.Regla 1 — Coincidencia exacta por endToEndId (prioridad 1):

{
  "type": "EXACT",
  "priority": 1,
  "config": {
    "matchAmount": true,
    "matchCurrency": true,
    "matchDate": true,
    "matchReference": true,
    "datePrecision": "DAY",
    "caseInsensitive": false,
    "referenceMustSet": true,
    "matchScore": 100
  }
}

Esta regla resuelve aproximadamente el 95% de los casos. El endToEndId es único por transacción Pix en todo el ecosistema. Cuando la referencia, el monto, la moneda y la fecha coinciden, es una conciliación confirmada con máxima confianza. Nota que caseInsensitive está en false porque los valores de endToEndId distinguen mayúsculas y minúsculas, y referenceMustSet está en true para asegurar que ambos lados contengan el endToEndId antes de comparar — esto previene falsos positivos basados solo en monto y fecha.Regla 2 — Tolerancia de fecha como respaldo (prioridad 51):

{
  "type": "DATE_LAG",
  "priority": 51,
  "config": {
    "maxDays": 1,
    "minDays": 0,
    "inclusive": true,
    "direction": "ABS",
    "feeTolerance": 0,
    "matchScore": 85,
    "matchCurrency": true
  }
}

Un Pix iniciado a las 23:58 puede liquidarse en el BACEN al día calendario siguiente. Esta regla permite una ventana de 1 día para cubrir escenarios de liquidación D+1. Nota que esta regla se basa únicamente en la coincidencia de monto y moneda — la comparación del endToEndId se maneja en la Regla 1.

Consulta Crear regla de conciliación para el esquema completo de la solicitud y todos los tipos de regla disponibles.

Activar y programar

Una vez que toda la configuración esté lista, activa el contexto y crea una programación diaria.Activar el contexto:

curl -X PATCH "https://api.matcher.example.com/v1/contexts/{contextId}" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{ "status": "ACTIVE" }'

Crear una programación para ejecutar diariamente a las 07:00 UTC:

curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/schedules" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "cronExpression": "0 7 * * *",
   "enabled": true
 }'

Ejecutar a las 07:00 UTC proporciona margen suficiente para que las liquidaciones D+1 aparezcan en el extracto del BACEN y para que el archivo diario se cargue antes de que se ejecute la conciliación.

Consulta Actualizar contexto y Crear programación para los esquemas completos de solicitud.

Operación diaria

Una vez configurado, el flujo de conciliación diaria sigue cinco pasos.

Cargar extracto del BACEN

Carga el archivo de liquidación SPI del día anterior a la fuente del BACEN. Matcher interpreta CSV, JSON, XML y otros formatos de su catálogo de formatos.

curl -X POST "https://api.matcher.example.com/v1/imports/contexts/{contextId}/sources/{sourceId}/upload" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: multipart/form-data" \
 -F "file=@bacen_spi_2026-03-17.csv" \
 -F "format=csv"

Este paso puede automatizarse mediante un pipeline que obtenga el archivo SPI y lo cargue antes de la ejecución programada de conciliación.

Subir la exportación de Midaz

Exporta las transacciones Pix confirmadas del día anterior desde Midaz — incluyendo el metadato endToEndId como columna plana — y sube la exportación a la fuente de Midaz de la misma forma. Este paso suele automatizarse con el mismo pipeline. Consulta Matcher y Midaz para el flujo de exportación/importación.

Matcher se ejecuta a las 07:00 (o manualmente)

La ejecución programada se realiza automáticamente a las 07:00 UTC. Para ejecutar la conciliación manualmente, utiliza el endpoint de ejecución.

curl -X POST "https://api.matcher.example.com/v1/matching/contexts/{contextId}/run" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{ "mode": "DRY_RUN" }'

Utiliza DRY_RUN primero para previsualizar resultados sin confirmarlos. Cuando estés satisfecho, ejecuta nuevamente con COMMIT:

curl -X POST "https://api.matcher.example.com/v1/matching/contexts/{contextId}/run" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{ "mode": "COMMIT" }'

Revisar resultados

Después de que la ejecución se complete, recupera los grupos conciliados para ver los resultados.

curl -X GET "https://api.matcher.example.com/v1/matching/runs/{runId}/groups" \
 -H "Authorization: Bearer $TOKEN"

Cada grupo muestra la transacción de Midaz conciliada y su entrada de liquidación correspondiente del BACEN, junto con la regla que las concilió y el puntaje de confianza.

Resolver excepciones

Las transacciones no conciliadas aparecen como excepciones. Estas requieren investigación — una transacción presente en una fuente pero no en la otra, o una discrepancia en monto o fecha más allá de la tolerancia configurada.Revisa las excepciones, determina la causa raíz y resuélvelas mediante forzar conciliación, ignorar o corregir los datos subyacentes.

Siempre ejecuta un DRY_RUN primero al probar nuevas reglas o después de cambios de configuración. Esto previene que coincidencias no deseadas se confirmen.

Ejemplo práctico — un día de datos

El siguiente ejemplo ilustra una ejecución de conciliación completa para el 17 de marzo de 2026.

Transacciones de Midaz (Fuente A)

ID (tipo)	endToEndId	Monto · fecha
txn-001 (Pix OUT)	E123456789202603170001	150.00 · 2026-03-17 10:15
txn-002 (Pix IN)	E987654321202603170042	3200.50 · 2026-03-17 11:30
txn-003 (Pix OUT)	E555666777202603170099	89.90 · 2026-03-17 23:58
txn-004 (Pix IN)	E111222333202603170007	500.00 · 2026-03-17 14:00

Extracto SPI del BACEN (Fuente B)

id_liquidacao	end_to_end_id	valor / data_liquidacao
liq-8801	E123456789202603170001	150.00 / 2026-03-17
liq-8802	E987654321202603170042	3200.50 / 2026-03-17
liq-8803	E555666777202603170099	89.90 / 2026-03-18
liq-8804	E444555666202603170055	750.00 / 2026-03-17

Resultados de la conciliación

endToEndId	Midaz ↔ BACEN	Resultado (regla)
E12345…0001	txn-001 ↔ liq-8801	Conciliado — EXACT (score: 100)
E98765…0042	txn-002 ↔ liq-8802	Conciliado — EXACT (score: 100)
E55566…0099	txn-003 ↔ liq-8803	Conciliado (D+1) — DATE_LAG (score: 85)
E11122…0007	txn-004 ↔ —	Excepción — —
E44455…0055	— ↔ liq-8804	Excepción — —

Análisis

txn-001 y txn-002: Coincidencia exacta en endToEndId, monto, moneda y fecha. La Regla 1 resolvió estos con puntaje de confianza 100.
txn-003: Pix iniciado a las 23:58, liquidado en el BACEN el 2026-03-18. La Regla 2 (DATE_LAG con ventana de 1 día) emparejó este con puntaje de confianza 85. Los matches de date-lag nunca se confirman automáticamente: el par va a la cola de revisión para confirmación humana.
txn-004: Presente en Midaz pero ausente en el BACEN. Posible fallo de liquidación o timeout del SPI. Investiga el estado de la transacción a través del plugin de Pix.
liq-8804: Presente en el BACEN pero ausente en Midaz. Un Pix entrante que no fue procesado. Verifica la entrega del webhook o reprocesa el mensaje.

Manejo de excepciones Pix

La siguiente tabla cubre los escenarios de excepción Pix más comunes y las acciones recomendadas.

Escenario	Causa probable	Acción recomendada
En Midaz, no en BACEN	Fallo de liquidación, timeout del SPI, transacción rechazada	Verifica el estado de la transacción en el plugin de Pix. Si fue rechazada, revierte en Midaz.
En BACEN, no en Midaz	Pix entrante no procesado, fallo de webhook	Reprocesa el mensaje. Crea una transacción manual si es necesario.
Discrepancia de monto	Raro en Pix (sin comisiones intermedias). Posible error de redondeo.	Investiga los registros originales. Fuerza la conciliación si la diferencia es aceptable.
Discrepancia de fecha (>1 día)	Transacción retenida, reprocesamiento	Verifica que sea el mismo Pix. Fuerza la conciliación o ignora.

Forzar conciliación

Cuando hayas confirmado que dos registros representan la misma transacción Pix pero Matcher no pudo conciliarlos automáticamente, utiliza forzar conciliación.

curl -X POST "https://api.matcher.example.com/v1/exceptions/{exceptionId}/force-match" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "notes": "Confirmed same Pix via endToEndId lookup in SPI",
   "overrideReason": "D+2 settlement delay confirmed with BACEN"
 }'

Ignorar transacción

Cuando una transacción debe excluirse de la conciliación (por ejemplo, una entrada duplicada o un Pix ya revertido), márcala como ignorada.

curl -X POST "https://api.matcher.example.com/v1/imports/contexts/{contextId}/transactions/{transactionId}/ignore" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "reason": "Pix reversal already processed — duplicate entry"
 }'

Consulta Forzar conciliación e Ignorar transacción para los esquemas completos de solicitud.

Devoluciones Pix (devoluções)

Las devoluciones Pix generan transacciones inversas que también necesitan conciliación. Cuando se procesa una devolución, el plugin de Pix crea una nueva transacción en Midaz con:

El originalEndToEndId que vincula de vuelta a la transacción Pix original
Un nuevo returnIdentification (rtrId) que identifica de forma única la devolución en el SPI

El extracto de liquidación del BACEN incluye entradas de devolución con ambos identificadores, lo que permite a Matcher conciliarlas contra las transacciones de devolución correspondientes en Midaz. Para volúmenes bajos de devoluciones, estas pueden conciliarse dentro del mismo contexto de Conciliación Diaria Pix. Para volúmenes altos, crea un contexto separado dedicado a la conciliación de devoluciones. Esto simplifica el triaje de excepciones y mantiene las métricas de devoluciones aisladas de las métricas del flujo estándar de Pix.

La iniciación de devoluciones mediante POST /v1/transfers/{id}/refunds es un endpoint del plugin de Pix, no un endpoint de Matcher. Matcher no inicia transferencias ni devoluciones — solo concilia las transacciones resultantes. Cada devolución lleva el originalEndToEndId y un nuevo returnIdentification para el seguimiento de extremo a extremo, que Matcher luego usa para conciliar la devolución contra el extracto de liquidación del BACEN. Para la iniciación de devoluciones, consulte la documentación del plugin de Pix.

Mejores prácticas

Usa endToEndId como referencia primaria

El endToEndId es el identificador único de Pix en todo el ecosistema — desde la institución iniciadora a través del SPI hasta la institución receptora. Asegúrate de que esté almacenado en los metadatos de la transacción de Midaz y presente en el extracto del BACEN. Sin él, la conciliación recurre a la coincidencia por monto y fecha, lo cual es mucho menos confiable.

Ejecuta la conciliación al día siguiente

Las transacciones Pix cercanas al fin del día pueden liquidarse en el BACEN en D+1. Programar Matcher para las 07:00 UTC asegura que todas las liquidaciones del día anterior estén incluidas en el extracto del BACEN antes de que se ejecute la conciliación. Esto elimina excepciones falsas causadas por diferencias de horario.

Separa Pix IN y Pix OUT para alto volumen

Al procesar altos volúmenes de Pix, crea dos contextos separados — uno para cash-out y otro para cash-in. Esto simplifica el triaje de excepciones, proporciona métricas más granulares por flujo y permite programación independiente si es necesario.

Monitorea la tasa de conciliación

Una conciliación Pix saludable alcanza una tasa de conciliación automática superior al 99%. Si la tasa cae por debajo del 95%, investiga problemas sistémicos como fallos del plugin, cambios en el formato del BACEN o metadatos faltantes en las transacciones de Midaz.

Tolerancia cero es el valor por defecto

Pix no tiene comisiones intermedias, liquidaciones parciales ni cargos de procesamiento. Si los montos divergen entre Midaz y el BACEN, indica un problema real — no redondeo. Mantén tanto feeToleranceAbs como feeTolerancePct en cero.

Previsualiza antes de confirmar

Siempre ejecuta un DRY_RUN antes de COMMIT, especialmente después de cambios en reglas o mapeos de campos. Esto te permite revisar los resultados de la conciliación y detectar errores de configuración antes de que afecten los datos de producción.

Métricas clave

Monitorea estas métricas para supervisar la salud de tu proceso de conciliación Pix.

Métrica	Valor saludable	Umbral de alerta
Tasa de conciliación automática	Superior al 99%	Inferior al 95%
Excepciones diarias	Inferior al 0.5% del volumen	Superior al 2%
Tiempo promedio de resolución	Menos de 4 horas	Más de 24 horas
Excepciones sin resolver 48h+	0	Más de 5

Utiliza los endpoints del dashboard de Matcher para monitorear estas métricas en tiempo real. Consulta Métricas del dashboard.

Próximos pasos

Contextos y fuentes

Aprende a configurar y gestionar contextos de conciliación y fuentes de datos.

Reglas de conciliación

Explora todos los tipos de regla disponibles y configuraciones avanzadas de conciliación.

Integración con Midaz

Profundiza en el mapeo automático de campos y la sincronización en tiempo real con Midaz Ledger.

Resolución de excepciones

Guía detallada sobre investigación, forzar conciliación y gestión de excepciones de conciliación.

Resumen

Guías

Matcher UI

Servidor MCP

Operaciones

Reconciliación Pix

Flujos de transacciones Pix

Pix enviado (cash-out)

Pix recibido (cash-in)

Configuración paso a paso

Operación diaria

Ejemplo práctico — un día de datos

Transacciones de Midaz (Fuente A)

Extracto SPI del BACEN (Fuente B)

Resultados de la conciliación

Análisis

Manejo de excepciones Pix

Forzar conciliación

Ignorar transacción

Devoluciones Pix (devoluções)

Mejores prácticas

Métricas clave

Próximos pasos

Contextos y fuentes

Reglas de conciliación

Integración con Midaz

Resolución de excepciones

​Flujos de transacciones Pix

​Pix enviado (cash-out)

​Pix recibido (cash-in)

​Configuración paso a paso

​Operación diaria

​Ejemplo práctico — un día de datos

​Transacciones de Midaz (Fuente A)

​Extracto SPI del BACEN (Fuente B)

​Resultados de la conciliación

​Análisis

​Manejo de excepciones Pix

​Forzar conciliación

​Ignorar transacción

​Devoluciones Pix (devoluções)

​Mejores prácticas

​Métricas clave

​Próximos pasos

Contextos y fuentes

Reglas de conciliación

Integración con Midaz

Resolución de excepciones

Flujos de transacciones Pix

Pix enviado (cash-out)

Pix recibido (cash-in)

Configuración paso a paso

Operación diaria

Ejemplo práctico — un día de datos

Transacciones de Midaz (Fuente A)

Extracto SPI del BACEN (Fuente B)

Resultados de la conciliación

Análisis

Manejo de excepciones Pix

Forzar conciliación

Ignorar transacción

Devoluciones Pix (devoluções)

Mejores prácticas

Métricas clave

Próximos pasos