> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Matcher and Midaz

> See how Matcher works alongside Midaz Ledger — two independent services that share data through exports and imports rather than a live API connection.

<Info>
  **There's no direct Matcher-to-Midaz connector.** Matcher is a stand-alone reconciliation service. It doesn't open a live connection to Midaz, and it has no Midaz-specific configuration. This page explains how the two products work together conceptually.
</Info>

Matcher and [Midaz](/en/midaz) are separate Lerian services with distinct jobs:

* **Midaz** is the ledger — the system of record for balances and postings.
* **Matcher** is the reconciliation engine — it compares two independent datasets and reports what agrees, what doesn't, and why.

They are **complementary, not coupled**. You get value from Midaz-plus-Matcher by reconciling ledger data *against* an external dataset (a bank statement, a gateway settlement report), which is exactly the problem Matcher exists to solve. The data moves between them by **export and import**, not through a real-time link.

## How they fit together

***

A typical Lerian reconciliation flow:

1. **Midaz records postings.** Midaz books transactions in the ledger as usual.
2. **You export the ledger data** for the period you want to reconcile (for example, a day's cash-account entries).
3. **You import that export into Matcher** as one side of a context — a source of type `LEDGER`.
4. **You import the counterparty data** — the bank statement or gateway report — as the other side.
5. **Matcher matches the two sides** using your match rules and surfaces exceptions for review.

Midaz is the origin of one dataset; the bank or gateway is the origin of the other. Matcher never talks to Midaz directly — it works from the exported data you feed it.

## Modeling Midaz as a source

***

Inside a Matcher context, ledger data from Midaz is represented by a source with type `LEDGER`. `LEDGER` is simply Matcher's category for "internal ledger / accounting system" data; it's not a Midaz driver.

```json theme={null}
{
  "name": "Midaz Cash Ledger",
  "type": "LEDGER",
  "side": "LEFT",
  "config": {}
}
```

<Tip>
  API Reference: [Create source](/en/reference/matcher/create-source)
</Tip>

The other side of the context is the external dataset you're reconciling against — usually a `BANK` or `GATEWAY` source on the opposite `side`.

Source types available in Matcher:

| Type      | Meaning                                                  |
| --------- | -------------------------------------------------------- |
| `LEDGER`  | Internal ledger / accounting system (e.g. Midaz exports) |
| `BANK`    | Bank statement feed                                      |
| `GATEWAY` | Payment gateway report                                   |
| `CUSTOM`  | Any other bespoke feed                                   |
| `FETCHER` | Discovery-engine pull                                    |

## Getting ledger data into Matcher

***

Matcher ingests the data you export from Midaz the same way it ingests any other source — there's no Midaz-specific transport.

* **File upload.** Export ledger entries (CSV/JSON) and upload the file to the source. This is the most common path.
* **Discovery-engine query rail.** For sources bound on the `query` rail, Matcher pulls rows through a discovery-engine connection instead of a file. This is a generic ingestion rail, not a Midaz connector.

Either way, you then define a [field map](/en/matcher/configuration/matcher-field-mapping) that renames the exported columns to Matcher's canonical fields (`external_id`, `amount`, `currency`, `date`, and optional `description`, `fee_amount`, `fee_currency`).

<Tip>
  API Reference: [Upload transaction file](/en/reference/matcher/upload-transaction-file)
</Tip>

### Custom field mapping

Most ledger columns map straight across. Field-map lookups are **flat** — a mapping value must name a column that exists at the top level of the exported row, so a value that lives inside transaction metadata must be exported as its own flat column before Matcher can match on it.

For example, Brazil's Pix `endToEndId` is stored in Midaz transaction metadata. To reconcile on it, export it as a flat column (here `endToEndId`) and map a canonical key (here `description`) to that column:

```json theme={null}
{
  "mapping": {
    "external_id": "id",
    "amount": "amount",
    "currency": "asset_code",
    "date": "created_at",
    "description": "endToEndId"
  }
}
```

Every field map must declare all four required canonical keys (`external_id`, `amount`, `currency`, `date`) explicitly — there is no automatic mapping. See [Field mapping](/en/matcher/configuration/matcher-field-mapping) for the full canonical vocabulary.

## Shared platform foundations

***

Although there's no live integration, Matcher is built for the same platform as Midaz and mirrors several of its patterns:

* **Authentication.** Matcher uses the shared Lerian auth stack, so the same identity provider and tokens used across the platform apply.
* **Multi-tenancy.** Matcher follows a pool-per-tenant isolation model (a dedicated database per tenant) in line with the rest of the stack, keeping each tenant's data separate.

These are platform-level commonalities, not a Matcher-to-Midaz data channel.

## What this integration is *not*

***

To avoid confusion with earlier drafts of this page:

* Matcher has **no** `MIDAZ_BASE_URL` or `MIDAZ_GRPC_ADDRESS` setting.
* There is **no** real-time sync mode and **no** `account_filter` for a Midaz source.
* Matcher **doesn't** subscribe to Midaz events or open a gRPC/HTTP connection to Midaz.

Reconciling Midaz data means exporting it and importing it into Matcher like any other source.

## Best practices

***

<AccordionGroup>
  <Accordion title="Export the smallest relevant slice">
    Export only the ledger accounts and period you actually need to reconcile. Smaller, targeted exports keep contexts fast and matching precise.
  </Accordion>

  <Accordion title="Keep export cadence aligned with reconciliation">
    If you reconcile daily, export daily. Match the export schedule to the counterparty data (bank statement) availability.
  </Accordion>

  <Accordion title="Normalize before upload where you can">
    Field maps rename columns but do not transform values. Produce exports whose amounts, dates, and currency codes are already in the shapes your match rules expect.
  </Accordion>

  <Accordion title="Carry references through metadata columns">
    Include stable references (invoice numbers, external IDs) as columns in the export so match rules can key on them for higher match rates.
  </Accordion>
</AccordionGroup>

## Next steps

***

<Card title="External sources" icon="building-columns" href="/en/matcher/integrations/matcher-external-sources" horizontal>
  Connect the bank or gateway side of the reconciliation.
</Card>

<Card title="Field mapping" icon="arrows-left-right" href="/en/matcher/configuration/matcher-field-mapping" horizontal>
  Map exported ledger columns to Matcher's canonical fields.
</Card>