Message Families

What a family is

A family is a set of message formats that describe the same kind of business event. An MT103 and a pacs.008 are both a customer credit transfer, so they share the payment family; an MT940 and a camt.053 are both an account statement, so they share the statement family.

Inside the engine every family has one canonical model: a format-neutral JSON shape that every member parses into and renders out of. A conversion is always two steps, source to canonical and canonical to target, and it only exists when both formats belong to the same family. The canonical shape is what /v1/normalize returns, so the result.type of a normalize response tells you which model a message lives in.

Terms used on these pages:

The families

The live list of formats, versions and pairs is always GET /v1/formats; the tables on these pages describe the behaviour behind those pairs.

Why pairs never cross families

Some families share a canonical model (FI transfers and customer payments are both payment; queries, answers and cancellation requests are all investigation), yet transmute never converts between them. A message type carries meaning, not just fields: a return is not a new payment, a bank-to-bank cover transfer is not a customer transfer, and a query is not a request to cancel. Converting across that line would produce a well-formed message that says something different from the source.

So these pairs do not exist, and asking for one returns unsupported-conversion (422):

• mt202 → pacs.008 or mt103 → pacs.009 (FI transfer vs. customer payment)
• mt103-retn → pacs.002 or mt103-rejt → pacs.004 (a return is not a reject)
• mt101 → pain.008 or mt104 → pain.001 (a credit transfer is not a direct debit)
• mt210 → camt.053 (a notice is not a statement)
• mt195 → camt.111 (a query is not an answer)

Within a family, conversions change the syntax (MT to MX or MX to MT). Two MT formats of one family never convert to each other (mt202 → mt205 is not a pair). A few MX-to-MX pairs exist where they serve a real purpose: re-rendering or upgrading a camt statement, bridging pain.001 versions, and forwarding a customer cancellation (camt.055 → camt.056).

The same rule applies to canonical JSON input: a canonical document of one family sent to another family's target, such as a statement document with to=mt103 or a credit-transfer initiation with to=pain.008, is a 422 unsupported-conversion.

Normalize-only formats

Four formats parse, normalize and validate but take part in no conversion: mt199, mt299, camt.029, and pain.002 when it is the source. Each one either has no structured counterpart (free-format text) or carries content that no other format in its family can hold faithfully. Naming one as from on /v1/convert returns 422 unsupported-conversion. See Normalize-only formats.

pain.002 is the one asymmetry: you cannot convert from it, but transmute can generate one from a canonical status document (see Rejects and status reports).

How to read a family page

Every family page follows the same layout:

1. Formats: each format id, the MX versions accepted as input, and the version emitted by default. Pin another output version with targetVersion where the page lists more than one.
2. Pairs: every registered from → to in the family, both directions.
3. How fields map: a plain-language summary of where the key fields go, in each direction.
4. Where information is lost: the situations that produce a lossy or defaulted step, and the warning code each one emits.
5. Conventions: family-specific rules worth knowing before you build on the output.
6. Example: one runnable curl with synthetic data and the shape of the response.

All examples post raw MT text with Content-Type: text/plain and let transmute detect the source (meta.detectedType). Each response is abbreviated: XML is shown formatted, and warning detail strings are elided.

Detecting sibling MT types

Several MT types share their field layout with a sibling and differ only in the message type in the FIN header (block 2). Without the {1:}{2:} header, transmute cannot tell them apart:

When the distinction matters, send the full FIN envelope or name the format with from.