> ## 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/products/midaz/what-is-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). 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 Matcher's category for "internal ledger / accounting system" data. It is not a Midaz driver.

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

<Tip>
  API Reference: [Create source](/en/reference/products/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/products/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/products/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 `external_id` to that column. `external_id` is the reference the matching engine compares across sources, so both sides of the context must map it to a value they share (the `description` key is display-only and never feeds matching):

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

Every field map must declare all four required canonical keys (`external_id`, `amount`, `currency`, `date`) explicitly. No automatic mapping happens. See [Field mapping](/en/products/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*

***

* 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/products/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/products/matcher/configuration/matcher-field-mapping" horizontal>
  Map exported ledger columns to Matcher's canonical fields.
</Card>