Prerequisites

Before deploying Matcher, ensure that your environment meets the requirements described on this page. These prerequisites define the baseline for running reconciliation reliably in development and production environments.

System requirements

Infrastructure

Component	Minimum / recommended	Purpose
CPU	2 cores / 4+ cores	Matching and scoring logic is CPU-intensive
Memory	2 GB / 4+ GB	In-memory processing of transaction batches
Storage	10 GB / 50+ GB	Persistent storage for transactions and audit logs

Dependencies

Matcher depends on the following services:

PostgreSQL 15+: Primary data store for reconciliation contexts, transactions, matches, and audit logs.
Redis 7+: Used for caching, duplicate detection, distributed locking, and idempotency control.
RabbitMQ 3.12+: Message broker for asynchronous processing across bounded contexts.

Runtime

Matcher supports the following runtimes and tooling:

Go 1.26+ (only required when building from source)
Docker 24+ and Docker Compose 2.20+ for containerized deployments
Kubernetes 1.28+ for production-grade deployments using Helm

Optional: reconciling Midaz data

Matcher pairs naturally with Midaz Ledger, but there is no live connector between them — Matcher has no MIDAZ_API_URL and opens no connection to Midaz. Reconciling Midaz data is entirely optional; Matcher works as a stand-alone product reconciling 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

Matcher uses lib-auth for authentication and authorization, consistent with the rest of the Lerian ecosystem.

Authentication flow

The client obtains a JWT from the identity provider
The token is sent in the Authorization: Bearer <token> header
Matcher validates the token via lib-auth
Tenant identity and permissions are extracted from token claims

Required permissions

Access to Matcher features is controlled through fine-grained permissions:

Permission	Description
`contexts:create`	Create reconciliation contexts
`contexts:read`	View context configuration
`rules:create`	Create and update 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 and audit views

Single-tenant mode

If authentication is disabled or no tenant identifier is present in the JWT, Matcher runs in single-tenant mode using a default tenant.

# Default tenant configuration (single-tenant mode)
DEFAULT_TENANT_ID=11111111-1111-1111-1111-111111111111
DEFAULT_TENANT_SLUG=default

Supported file formats

Matcher accepts transaction data in the following formats. Each format has specific structural requirements for successful ingestion.

CSV (comma-separated values)

Commonly used for bank statements and exports. Requirements:

Header row is required
UTF-8 encoding
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:

Valid JSON array of transaction objects
UTF-8 encoding
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
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	Configurable via
Maximum upload file size	1 GiB	`INGESTION_MAX_UPLOAD_BYTES` (streaming upload route)
Maximum buffered request body	100 MiB	`HTTP_BODY_LIMIT_BYTES` (non-upload requests)
Maximum transactions per file	100,000	Context-level configuration

Network requirements

Inbound access

Matcher exposes a REST API that must be reachable by clients:

Port	Protocol	Purpose
4018	HTTP/HTTPS	API server (default `:4018`; serves HTTPS when TLS is configured)

Outbound access

Matcher must be able to reach the following services:

Service	Purpose	Required
PostgreSQL	Data persistence	Yes
Redis	Caching and coordination	Yes
RabbitMQ	Messaging	Yes
Auth service	Token validation	If authentication is enabled
JIRA / ServiceNow	Exception routing	Optional
Custom webhooks	Event notifications	Optional

TLS configuration

For production environments, configure TLS:

SERVER_TLS_CERT_FILE=/path/to/cert.pem
SERVER_TLS_KEY_FILE=/path/to/key.pem

Environment checklist

Before proceeding with installation, confirm that:

Infrastructure is ready: PostgreSQL, Redis, and RabbitMQ are running and accessible
Authentication is configured: Auth service is available, or auth is explicitly disabled
Network access is validated: Required inbound and outbound connectivity is in place
Credentials are available: Database credentials and API tokens are configured
Sample data is prepared: Transaction files are ready for testing (see Quick Start)

Overview

Guides

Matcher UI

MCP Server

Operations

System requirements

Infrastructure

Dependencies

Runtime

Optional: reconciling Midaz data

When to reconcile Midaz data

When Midaz is not involved

How it works

Authentication

Authentication flow

Required permissions

Single-tenant mode

Supported file formats

CSV (comma-separated values)

JSON (javascript object notation)

XML (extensible markup language)

File size limits

Network requirements

Inbound access

Outbound access

TLS configuration

Environment checklist

Next steps

Installation

Quick start

​System requirements

​Infrastructure

​Dependencies

​Runtime

​Optional: reconciling Midaz data

​When to reconcile Midaz data

​When Midaz is not involved

​How it works

​Authentication

​Authentication flow

​Required permissions

​Single-tenant mode

​Supported file formats

​CSV (comma-separated values)

​JSON (javascript object notation)

​XML (extensible markup language)

​File size limits

​Network requirements

​Inbound access

​Outbound access

​TLS configuration

​Environment checklist

​Next steps

Installation

Quick start

System requirements

Infrastructure

Dependencies

Runtime

Optional: reconciling Midaz data

When to reconcile Midaz data

When Midaz is not involved

How it works

Authentication

Authentication flow

Required permissions

Single-tenant mode

Supported file formats

CSV (comma-separated values)

JSON (javascript object notation)

XML (extensible markup language)

File size limits

Network requirements

Inbound access

Outbound access

TLS configuration

Environment checklist

Next steps