Conciliación de Pix

Esta guía explica cómo conciliar transacciones de Pix entre Midaz Ledger y los datos de liquidación de BACEN (Banco Central de Brasil) usando Matcher. Cubre tanto el Pix enviado (cash-out) como el 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 que concilia tus transacciones de Pix contra los extractos de liquidación SPI de BACEN todos los días.

Flujos de transacciones de Pix

Los dos flujos siguientes muestran qué necesita conciliar Matcher en cada lado.

Pix enviado (cash-out)

Flujo de cash-out de Pix enviado — Flujo de cash-out: desde la iniciación del cliente hasta la liquidación en SPI y la conciliación en Matcher.

El cliente inicia el Pix: el usuario final activa un pago Pix mediante la aplicación o la API.
El plugin crea la iniciación: el plugin de Pix crea un registro de iniciación y resuelve la cuenta de destino mediante una consulta a 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 que confirma la liquidación. La transacción de Midaz queda confirmada.
Matcher concilia: Matcher compara la transacción confirmada de Midaz con la entrada correspondiente en el extracto de liquidación SPI de BACEN.

Pix recibido (cash-in)

Flujo de cash-in de Pix recibido — Flujo de cash-in: desde la notificación entrante de SPI hasta el crédito en Midaz y la conciliación en Matcher.

Llega un Pix entrante: SPI envía un webhook síncrono 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 receptora.
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 de Midaz con la entrada correspondiente en el extracto de liquidación SPI de BACEN.

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

Configuración paso a paso

Crea el contexto

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

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

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

150.00 en Midaz debe aparecer como exactamente R

150.00 en el extracto de BACEN. Configura ambos valores de tolerancia en cero. Son cadenas decimales, así que pasa "0".Configurar autoMatchOnUpload en false te da control sobre cuándo se ejecuta el emparejamiento. Ese control importa cuando necesitas que ambas fuentes estén ingeridas antes de que se ejecute la corrida.

Consulta el esquema completo de la solicitud en Crear contexto.

Crea las fuentes

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

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

LEDGER es la categoría de Matcher para los datos del ledger interno. No es un conector en vivo de Midaz. Exportas las transacciones de Pix del día desde Midaz, incluyendo los metadatos de endToEndId como una columna plana. Luego subes la exportación a esta fuente, de forma manual o mediante un pipeline automatizado. Consulta Matcher y Midaz para ver el flujo de exportación e importación.Fuente B, extracto SPI de BACEN (tipo CUSTOM):

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

La fuente de BACEN usa el tipo CUSTOM porque subes el archivo de liquidación SPI de forma manual 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. Asigna un lado a Midaz y el otro a BACEN. Mantén la asignación consistente en ambas fuentes.

Consulta el esquema completo de la solicitud en Crear fuente.

Crea los mapas de campos

Los mapas de campos le indican a Matcher cómo traducir los campos de cada fuente a los campos canónicos que se usan para el emparejamiento.Un mapa 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, de forma opcional, description, fee_amount, fee_currency). Los valores son los nombres de columna sin procesar en cada fuente. Las búsquedas son planas. Un valor de mapeo debe nombrar una columna de nivel superior en la fila. Por lo tanto, la exportación de Midaz debe llevar endToEndId como su propia columna plana (consulta Matcher y Midaz — mapeo de campos personalizado).

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

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

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

Mapa de campos de la fuente Midaz:

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

Mapa de campos de la fuente BACEN:

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

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

Crea las reglas de coincidencia

