pain001-loader-mt101 v0.0.70 parses legacy SWIFT MT101 (Request for Transfer) messages into flat records that pass pain.001.001.09 validation. One function, zero third-party dependencies, 100% branch-covered.
Swift ended MT payment instructions (MT103, MT202) for cross-border payments in November 2025, and plans to move interbank MT101 to pain.001 too, a change it deferred in August 2026. Treasury systems, however, still hold years of MT101 templates, archives, and file-based bank integrations. This loader is the bridge: parse the MT, regenerate as MX, validate against the official XSD, move on.
New to the migration? Start with MT101 to pain.001: the migration path, which explains the case and the three steps before this reference.
01. One function#
= # one dict per Sequence B transaction
The output is shaped for pain.001.001.09 and passes the core library's SchemaValidator unchanged. The MCP server exposes the same capability to AI agents as the convert_mt101 tool.
02. Field mapping reference#
| MT101 tag | Meaning | pain.001 field |
|---|---|---|
:20: (Seq A) | Sender's reference | id, payment_information_id |
:30: (Seq A) | Requested execution date (YYMMDD) | date, requested_execution_date |
:21: (Seq B) | Transaction reference | payment_id |
:32B: | Currency + amount | currency, payment_amount |
:50H: :50G: :50F: :50K: :50A: :50: | Ordering customer | debtor_name, debtor_account_IBAN, initiator_name |
:52A: :52C: :52D: | Account servicing institution | debtor_agent_BIC |
:57A: :57C: :57D: (Seq B) | Account with institution | creditor_agent_BIC |
:59: :59A: :59F: (Seq B) | Beneficiary | creditor_name, creditor_account_IBAN |
:70: | Remittance information | remittance_information (truncated to 140 chars) |
:71A: | Details of charges | charge_bearer (OUR→DEBT, BEN→CRED, SHA→SHAR) |
Party tags set in Sequence B override their Sequence A defaults, matching MT101 semantics. A raw {4:...-} block-4 envelope is unwrapped automatically; block 1/2/3 headers are ignored. Control fields are synthesised: nb_of_txs from the Sequence B count, ctrl_sum from the transaction amounts, payment_method fixed to TRF.
Deliberately out of scope: :23E:, :25:, :28D:, :33B:, :36:, :21F:, :56a:, :51A:, :77B:, :25A:. Instruction codes, FX and intermediary routing need human judgement; the loader refuses to guess.
03. Strict where it counts#
Malformed input raises ValueError with a precise message rather than emitting a half-converted file: missing :20: or :30:, no Sequence B transactions, a transaction without :21: or :32B:, or an unnamed beneficiary all stop the conversion. Amounts are re-validated and control sums recomputed downstream by the core library's decimal.Decimal pipeline before any XML is written.
FAQ#
Is MT101 actually decommissioned?
The many-to-one relay use of MT101 on SWIFT FIN follows the same retirement path as the rest of the MT payment category; corporate-to-bank channels (SCORE) retain MT for longer, at each bank's discretion. Either way, every receiving bank is now MX-native, so regenerating legacy instructions as validated pain.001 removes a translation dependency you no longer control. See the 2026 migration briefing.
Why records instead of direct XML?
Because conversion without validation is how malformed files reach banks. Records flow through the same JSON Schema → scheme rulebook → XSD pipeline as every other Pain001 input. The XML you get is provably valid, not merely translated.
Install: