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á un contexto de Matcher completamente configurado que concilia automáticamente sus 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

Cree un contexto de conciliación para transacciones Pix. Utilice 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. Establezca ambos valores de tolerancia en cero.Establecer autoMatchOnUpload en false le da control sobre cuándo se ejecuta la conciliación, lo cual es importante cuando necesita que ambas fuentes estén ingestadas antes de ejecutar.

Consulte 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",
  "config": {
    "ledger_id": "your-ledger-id",
    "currency": "BRL"
  }
}

Cuando Midaz está integrado con Matcher (consulte Integración con Midaz), las transacciones se ingestan automáticamente mediante sincronización basada en eventos. No se necesita carga manual para esta fuente.Fuente B — Extracto SPI del BACEN (tipo CUSTOM):

{
  "name": "BACEN SPI Settlement Extract",
  "type": "CUSTOM",
  "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.

Consulte 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.La siguiente tabla muestra el mapeo entre los campos canónicos de Matcher y los campos de cada fuente:

Campo de Matcher	Midaz (automático)	Extracto BACEN (mapeo de campos)
`transaction_id`	`id`	`id_liquidacao`
`amount`	`amount`	`valor`
`currency`	`asset_code`	`moeda`
`date`	`created_at`	`data_liquidacao`
`reference`	`metadata.endToEndId`	`end_to_end_id`

Cuando Midaz está integrado con Matcher, los campos estándar se mapean automáticamente. El endToEndId reside en los metadatos de la transacción y requiere una personalización del mapeo de campos en la configuración de la fuente (consulte Integración con Midaz — mapeo de campos personalizado):Fuente Midaz — mapeo de campos con override de endToEndId:

{
  "mapping": {
    "id": "transaction_id",
    "amount": "amount",
    "asset_code": "currency",
    "created_at": "date",
    "metadata.endToEndId": "reference"
  }
}

Fuente BACEN — mapeo de campos:

{
  "mapping": {
    "id_liquidacao": "transaction_id",
    "valor": "amount",
    "moeda": "currency",
    "data_liquidacao": "date",
    "end_to_end_id": "reference"
  }
}

Consulte Crear mapeo de campos para el esquema completo de la solicitud e Integración con Midaz para detalles sobre el mapeo automático de campos.

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. Note 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. El matchScore más bajo de 85 indica que estas coincidencias deben revisarse con un poco más de atención, aunque siguen siendo válidas. Note que esta regla se basa únicamente en la coincidencia de monto y moneda — la comparación del endToEndId se maneja en la Regla 1.

Consulte 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, active el contexto y cree 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.

Consulte 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

Cargue el archivo de liquidación SPI del día anterior a la fuente del BACEN. Matcher acepta formatos CSV y JSON.

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.

Datos de Midaz disponibles automáticamente

Con la integración de Midaz configurada, las transacciones se ingestan continuamente en Matcher a medida que se confirman. No se necesita carga manual para la Fuente A. Consulte Integración con Midaz para detalles de configuració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, utilice 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" }'

Utilice DRY_RUN primero para previsualizar resultados sin confirmarlos. Cuando esté satisfecho, ejecute 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, recupere 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.Revise las excepciones, determine la causa raíz y resuélvalas mediante forzar conciliación, ignorar o corregir los datos subyacentes.

Siempre ejecute 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	endToEndId	Amount	Type	Date
txn-001	E123456789202603170001	150.00	Pix OUT	2026-03-17 10:15
txn-002	E987654321202603170042	3200.50	Pix IN	2026-03-17 11:30
txn-003	E555666777202603170099	89.90	Pix OUT	2026-03-17 23:58
txn-004	E111222333202603170007	500.00	Pix IN	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) resolvió este con puntaje de confianza 85.
txn-004: Presente en Midaz pero ausente en el BACEN. Posible fallo de liquidación o timeout del SPI. Investigue 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. Verifique la entrega del webhook o reprocese 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	Verifique el estado de la transacción en el plugin de Pix. Si fue rechazada, revierta en Midaz.
En BACEN, no en Midaz	Pix entrante no procesado, fallo de webhook	Reprocese el mensaje. Cree una transacción manual si es necesario.
Discrepancia de monto	Raro en Pix (sin comisiones intermedias). Posible error de redondeo.	Investigue los registros originales. Fuerce la conciliación si la diferencia es aceptable.
Discrepancia de fecha (>1 día)	Transacción retenida, reprocesamiento	Verifique que sea el mismo Pix. Fuerce la conciliación o ignore.

Forzar conciliación

Cuando haya confirmado que dos registros representan la misma transacción Pix pero Matcher no pudo conciliarlos automáticamente, utilice 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árquela 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"
 }'

Consulte 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, cree 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.

El plugin de Pix soporta la iniciación de devoluciones mediante POST /v1/transfers/{id}/refunds. Cada devolución lleva el originalEndToEndId y un nuevo returnIdentification para el seguimiento de extremo a extremo.

Mejores prácticas

Use 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úrese 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.

Ejecute 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.

Separe Pix IN y Pix OUT para alto volumen

Al procesar altos volúmenes de Pix, cree 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.

Monitoree 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%, investigue 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. Mantenga tanto feeToleranceAbs como feeTolerancePct en cero.

Previsualice antes de confirmar

Siempre ejecute un DRY_RUN antes de COMMIT, especialmente después de cambios en reglas o mapeos de campos. Esto le 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

Monitoree estas métricas para supervisar la salud de su 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

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

Próximos pasos

Contextos y fuentes

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

Reglas de conciliación

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

Integración con Midaz

Profundice 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.

​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