Pix reconciliation

This guide walks through reconciling Pix transactions between Midaz Ledger and BACEN (Brazil’s Central Bank) settlement data using Matcher. It covers both Pix sent (cash-out) and Pix received (cash-in), from configuration to daily operation and exception handling. By the end of this guide, you will have a fully configured Matcher context that automatically reconciles your Pix transactions against BACEN’s SPI settlement extracts on a daily basis.

Pix transaction flows

Understanding how Pix transactions flow through the system is essential for configuring reconciliation correctly. The two flows below show what Matcher needs to reconcile on each side.

Pix sent (cash-out)

Client initiates Pix — The end user triggers a Pix payment via the app or API.
Plugin creates initiation — The Pix plugin creates an initiation record and resolves the destination account via DICT lookup.
Plugin processes payment — The plugin debits the client account in Midaz (transaction in pending status) and sends the payment instruction to SPI.
Settlement confirmed — SPI sends a webhook confirming settlement. The Midaz transaction is committed.
Matcher reconciles — Matcher compares the committed Midaz transaction against the corresponding entry in the BACEN SPI settlement extract.

Pix received (cash-in)

Inbound Pix arrives — SPI sends a synchronous webhook containing the inbound Pix data.
Plugin validates — The Pix plugin validates the payload and approves the transaction.
Credit transaction created — The plugin creates a CREDIT transaction in Midaz for the recipient account.
Settlement confirmed — The settlement webhook confirms the transaction is final.
Matcher reconciles — Matcher compares the Midaz credit transaction against the corresponding entry in the BACEN SPI settlement extract.

In both flows, the endToEndId is the unique identifier that links the Midaz transaction to the BACEN settlement record. This is the primary key for reconciliation.

Configuration step-by-step

Create the context

Create a reconciliation context for Pix transactions. Use type 1:1 because each Pix transaction has exactly one corresponding BACEN settlement entry.

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

Pix transactions have no intermediate fees or partial settlements. A Pix of R

150.00 in Midaz must appear as exactly R

150.00 in the BACEN extract. Set both tolerance values to zero — they are decimal strings, so pass "0".Setting autoMatchOnUpload to false gives you control over when matching runs, which is important when you need both sources ingested before executing.

See the full request schema at Create context.

Create the sources

Each context needs two sources: one for Midaz transactions and one for the BACEN settlement extract.Source A — Midaz (type LEDGER):

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

LEDGER is Matcher’s category for internal ledger data — it is not a live Midaz connector. You export the day’s Pix transactions from Midaz (including the endToEndId metadata as a flat column) and upload the export to this source, manually or via an automated pipeline. See Matcher and Midaz for the export/import flow.Source B — BACEN SPI extract (type CUSTOM):

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

The BACEN source uses type CUSTOM because the SPI settlement file is uploaded manually or via an automated pipeline each day.Each source must declare a side (LEFT or RIGHT). A context reconciles its LEFT source against its RIGHT source, so assign one side to Midaz and the other to BACEN and keep the assignment consistent across both sources.

See the full request schema at Create source.

Create field maps

Field maps tell Matcher how to translate fields from each source into the canonical fields used for matching.A field map is a JSON object in the form { "<canonicalKey>": "<sourceColumn>" }. The keys come from Matcher’s closed canonical vocabulary (external_id, amount, currency, date, and optional description, fee_amount, fee_currency); the values are the raw column names in each source. Lookups are flat — a mapping value must name a top-level column in the row, so the Midaz export must carry endToEndId as its own flat column (see Matcher and Midaz — custom field mapping).

external_id is the cross-side matching reference — the value the engine compares between the two sources when a rule sets matchReference. Map it to the endToEndId on both sides. Do not map side-local row IDs (the Midaz transaction id, the BACEN id_liquidacao) into external_id: those values never agree across sources, so reference matching would never find a counterpart.

The following table shows how each canonical field maps to the column in each source:

Canonical field	Midaz export column	BACEN extract column
`external_id`	`endToEndId`	`end_to_end_id`
`amount`	`amount`	`valor`
`currency`	`asset_code`	`moeda`
`date`	`created_at`	`data_liquidacao`

Midaz source — field map:

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

BACEN source — field map:

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

See Create field map for the full request schema and Field mapping for the canonical vocabulary.

Create match rules

Match rules define how Matcher compares transactions across sources. For Pix reconciliation, two rules cover the vast majority of scenarios.Rule 1 — Exact match by endToEndId (priority 1):

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

