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 Matcher context that reconciles your Pix transactions against BACEN’s SPI settlement extracts every day.

Pix transaction flows

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 becomes 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",
  "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. The match rules below compare amounts exactly.Setting autoMatchOnUpload to false gives you control over when matching runs. Use that control when you need both sources ingested before the run executes.

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. You then 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 you upload the SPI settlement file 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. Assign one side to Midaz and the other to BACEN. 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 whose keys come from Matcher’s closed vocabulary: external_id, amount, currency, and date, plus the optional description, fee_amount, fee_currency, and direction. The direction key takes an object, {column, debit, credit}, for a file that marks each row as debit or credit in a separate column. Every other key takes a raw column name in the source. Lookups are flat. A mapping value must name a top-level column in the row. The Midaz export must therefore 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
  }
}

This rule resolves approximately 95% of cases. The endToEndId is unique per Pix transaction across the entire ecosystem. A match on reference, amount, currency, and date gives a confirmed reconciliation with maximum confidence. The rule sets caseInsensitive to false because endToEndId values are case-sensitive. The rule sets referenceMustSet to true, so both sides must carry the endToEndId before comparison. 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,
    "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. This rule relies on amount and currency matching only. Rule 1 handles the endToEndId comparison.

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. It also gives you time to upload the daily file 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 "format=csv" \
 -F "file=@bacen_spi_2026-03-17.csv"

You can automate this step with 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. Upload the export to the Midaz source the same way. The same pipeline usually automates this step. 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?contextId={contextId}" \
 -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 Matcher from committing unintended matches.

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	Proposed, D+1 (DATE_LAG, score: 90)
E11122…0007	txn-004 ↔ none	Exception (no rule)
E44455…0055	none ↔ liq-8804	Exception (no rule)

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) proposed this pair with confidence score 90. Matcher never confirms a DATE_LAG group automatically: it proposes the group, whatever its score. To pair the two transactions, un-match the proposed group, then create a manual match.
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. This inbound Pix did not reach the ledger. 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).	Investigate original records. Create a manual match if the difference is acceptable.
Date mismatch (>1 day)	Held transaction, reprocessing	Verify it is the same Pix. Create a manual match, or ignore the transaction.

Manual match

When you have confirmed that two records represent the same Pix transaction but Matcher could not match them automatically, pair them with a manual match. Matcher creates a CONFIRMED match group at confidence 100.

curl -X POST "https://api.matcher.example.com/v1/matching/manual?contextId={contextId}" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "transactionIds": ["{midazTransactionId}", "{bacenTransactionId}"],
   "notes": "Same Pix confirmed via endToEndId lookup in SPI. D+2 settlement delay confirmed with BACEN"
 }'

Ignore transaction

When you must exclude a transaction 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 Create manual match and Ignore transaction for the full request schemas.

Pix refunds (devoluções)

Pix refunds generate reverse transactions that also need reconciliation. When the Pix plugin processes a refund, it 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, so Matcher can reconcile them against the corresponding Midaz refund transactions. For low refund volumes, you can reconcile these 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. Store it in Midaz transaction metadata and make sure the BACEN extract carries it. 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 the BACEN extract includes all settlements from the previous day 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 feeTolerance at 0 on the DATE_LAG rule.

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

Learn about automatic field mapping and the Midaz Ledger data source.

Resolving exceptions

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

Overview

Guides

Console

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

Manual 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

​Manual 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

Manual match

Ignore transaction

Pix refunds (devoluções)

Best practices

Key metrics

Next steps