Las reglas de coincidencia definen cómo Matcher compara las transacciones entre fuentes. Para la conciliación de 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 de Pix en todo el ecosistema. Una coincidencia en referencia, monto, moneda y fecha da una conciliación confirmada con la máxima confianza. La regla configura caseInsensitive en false porque los valores de endToEndId distinguen mayúsculas de minúsculas. La regla configura referenceMustSet en true, así que ambos lados deben llevar el endToEndId antes de la comparación. Esto evita falsos positivos basados solo en monto y fecha.Regla 2 (respaldo con tolerancia de fecha, 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 BACEN al día calendario siguiente. Esta regla permite una ventana de 1 día para cubrir escenarios de liquidación D+1. Esta regla depende únicamente de la coincidencia de monto y moneda. La Regla 1 se encarga de la comparación de endToEndId.

Consulta Crear regla de coincidencia para ver el esquema completo de la solicitud y todos los tipos de regla disponibles.

Activa y programa

Una vez que toda la configuración esté lista, activa el contexto y crea una programación diaria.Activa 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" }'

Crea una programación para ejecutarse a diario 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
 }'

Ejecutarse a las 07:00 UTC brinda margen suficiente para que las liquidaciones D+1 aparezcan en el extracto de BACEN. También te da tiempo para subir el archivo diario antes de que se ejecute la corrida de emparejamiento.

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

Operación diaria

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

Sube el extracto de BACEN

Sube el archivo de liquidación SPI del día anterior a la fuente de BACEN. Matcher analiza 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"

Puedes automatizar este paso con un pipeline que obtenga el archivo SPI y lo suba antes de la corrida de emparejamiento programada.

Sube el export de Midaz

Exporta las transacciones de Pix confirmadas del día anterior desde Midaz, incluyendo los metadatos de endToEndId como una columna plana. Sube la exportación a la fuente de Midaz de la misma forma. Por lo general, el mismo pipeline automatiza este paso. Consulta Matcher y Midaz para ver el flujo de exportación e importación.

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

La corrida programada se ejecuta automáticamente a las 07:00 UTC. Para ejecutar el emparejamiento manualmente, usa 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" }'

Usa DRY_RUN primero para previsualizar los resultados sin confirmarlos. Cuando estés conforme, ejecuta de nuevo 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" }'

Revisa los resultados

Después de que la corrida termine, obtén los grupos emparejados 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 emparejada y su entrada correspondiente de liquidación en BACEN, junto con la regla que las emparejó y la puntuación de confianza.

Resuelve las 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 de monto o fecha que supera la tolerancia configurada.Revisa las excepciones, determina la causa raíz y resuélvelas forzando la coincidencia, ignorándolas o corrigiendo los datos subyacentes.

Ejecuta siempre un DRY_RUN primero al probar reglas nuevas o después de cambios de configuración. Esto evita que Matcher confirme coincidencias no deseadas.

Ejemplo práctico: un día de datos

El siguiente ejemplo ilustra una corrida 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 de 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 coincidencia