This rule resolves approximately 95% of cases. The endToEndId is unique per Pix transaction across the entire ecosystem. When the reference, amount, currency, and date all match, it is a confirmed reconciliation with maximum confidence. Note that caseInsensitive is set to false because endToEndId values are case-sensitive, and referenceMustSet is true to ensure both sides carry the endToEndId before comparing — this prevents false positives on amount and date alone.Rule 2 — Date tolerance fallback (priority 51):

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

A Pix initiated at 23:58 may settle in BACEN on the following calendar day. This rule allows a 1-day window to cover D+1 settlement scenarios. Note that this rule relies on amount and currency matching only — the endToEndId comparison is handled by Rule 1.

See Create match rule for the full request schema and all available rule types.

Activate and schedule

Once all configuration is in place, activate the context and create a daily schedule.Activate the context:

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

Create a schedule to run daily at 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
 }'

Running at 07:00 UTC provides enough margin for D+1 settlements to appear in the BACEN extract and for the daily file to be uploaded before the matching run executes.

See Update context and Create schedule for the full request schemas.

Daily operation

Once configured, the daily reconciliation workflow follows five steps.

Upload BACEN extract

Upload the previous day’s SPI settlement file to the BACEN source. Matcher parses CSV, JSON, XML, and other formats from its format catalog.

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"

This step can be automated via a pipeline that fetches the SPI file and uploads it before the scheduled matching run.

Upload the Midaz export

Export the previous day’s committed Pix transactions from Midaz — including the endToEndId metadata as a flat column — and upload the export to the Midaz source the same way. This step is usually automated by the same pipeline. See Matcher and Midaz for the export/import flow.

Matcher runs at 07:00 (or manually)

The scheduled run executes automatically at 07:00 UTC. To run matching manually, use the run endpoint.

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" }'

Use DRY_RUN first to preview results without committing them. When satisfied, run again with 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" }'

Review results

After the run completes, retrieve the matched groups to see the results.

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

Each group shows the matched Midaz transaction and its corresponding BACEN settlement entry, along with the rule that matched them and the confidence score.

Resolve exceptions

Unmatched transactions appear as exceptions. These require investigation — a transaction present in one source but not the other, or a mismatch in amount or date beyond the configured tolerance.Review exceptions, determine the root cause, and resolve them by force matching, ignoring, or correcting the underlying data.

Always run a DRY_RUN first when testing new rules or after configuration changes. This prevents unintended matches from being committed.

Practical example — one day of data

The following example illustrates a complete reconciliation run for March 17, 2026.

Midaz transactions (Source A)

ID (type)	endToEndId	Amount · date
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

BACEN SPI extract (Source 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

Match results

endToEndId	Midaz ↔ BACEN	Result (rule)
E12345…0001	txn-001 ↔ liq-8801	Match — EXACT (score: 100)
E98765…0042	txn-002 ↔ liq-8802	Match — EXACT (score: 100)
E55566…0099	txn-003 ↔ liq-8803	Match (D+1) — DATE_LAG (score: 85)
E11122…0007	txn-004 ↔ —	Exception — —
E44455…0055	— ↔ liq-8804	Exception — —

Analysis

txn-001 and txn-002: Exact match on endToEndId, amount, currency, and date. Rule 1 resolved these with confidence score 100.
txn-003: Pix initiated at 23:58, settled in BACEN on 2026-03-18. Rule 2 (DATE_LAG with 1-day window) paired this with confidence score 85. Date-lag matches never auto-confirm — the pair lands in the review queue for a human to confirm.
txn-004: Present in Midaz but absent from BACEN. Possible settlement failure or SPI timeout. Investigate the transaction status via the Pix plugin.
liq-8804: Present in BACEN but absent from Midaz. An inbound Pix that was not processed. Check webhook delivery or reprocess the message.

Handling Pix exceptions

The following table covers the most common Pix exception scenarios and recommended actions.

Scenario	Probable cause	Recommended action
In Midaz, not in BACEN	Settlement failure, SPI timeout, rejected transaction	Check transaction status in the Pix plugin. If rejected, revert in Midaz.
In BACEN, not in Midaz	Inbound Pix not processed, webhook failure	Reprocess the message. Create a manual transaction if needed.
Amount mismatch	Rare in Pix (no intermediate fees). Possible rounding error.	Investigate original records. Force match if the difference is acceptable.
Date mismatch (>1 day)	Held transaction, reprocessing	Verify it is the same Pix. Force match or ignore.

Force match

When you have confirmed that two records represent the same Pix transaction but Matcher could not match them automatically, use force match.

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"
 }'

Ignore transaction

When a transaction should be excluded from reconciliation (for example, a duplicate entry or an already-reversed Pix), mark it as ignored.

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"
 }'

See Force match and Ignore transaction for the full request schemas.

