Prerequisites

Node.js 20.x (LTS). Use nvm from the service repo root: nvm use (reads .nvmrc) before npm commands.
Docker and Docker Compose — For PostgreSQL, Redis, LedgerMatch, Keycloak
Embeddings — LedgerMatch needs embeddings:
- Ollama (default in Docker) — No API key. docker-compose pulls mxbai-embed-large.
- OpenAI — Set OPENAI_API_KEY in .env and EMBEDDING_PROVIDER=openai for LedgerMatch.

Option A: Full Docker (recommended)

# Copy env and add OPENAI_API_KEY only if using OpenAI (not Ollama)
cp .env.example .env

# Start all services (API, DB, Redis, LedgerMatch, Keycloak, Ollama)
docker-compose up --build

# API runs at http://localhost:8000
# Swagger: http://localhost:8000/api/docs

The payment-reconciler container runs migrations, Keycloak realm setup, seed, and npm run start:dev. No local npm install needed.

Option B: Hybrid (Docker for deps, local API)

Useful when you want to edit code and run tests locally:

# 1. Start only dependencies (comment out payment-reconciler in docker-compose or use a separate compose file)
docker-compose up -d payment-reconciler-db ledger-match-db redis keycloak keycloak-db ollama ledger-match

# 2. Copy env and set DATABASE_URL for host (localhost:5433), REDIS_URL (localhost:6379)
cp .env.example .env

# 3. Install and run
npm install
npm run prisma:generate
npm run prisma:migrate
npm run keycloak:setup-realm   # Optional
npm run prisma:seed            # Optional
npm run start:dev

EBICS and Node.js version

The service targets Node 20 everywhere (.nvmrc, CI, Docker) with node --security-revert=CVE-2023-46809 so EBICS (ebics-client, RSA PKCS#1 v1.5) works. Node 22+ does not accept that revert flag. See the repository root README, section EBICS and Node.js.

Environment variables

Variable	Required	Description
DATABASE_URL	Yes	PostgreSQL connection (e.g. `postgresql://postgres:postgres@localhost:5433/paymentreconciler`)
REDIS_URL	Yes	Redis for BullMQ and cache
LEDGER_MATCH_API_URL	Yes	LedgerMatch REST URL (e.g. `http://localhost:9000`)
JWT_SECRET	Yes	JWT signing secret (dev: use any string)
AUTH_MODE	No	`keycloak` (typical dev/prod), `both`, or other values — see `.env.example` / README
OPENAI_API_KEY	When using OpenAI	For LedgerMatch embeddings. Required only if `EMBEDDING_PROVIDER=openai`
KEYCLOAK_URL	When AUTH_MODE=keycloak	Keycloak base URL
KEYCLOAK_REALM	No	Default: `sequel`
KEYCLOAK_CLIENT_ID	No	Default: `payment-reconciler-client`
PORT	No	API port (default: 8000)
LOG_LEVEL	No	`info`, `debug`, etc.
CACHE_ENABLED	No	Enable Redis cache (default: true)

See .env.example for the full list. For LedgerMatch-specific vars (timeout, retry, circuit breaker), see the LedgerMatch service docs.

Useful commands

Command	Purpose
`npm run prisma:studio`	Open Prisma Studio to inspect DB
`npm run prisma:migrate`	Run migrations (dev)
`npm run prisma:migrate:deploy`	Run migrations (prod/deploy)
`npm run prisma:seed`	Seed initial data
`npm run keycloak:setup-realm`	Configure Keycloak realm and client
`npm run start:dev`	Start API with watch
`npm test`	Unit tests
`npm run test:e2e`	E2E tests (requires Redis + PostgreSQL)

Swagger and health

Swagger UI — http://localhost:8000/api/docs
Health — http://localhost:8000/api/health
LedgerMatch health — http://localhost:8000/api/health/ledger-match

Next steps

Authentication — How to get a token and call the API
Tenants — Create tenants and environments
Reconciliation — Reconciliation flow

Development Environment