endToEndId	Midaz ↔ BACEN	Resultado (regla)
E12345…0001	txn-001 ↔ liq-8801	Coincidencia — EXACT (puntuación: 100)
E98765…0042	txn-002 ↔ liq-8802	Coincidencia — EXACT (puntuación: 100)
E55566…0099	txn-003 ↔ liq-8803	Coincidencia (D+1) — DATE_LAG (puntuación: 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ó estas con una puntuación de confianza de 100.
txn-003: Pix iniciado a las 23:58, liquidado en BACEN el 2026-03-18. La Regla 2 (DATE_LAG con ventana de 1 día) emparejó este caso con una puntuación de confianza de 85. Las coincidencias con tolerancia de fecha nunca se confirman automáticamente. El par queda en la cola de revisión para que una persona lo confirme.
txn-004: presente en Midaz pero ausente en BACEN. Posible falla de liquidación o timeout de SPI. Investiga el estado de la transacción a través del plugin de Pix.
liq-8804: presente en BACEN pero ausente en Midaz. Este Pix entrante no llegó al ledger. Revisa la entrega del webhook o reprocesa el mensaje.

Gestión de excepciones de Pix

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

Escenario	Causa probable	Acción recomendada
En Midaz, no en BACEN	Falla de liquidación, timeout de SPI, transacción rechazada	Revisa 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, falla del webhook	Reprocesa el mensaje. Crea una transacción manual si es necesario.
Discrepancia de monto	Poco común en Pix (sin tarifas intermedias). Posible error de redondeo.	Investiga los registros originales. Fuerza la coincidencia si la diferencia es aceptable.
Discrepancia de fecha (>1 día)	Transacción retenida, reprocesamiento	Verifica que sea el mismo Pix. Fuerza la coincidencia o ignórala.

Forzar coincidencia

Cuando hayas confirmado que dos registros representan la misma transacción de Pix pero Matcher no pudo emparejarlos automáticamente, usa la función de forzar coincidencia.

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 debas excluir una transacción 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 coincidencia e Ignorar transacción para ver los esquemas completos de la solicitud.

Devoluciones de Pix (devoluções)

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

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

El extracto de liquidación de BACEN incluye entradas de devolución con ambos identificadores, lo que permite que Matcher las concilie contra las transacciones de devolución correspondientes en Midaz. Para volúmenes bajos de devoluciones, puedes conciliarlas dentro del mismo contexto de Pix Daily Reconciliation. 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 la devolución 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 usa después para emparejar la devolución con el extracto de liquidación de BACEN. Para la iniciación de la devolución, consulta la documentación del plugin de Pix.

Mejores prácticas

Usa endToEndId como referencia principal

El endToEndId es el identificador único de Pix en todo el ecosistema, desde la institución iniciadora, pasando por SPI, hasta la institución receptora. Guárdalo en los metadatos de la transacción de Midaz y asegúrate de que el extracto de BACEN lo lleve. Sin él, la conciliación recae en la coincidencia por monto y fecha, que es mucho menos confiable.

Ejecuta la conciliación al día siguiente

Las transacciones de Pix cercanas al final del día pueden liquidarse en BACEN en D+1. Programar Matcher para las 07:00 UTC garantiza que el extracto de BACEN incluya todas las liquidaciones del día anterior antes de que se ejecute el emparejamiento. Esto elimina las excepciones falsas causadas por diferencias de horario.

Separa Pix IN y Pix OUT para volúmenes altos

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

Monitorea la tasa de coincidencia

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

La tolerancia cero es el valor predeterminado

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

Previsualiza antes de confirmar

Ejecuta siempre un DRY_RUN antes de COMMIT, en especial después de cambios en reglas o mapas de campos. Esto te permite revisar los resultados de la coincidencia y detectar errores de configuración antes de que afecten los datos de producción.

Métricas clave

Da seguimiento a estas métricas para monitorear la salud de tu proceso de conciliación de Pix.

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

Usa 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 coincidencia

Explora todos los tipos de regla disponibles y las configuraciones de coincidencia avanzadas.

Integración con Midaz

Aprende sobre el mapeo automático de campos y la fuente de datos de Midaz Ledger.

Resolución de excepciones

Guía detallada sobre cómo investigar, forzar coincidencias y gestionar excepciones de conciliación.

Resumen

Guías

Matcher UI

Servidor MCP

Operaciones

Conciliación de Pix

Flujos de transacciones de 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 de BACEN (Fuente B)

Resultados de la coincidencia

Análisis

Gestión de excepciones de Pix

Forzar coincidencia

Ignorar transacción

Devoluciones de Pix (devoluções)

Mejores prácticas

Métricas clave

Próximos pasos

Contextos y fuentes

Reglas de coincidencia

Integración con Midaz

Resolución de excepciones

​Flujos de transacciones de 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 de BACEN (Fuente B)

​Resultados de la coincidencia

​Análisis

​Gestión de excepciones de Pix

​Forzar coincidencia

​Ignorar transacción

​Devoluciones de Pix (devoluções)

​Mejores prácticas

​Métricas clave

​Próximos pasos

Contextos y fuentes

Reglas de coincidencia

Integración con Midaz

Resolución de excepciones

Flujos de transacciones de 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 de BACEN (Fuente B)

Resultados de la coincidencia

Análisis

Gestión de excepciones de Pix

Forzar coincidencia

Ignorar transacción

Devoluciones de Pix (devoluções)

Mejores prácticas

Métricas clave

Próximos pasos