Prerequisites

Before you use Matcher, confirm that you have what this page describes.

Optional: reconciling Midaz data

Matcher pairs with Midaz Ledger, but there is no live connector between them. Matcher opens no connection to Midaz. Reconciling Midaz data is entirely optional. Matcher works as a stand-alone product that reconciles any data sources.

When to reconcile Midaz data

Reconcile ledger data from Midaz if:

You use Midaz as your ledger system
You want to reconcile Midaz postings against external sources (bank statements, gateway reports)

When Midaz is not involved

Matcher works independently when:

Reconciling between external systems (banks, ERPs, payment processors)
Using a different ledger system
Importing ledger data via CSV/JSON/XML files

How it works

Matcher reconciles Midaz data the same way it ingests any source (by import, not a live query):

Export the ledger data for the period you want to reconcile.
Import that export into a Matcher context as a source of type LEDGER.
Import the counterparty data (bank statement or gateway report) as the other side.
Matcher matches the two sides using your match rules.

See the Matcher and Midaz guide for the full flow.

Authentication

Access Manager issues the token and checks the caller’s permissions.

Required permissions

Fine-grained permissions control access to Matcher features:

Permission	Description
`contexts:create`	Create reconciliation contexts
`contexts:read`	View context configuration
`rules:create`	Create match rules
`imports:create`	Upload transaction files
`match-runs:run`	Execute matching jobs
`exceptions:read`	View exceptions
`exceptions:resolve`	Resolve exceptions
`reports:read`	Access reports

Generic import formats

Matcher’s generic importers accept CSV, JSON, and XML. Built-in parsers also support CAMT.053, CNAB 240/400, OFX, several acquirer formats, and receivables formats. See the import format catalog for the complete inventory. Each generic format has specific structural requirements for successful ingestion.

CSV (comma-separated values)

Commonly used for bank statements and exports. Requirements:

The file must have a header row
UTF-8 encoding (configurable)
Comma delimiter (configurable)
Quoted fields for values containing delimiters

Example:

transaction_id,amount,currency,date,reference
TXN-001,1000.00,USD,2024-01-15,Invoice payment
TXN-002,-250.50,USD,2024-01-16,Refund

JSON (javascript object notation)

Recommended for API-based integrations. Requirements:

UTF-8 encoding (configurable)
Consistent field names across records

Example:

[
  {
    "transaction_id": "TXN-001",
    "amount": 1000.0,
    "currency": "USD",
    "date": "2024-01-15",
    "reference": "Invoice payment"
  }
]

XML (extensible markup language)

Common in enterprise and banking integrations. Requirements:

Single root element
UTF-8 encoding (configurable)
Consistent element structure

Example:

<?xml version="1.0" encoding="UTF-8"?>
<transactions>
 <transaction>
 <transaction_id>TXN-001</transaction_id>
 <amount>1000.00</amount>
 <currency>USD</currency>
 <date>2024-01-15</date>
 <reference>Invoice payment</reference>
 </transaction>
</transactions>

File size limits

Limit	Default
Maximum upload file size	1 GiB
Maximum buffered request body	100 MiB

Network requirements

Access to Matcher

Your systems and users reach the Matcher API and the Matcher module of Lerian Console at the addresses Lerian provides.

Access to your systems

For these sources, Matcher connects to the system you name, and that system must accept connections from Matcher:

What you register	What Matcher connects to
Discovery connection	The database or API that the connection names. `GET /v1/discovery/connector-types` lists the available types
Source binding on the `file` rail	The SFTP server, HTTPS endpoint, S3 bucket, or IMAP mailbox

Aggregator connections need your account with Pluggy or Belvo. Event delivery is optional. When Lerian enables it for you, Matcher publishes the events in Matcher events as CloudEvents.

Checklist

Before you start, confirm that:

Credentials are available: you have a token from Access Manager
Network access works: the systems you register accept connections from Matcher
A web browser is available: you use it to open the Matcher module of Lerian Console
Sample data is ready: you have transaction files for your first test (see Quick Start)

Next steps

Quick start

Run your first reconciliation.

Overview

Guides

Console

MCP Server

Operations

Optional: reconciling Midaz data

When to reconcile Midaz data

When Midaz is not involved

How it works

Authentication

Required permissions

Generic import formats

CSV (comma-separated values)

JSON (javascript object notation)

XML (extensible markup language)

File size limits

Network requirements

Access to Matcher

Access to your systems

Checklist

Next steps

Quick start

​Optional: reconciling Midaz data

​When to reconcile Midaz data

​When Midaz is not involved

​How it works

​Authentication

​Required permissions

​Generic import formats

​CSV (comma-separated values)

​JSON (javascript object notation)

​XML (extensible markup language)

​File size limits

​Network requirements

​Access to Matcher

​Access to your systems

​Checklist

​Next steps

Quick start

Optional: reconciling Midaz data

When to reconcile Midaz data

When Midaz is not involved

How it works

Authentication

Required permissions

Generic import formats

CSV (comma-separated values)

JSON (javascript object notation)

XML (extensible markup language)

File size limits

Network requirements

Access to Matcher

Access to your systems

Checklist

Next steps