pain001-loader-mt101: MT101 → pain.001 loader

Convert legacy SWIFT MT101 requests for transfer into the flat records that the pain001 library validates and turns into ISO 20022 pain.001 XML. A single parse_mt101(text) call returns a list[dict] — one record per transaction — ready to feed straight into pain.001 generation.

Latest release: v0.0.2. The second deliverable of the MT→MX converter project (after pacs008-loader-mt103). SWIFT MT-MX coexistence ends in November 2025; this loader bridges the window where upstream systems still emit MT101 but downstream tooling expects pain.001.

Contents

• Overview
• Install
• Quick Start
• Field Mapping
• Assumptions and defaults
• Out of scope
• Examples
• Development
• Security
• License

Overview

pain001-loader-mt101 is a small, focused companion to the pain001 ISO 20022 Customer Credit Transfer Initiation library. It does one thing well: parse the mandatory + common-denominator MT101 grammar and hand back flat records whose keys are exactly the ones pain001 validates against the pain.001.001.09 JSON schema. Unlike an MT103 (one transfer), an MT101 can carry many transactions (repeating sequence B), so parse_mt101 returns one record per transaction. The correctness proof is that a realistic multi-transaction MT101 maps to records that pass SchemaValidator("pain.001.001.09").validate_batch(...) with zero errors.

Install

pain001-loader-mt101 requires Python 3.10+ and pulls in pain001 automatically.

pip install pain001-loader-mt101

Quick Start

from pain001_loader_mt101 import parse_mt101

mt101 = """:20:MSGREF2026070901
:21R:CUSTREF-A
:50H:/DE89370400440532013000
GLOBAL IMPORTS GMBH
100 HAFEN STRASSE
HAMBURG
:52A:DEUTDEFF
:30:260712
:21:TXN-REF-0001
:32B:EUR12345,67
:57A:CHASUS33
:59:/GB29NWBK60161331926819
ACME TRADING LTD
1 CORPORATE AVENUE
LONDON
:70:INVOICE 998877
:71A:SHA
:21:TXN-REF-0002
:32B:USD5000,00
:57A:BOFAUS3N
:59:/FR1420041010050500013M02606
LES FLEURS SARL
:70:CONTRACT 445566
:71A:OUR
"""

records = parse_mt101(mt101)
print(len(records))                       # 2
print(records[0]["payment_amount"])       # 12345.67
print(records[0]["charge_bearer"])        # SHAR
print(records[0]["nb_of_txs"])            # 2 (message-level)

# Validate against the real pain.001 schema:
from pain001.validation.schema_validator import SchemaValidator
total, valid, errors = SchemaValidator("pain.001.001.09").validate_batch(records)
assert valid == total and not errors

Field Mapping

parse_mt101(text: str) -> list[dict] — one record per sequence-B transaction. Sequence-A :50a: / :52a: apply to every transaction unless a sequence-B block overrides them.

Assumptions and defaults

The pain.001 schema requires fields MT101 does not carry; these are synthesised (override downstream as needed):

• payment_method = "TRF" — an MT101 requests credit transfers.
• batch_booking = False.
• service_level_code = "SEPA" — the schema enum admits only SEPA / URNS; override for non-SEPA payments.
• charge_bearer = "SLEV" when :71A: is absent or unrecognised — the schema requires a charge bearer.
• remittance_information = "NOTPROVIDED" when :70: is absent — the schema requires a non-empty value.
• nb_of_txs / ctrl_sum describe the whole message (count of and total over sequence-B blocks) and are repeated on every record, as in a pain.001 group header.
• date (message creation date) reuses :30: — MT101 has no separate creation timestamp. Two-digit years follow the SWIFT sliding window (00–79 → 20YY, 80–99 → 19YY).
• initiator_name reuses the ordering-customer name.
• Absent optional fields are omitted, not guessed. A schema-valid pain.001 record needs the ordering-customer name + IBAN (:50a:), the account-servicing and account-with BICs (:52a: / :57a:) and the beneficiary IBAN (:59a:); a well-formed MT101 carries all of these.
• Hard requirements — only :20:, :30:, at least one transaction, and per transaction :21:, :32B: and a named beneficiary (:59:/:59A:/:59F:) raise ValueError. Everything else is best-effort; the loader never crashes on unexpected input.

Out of scope

This is the correct core MT101 → pain.001 mapping, not every optional field. Deliberately excluded in v0.0.2:

• :23E: instruction codes, :25: / :28D: authorisation / sequence fields.
• :33B: instructed currency/amount, :36: exchange rate, :21F: FX deal reference (FX legs).
• :56a: intermediary and :51A: sending institutions.
• :77B: regulatory reporting and :25A: charges account.
• The SWIFT application header (blocks 1/2). This loader reads block 4 only (it unwraps a {4:...-} envelope if present).

Examples

Two runnable scripts live in examples/, exercised in CI:

• 01_minimal_parse.py — parse and print the flat records.
• 02_validate_against_pain001.py — parse, then validate against the real pain.001.001.09 schema.

Development

git clone https://github.com/sebastienrousseau/pain001-loader-mt101
cd pain001-loader-mt101
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest                            # 100% line + branch coverage gate
interrogate pain001_loader_mt101  # 100% docstring gate
mypy pain001_loader_mt101         # strict

Security

pain001-loader-mt101 parses a flat text format with no XML envelope — the XXE / billion-laughs surface lives upstream. Field regexes are anchored and bounded, so catastrophic backtracking is not a concern. See SECURITY.md.

License

Licensed under the Apache License, Version 2.0. Any contribution submitted for inclusion shall be licensed as above, without additional terms.