MT to MX migration checklist

Use this list when a counterparty or market infrastructure asks you to send or receive ISO 20022 instead of (or alongside) MT. Each step names the request option that implements it.

Measured on: transmute main at commit f460e0e (7 October 2026). The pair list and versions below come from GET /v1/formats on that build; re-run it any time, because the live registry is the source of truth.

1. Inventory your MT traffic against the registry

List the MT types you send and receive, then check each against the registry:

curl -sS https://api.transmute.403fin.io/v1/formats -H "Authorization: Bearer $TRANSMUTE_KEY" \
  | jq -r '.formats as $f | .formats[] | select(.kind=="mt") | . as $s
      | "\($s.id) -> \([$s.convertsTo[] | select(. as $t | $f | any(.id==$t and .kind=="mx"))] | join(", "))"'

At f460e0e that prints 20 MT sources with 30 MT → MX directions (and 30 in the reverse direction):

A type that is not in the list is not supported; POST /v1/convert answers unsupported-conversion rather than guessing.

2. Pick the target message version

Each MX family lists its versions in the registry (versions). Where a family has more than one, the default at f460e0e is the newest (camt.05x.001.08, pain.001.001.09; the response's meta.targetType always names the version produced); pin another with toVersion (raw bodies: ?toVersion=; JSON: options.targetVersion).

Agree the version with your counterparty first; the default is not a recommendation for your market.

3. Decide on the envelope

By default the response is the business Document only. If your channel expects a Business Application Header, send envelope=apphdr: transmute builds a head.001.001.02 AppHdr from the MT's FIN blocks 1–3 (sender, receiver, :20: reference) and returns it before the Document, as two top-level elements. A source without sender and receiver BICs (FIN blocks 1 and 2) is rejected with invalid-input. Envelope components the AppHdr cannot hold are reported as ENVELOPE_DROPPED.

4. Pin the Standards Release

Pin srVersion (or X-Api-Version) in production so output never moves under you between releases, and test the next release on a test key before it becomes the default. See Migrating from SR2025 to SR2026 for what SR2026 changes (structured postal addresses in MT101/MT103 ↔ pain.001/pacs.008) and the planned default change with the 14 November 2026 release.

5. Read every warning

Every assumption or loss is a structured warning with a stable code from the warning registry, sorted deterministically. Treat them by severity:

For a whole flow, a response without lossy warnings means nothing was dropped. Set options.strict to turn lossy mappings into errors (and, for MT targets, characters outside the SWIFT X character set into a charset error instead of transliteration).

6. Validate what you send

Validate the MX you produce before it leaves you: POST /v1/validate with level=schema (the default) or, for MX, a usage-guideline level layered on schema — cbpr, hvps, fedwire, sepa or cgi, whichever your counterparty's market follows. While you still send MT, level=network checks MT cross-field rules. Levels beyond syntax and schema are deployment features; GET /v1/formats lists the ones yours serves as validationLevels (see Validate). Validation follows the same srVersion as conversion.

7. Run in parallel, then cut over

1. Run the conversion alongside your existing MT flow for a full statement cycle and compare totals: opening and closing balances, entry counts and amounts (amounts are decimal strings in every response, never floats).
2. Keep a sample of converted messages and their warnings for your own audit trail — transmute keeps no message content once the response is sent.
3. Use Idempotency-Key on retries, and Batch for volume.
4. Cut over per counterparty, not all at once.

"SWIFT" is a trademark of S.W.I.F.T. SCRL. transmute converts SWIFT MT messages; it is not affiliated with, endorsed by, or certified by SWIFT.