Pix refunds (devoluções)

Pix refunds generate reverse transactions that also need reconciliation. When a refund is processed, the Pix plugin creates a new transaction in Midaz with:

The originalEndToEndId linking back to the original Pix transaction
A new returnIdentification (rtrId) that uniquely identifies the refund in SPI

BACEN’s settlement extract includes refund entries with both identifiers, allowing Matcher to reconcile them against the corresponding Midaz refund transactions. For low refund volumes, these can be reconciled within the same Pix Daily Reconciliation context. For high volumes, create a separate context dedicated to refund reconciliation. This simplifies exception triage and keeps refund metrics isolated from standard Pix flow metrics.

Refund initiation via POST /v1/transfers/{id}/refunds is a Pix plugin endpoint, not a Matcher endpoint. Matcher does not initiate transfers or refunds — it only reconciles the resulting transactions. Each refund carries the originalEndToEndId and a new returnIdentification for end-to-end tracking, which Matcher then uses to match the refund against BACEN’s settlement extract. For refund initiation, see the Pix plugin documentation.

Best practices

Use endToEndId as the primary reference

The endToEndId is the unique Pix identifier across the entire ecosystem — from the initiating institution through SPI to the receiving institution. Ensure it is stored in Midaz transaction metadata and present in the BACEN extract. Without it, reconciliation falls back to amount and date matching, which is far less reliable.

Run reconciliation the following day

Pix transactions near end of day may settle in BACEN on D+1. Scheduling Matcher for 07:00 UTC ensures all settlements from the previous day are included in the BACEN extract before matching runs. This eliminates false exceptions caused by timing.

Separate Pix IN and Pix OUT for high volume

When processing high Pix volumes, create two separate contexts — one for cash-out and one for cash-in. This simplifies exception triage, provides more granular metrics per flow, and allows independent scheduling if needed.

Monitor match rate

A healthy Pix reconciliation achieves greater than 99% automatic match rate. If the rate drops below 95%, investigate systemic issues such as plugin failures, BACEN format changes, or missing metadata in Midaz transactions.

Zero tolerance is the default

Pix has no intermediate fees, partial settlements, or processing charges. If amounts diverge between Midaz and BACEN, it indicates a real problem — not rounding. Keep both feeToleranceAbs and feeTolerancePct at zero.

Preview before committing

Always run a DRY_RUN before COMMIT, especially after rule or field map changes. This lets you review match results and catch configuration errors before they affect production data.

Key metrics

Track these metrics to monitor the health of your Pix reconciliation process.

Metric	Healthy value	Alert threshold
Automatic match rate	Above 99%	Below 95%
Daily exceptions	Below 0.5% of volume	Above 2%
Average resolution time	Under 4 hours	Over 24 hours
Unresolved exceptions 48h+	0	More than 5

Use Matcher’s dashboard endpoints to monitor these metrics in real time. See Dashboard metrics.

Next steps

Contexts and sources

Learn how to configure and manage reconciliation contexts and data sources.

Match rules

Explore all available rule types and advanced matching configurations.

Midaz integration

Deep dive into automatic field mapping and real-time sync with Midaz Ledger.

Resolving exceptions

Detailed guide on investigating, force matching, and managing reconciliation exceptions.

Overview

Guides

Matcher UI

MCP Server

Operations

Pix reconciliation

Pix transaction flows

Pix sent (cash-out)

Pix received (cash-in)

Configuration step-by-step

Daily operation

Practical example — one day of data

Midaz transactions (Source A)

BACEN SPI extract (Source B)

Match results

Analysis

Handling Pix exceptions

Force match

Ignore transaction

Pix refunds (devoluções)

Best practices

Key metrics

Next steps

Contexts and sources

Match rules

Midaz integration

Resolving exceptions

​Pix transaction flows

​Pix sent (cash-out)

​Pix received (cash-in)

​Configuration step-by-step

​Daily operation

​Practical example — one day of data

​Midaz transactions (Source A)

​BACEN SPI extract (Source B)

​Match results

​Analysis

​Handling Pix exceptions

​Force match

​Ignore transaction

​Pix refunds (devoluções)

​Best practices

​Key metrics

​Next steps

Contexts and sources

Match rules

Midaz integration

Resolving exceptions

Pix transaction flows

Pix sent (cash-out)

Pix received (cash-in)

Configuration step-by-step

Daily operation

Practical example — one day of data

Midaz transactions (Source A)

BACEN SPI extract (Source B)

Match results

Analysis

Handling Pix exceptions

Force match

Ignore transaction

Pix refunds (devoluções)

Best practices

Key metrics

Next steps