SEPA pain.001 validator — free API, CLI, and MCP server

Client tools for the free, keyless validator at checksepa.com. Send one SEPA credit-transfer XML file (ISO 20022 pain.001.001.03 or pain.001.001.09) and get structure and EPC findings back.

This repository is only the public client: CLI, MCP server, OpenAPI copy, samples, and examples. It does not contain the validator engine.

The file is uploaded to POST https://checksepa.com/v1/validate for that request. The service does not store it.

Free limits

Higher limits and API keys: waitlist (joining is free; planned from EUR 79/month, charged only after confirmation). Docs: https://checksepa.com/docs. Machine-readable contract: openapi.json (copy in openapi/openapi.json).

A file can pass here and still be rejected by a bank. Bank implementation guidelines are out of scope. This is not a bank login, EBICS client, Verification of Payee check, or payment initiation.

pain.008 and camt messages are recognised (format and version) and returned with valid: false. They are not rule-checked yet.

Related MCP server: eleata e-invoice MCP server

curl

Using the published valid sample:

curl -F "file=@samples/valid-pain001-001-03.xml" https://checksepa.com/v1/validate

Raw XML body:

curl -X POST https://checksepa.com/v1/validate \
  -H "Content-Type: application/xml" \
  --data-binary @samples/valid-pain001-001-09.xml

examples/curl.sh wraps the multipart request.

Sample request and response

curl -F "file=@samples/invalid-pain001-001-03.xml" https://checksepa.com/v1/validate

The invalid sample is published as failing. The report has seven errors. The first one:

{
  "valid": false,
  "format": "pain.001",
  "version": "pain.001.001.03",
  "errors": [
    {
      "code": "EPC-CTRLSUM",
      "message": "CtrlSum is 999.00 but the transactions sum to 175.50.",
      "path": "/Document/CstmrCdtTrfInitn/GrpHdr/CtrlSum",
      "line": 8
    }
  ],
  "warnings": []
}

valid: true means the file passed the free baseline. errors and warnings use code, message, path, and line. line is 1-based, or null when the parser cannot place the finding.

Samples

Copied from the checksepa.com sample set. Synthetic data and dummy IBANs, not real payments.

CLI

Python 3.9+, package sepa-check. The only dependency is requests.

pip install ./cli
sepa-check samples/valid-pain001-001-03.xml
sepa-check samples/invalid-pain001-001-03.xml --json

Node 18+, package sepa-check, no dependencies:

npx ./cli-node samples/valid-pain001-001-03.xml
node cli-node/bin/sepa-check.js samples/invalid-pain001-001-03.xml --json

Human output prints each finding with its code, path, and line. --json prints the report. Exit 0 when valid is true, 1 when the file fails, 2 on usage, file, or HTTP errors (including 413 and 429).

After publish, the same commands are pip install sepa-check and npx sepa-check file.xml. They are not on PyPI or npm yet. Names checked on 19 October 2026: sepa-check was unused on both registries, and sepa-validator-mcp was unused on npm. See Publishing.

MCP server

mcp/ is a stdio MCP server, package sepa-validator-mcp. It exposes one tool, validate_sepa, with file_path or xml. The result is valid, format, version, errors[], and warnings[].

Registry metadata is in mcp/server.json (io.github.wenboteng/sepa-validator). Config snippets for Claude Desktop, Cursor, and VS Code are in mcp/README.md. Not submitted to the MCP registry yet.

Examples

Short snippets that post the file field. Each run spends one free validation.

Links

• Docs: https://checksepa.com/docs

• OpenAPI: https://checksepa.com/openapi.json

• API waitlist: https://checksepa.com/api-waitlist

• Samples on the site: https://checksepa.com/samples

Deutsch

Kostenlose Client-Werkzeuge für die Prüfung von SEPA-Überweisungen (ISO 20022 pain.001.001.03 und pain.001.001.09) auf checksepa.com. Kein API-Schlüssel. Dieses Repository enthält nur Clients, Beispiele und die öffentliche OpenAPI-Datei, nicht die Validator-Engine.

Die Datei geht an POST https://checksepa.com/v1/validate und wird für diese eine Anfrage geprüft. Sie wird nicht gespeichert.

Grenzen: 30 Prüfungen pro IP und Stunde, 200 pro IP und UTC-Tag, maximal 2 MB. Darüber HTTP 429 mit Retry-After, bei mehr als 2 MB HTTP 413. Höhere Limits und API-Schlüssel über die Warteliste (ab 79 €/Monat geplant, Zahlung erst nach Bestätigung).

curl -F "file=@samples/valid-pain001-001-03.xml" https://checksepa.com/v1/validate

Die Beispieldateien unter samples/ sind synthetisch, mit Dummy-IBANs: gültige pain.001.001.03, gültige pain.001.001.09, und eine ungültige pain.001.001.03 (unter anderem EPC-CTRLSUM und EPC-IBAN).

Antwortfelder: valid, format (zum Beispiel pain.001), version (zum Beispiel pain.001.001.03), errors[] und warnings[]. Jeder Fund hat code, message, path und line.

CLI: sepa-check datei.xml (Python) oder npx sepa-check datei.xml (Node, nach Veröffentlichung). Exit-Code 0 bei gültig, 1 bei ungültig, 2 bei Aufruf- oder HTTP-Fehler. --json gibt den Bericht aus.

pain.008 und camt werden erkannt und mit valid: false zurückgegeben. Sie werden noch nicht regelgeprüft. Eine bestandene Datei kann von der Bank trotzdem abgelehnt werden (bankeigene MIG). Kein Bank-Login, kein EBICS, keine Zahlungsauslösung.

Links: API-Doku, OpenAPI, Warteliste.

Development

GitHub Actions lints the Python and Node clients, typechecks the MCP server, boots it over stdio, and runs live checks of the published samples. Those live checks skip when checksepa.com:443 cannot be reached.

python -m pip install ./cli
python -m unittest discover -s tests -p 'test_*.py' -v
node --test cli-node/test/*.test.js
cd mcp && npm ci && npm run build && node --test test/*.test.js && node scripts/stdio-smoke.mjs

node mcp/scripts/stdio-smoke.mjs samples/valid-pain001-001-03.xml performs one extra live tool call. Do not loop it: the free quota is 30 per IP per hour.

Publishing

Nothing in this repo is on npm, PyPI, or the MCP registry. Names checked on 19 October 2026 while preparing this tree: sepa-check (PyPI and npm) and sepa-validator-mcp (npm) were unused (registry 404). Do not publish from CI. Do not publish from this checkout unless you mean to.

PyPI, from a machine logged in via ~/.pypirc or an API token:

cd cli
python -m pip install build twine
python -m build
python -m twine upload dist/*

npm CLI (unscoped package, public by default):

cd cli-node
npm login
npm publish

npm MCP server. npm publish runs prepack, which compiles TypeScript. Publish this package before the registry entry, because the registry checks mcpName in the published package.json.

cd mcp
npm login
npm publish

MCP registry, only after that npm publish. Use the official mcp-publisher binary from modelcontextprotocol/registry, not the unrelated npm package named mcp-publisher.

curl -L "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher
sudo mv mcp-publisher /usr/local/bin/
cd mcp
mcp-publisher validate server.json
mcp-publisher login github
mcp-publisher publish

The metadata points at https://github.com/wenboteng/sepa-validator. That remote is not created by this tree.

License

MIT. Copyright (c) 2026 Bobook Limited. See LICENSE.

The API is operated by Bobook Limited. Contact published on the service: info@bobook.club.