> ## Documentation Index
> Fetch the complete documentation index at: https://iso8583sim.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Version Conversion

> convert_message converts a message between the 1987, 1993 and 2003 versions of ISO 8583.

```python theme={null}
from iso8583sim.core.builder import ISO8583Builder
from iso8583sim.core.convert import convert_message
from iso8583sim.core.parser import ISO8583Parser
from iso8583sim.core.types import ISO8583Version

parsed = ISO8583Parser().parse(raw_1987_message)
result = convert_message(parsed, ISO8583Version.V2003)

raw_2003 = ISO8583Builder(version=ISO8583Version.V2003).build(result.message)

result.notes     # Things worth checking, e.g. fields whose meaning changed
result.dropped   # {field_number: reason} for fields that could not be carried over
result.lossless  # True when nothing was dropped
```

## What changes

| Item | Rule |
| - | - |
| MTI | The first digit is the version: `0` (1987), `1` (1993), `2` (2003). `0200` becomes `1200` or `2200`. |
| Original data elements | Moved from field 90 (1987, fixed 42) to field 56 (2003, LLLVAR) and back, unless the destination field is already set. |
| Other fields | Checked against the target version's definition and kept when they fit. |

## What gets dropped

Fields are dropped, never truncated, and each drop has a reason in `result.dropped`:

* **Field 52 (PIN data)** when the PIN block size differs (8, 16 or 32 bytes). A PIN block can't be padded to a new size. Re-encrypt it for the target version, for example as a format 4 block with `iso8583sim.security.encrypt_pin_block`.
* **Field 53 (security control information)** when its definition differs.
* **Fields 64 and 128 (MAC)**. The MAC covers the whole message, so it must be recomputed after conversion with `ISO8583Builder.build_with_mac`.
* **Values that don't fit**, such as a 60 character field 43 converted to 1987, where field 43 is a fixed 40 characters.
* **Fields not defined** in the target version.

## Notes

Fields 57 to 59 are reserved in 1987 but have defined meanings in 2003 (for example, field 57 is the Authorization Life Cycle Code). Their values are carried over, with a note to check that the value still means the same thing.

A message converted to another version and back reproduces the original exactly, as long as nothing was dropped.

## CLI

```bash theme={null}
iso8583sim convert "0400..." --to 2003
```

See the [CLI reference](../cli#convert).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.