# MISO20022 Python Library
This package provides a set of tools for generating and working with ISO 20022 financial messages, with a focus on the US Payment Rails.
## Installation
You can install the package from PyPI:
```bash
pip install miso20022
```
## Usage Examples
This section provides detailed examples for the core functionalities of the library.
**Index:**
- [Generating a `pacs.008.001.08` (Customer Credit Transfer) Message](#generating-a-pacs00800108-customer-credit-transfer-message)
- [Generating a `pacs.028.001.03` (Payment Status Request) Message](#generating-a-pacs02800103-payment-status-request-message)
- [Parsing a `pacs.008.001.08` XML to JSON](#parsing-a-pacs00800108-xml-to-json)
- [Parsing a `pacs.002.001.10` (Payment Status Report) XML to JSON](#parsing-a-pacs00200110-payment-status-report-xml-to-json)
---
### Input JSON Structure
The `generate_fedwire_message` function expects a specific JSON structure for the `payload` argument. Below are the expected formats for the supported message types.
#### `pacs.008.001.08` (Customer Credit Transfer)
The payload for a `pacs.008` message should follow this structure:
```json
{
"fedWireMessage": {
"inputMessageAccountabilityData": {
"inputCycleDate": "20250109",
"inputSource": "MBANQ",
"inputSequenceNumber": "001000001"
},
"amount": {
"amount": "1000"
},
"senderDepositoryInstitution": {
"senderABANumber": "<routing_number>",
"senderShortName": "Pypi Bank"
},
"receiverDepositoryInstitution": {
"receiverABANumber": "<routing_number>",
"receiverShortName": "HelloBank"
},
"originator": {
"personal": {
"name": "JANE SMITH",
"address": {
"addressLineOne": "456 eat street",
"addressLineTwo": "SOMEWHERE, CA 67890",
"addressLineThree": ""
},
"identifier": "<account_number>"
}
},
"beneficiary": {
"personal": {
"name": "JOHN DOE",
"address": {
"addressLineOne": "123 Main street",
"addressLineTwo": "ANYTOWN, TX 12345",
"addressLineThree": ""
},
"identifier": "<account_number>"
}
}
}
}
```
#### `pacs.028.001.03` (Payment Status Request)
The payload for a `pacs.028` message should follow this structure:
```json
{
"fedWireMessage": {
"inputMessageAccountabilityData": {
"inputCycleDate": "20250109",
"inputSource": "MBANQ",
"inputSequenceNumber": "001000002"
},
"senderDepositoryInstitution": {
"senderABANumber": "<routing_number>",
"senderShortName": "<short_name>"
},
"receiverDepositoryInstitution": {
"receiverABANumber": "<routing_number>",
"receiverShortName": "<short_name>"
}
},
"message_id": "PACS028REQ20250109001",
"original_msg_id": "20250109MBANQ001000001",
"original_msg_nm_id": "pacs.008.001.08",
"original_creation_datetime": "2025-01-09T12:34:56Z",
"original_end_to_end_id": "MEtoEIDCJShqZKb"
}
```
### Generating a `pacs.008.001.08` (Customer Credit Transfer) Message
This example shows how to generate a Fedwire `pacs.008` message from a JSON payload.
```python
import json
from miso20022.fedwire import generate_fedwire_message
# 1. Load your payment data from a JSON object
with open('sample_files/sample_payload.json', 'r') as f:
payload = json.load(f)
# 2. Define the necessary message parameters
message_code = 'urn:iso:std:iso:20022:tech:xsd:pacs.008.001.08'
environment = "TEST" # Or "PROD"
fed_aba = '000000008' # The ABA number for the Fed
xsd_path = 'proprietary_fed_file.xsd' # The XSD file for fedwire format
# 3. Generate the complete XML message
_, _, complete_message = generate_fedwire_message(
message_code=message_code,
environment=environment,
fed_aba=fed_aba,
payload=payload,
xsd_path=xsd_path
)
# 4. The `complete_message` variable now holds the XML string
if complete_message:
print(complete_message)
```
### Generating a `pacs.028.001.03` (Payment Status Request) Message
This example shows how to generate a `pacs.028` payment status request.
```python
import json
from miso20022.fedwire import generate_fedwire_message
# 1. Load the payload for the status request
with open('sample_files/sample_pacs028_payload.json', 'r') as f:
payload = json.load(f)
# 2. Define message parameters
message_code = 'urn:iso:std:iso:20022:tech:xsd:pacs.028.001.03'
environment = "TEST" # Or "PROD"
fed_aba = '000000008'
xsd_path = 'proprietary_fed_file.xsd'
# 3. Generate the XML message
_, _, complete_message = generate_fedwire_message(
message_code=message_code,
environment=environment,
fed_aba=fed_aba,
payload=payload,
xsd_path=xsd_path
)
# 4. The `complete_message` variable now holds the XML string
if complete_message:
print(complete_message)
```
### Parsing a `pacs.008.001.08` XML to JSON
This example shows how to parse a `pacs.008` XML file and convert it into a simplified JSON object.
```python
from miso20022.fedwire import generate_fedwire_payload
import json
# 1. Define the path to your XML file and the message code
xml_file = 'incoming_pacs.008.xml'
message_code = 'urn:iso:std:iso:20022:tech:xsd:pacs.008.001.08'
# 2. Parse the XML file
fedwire_json = generate_fedwire_payload(xml_file, message_code)
# 3. The `fedwire_json` variable now holds the parsed dictionary
if fedwire_json:
print(json.dumps(fedwire_json, indent=4))
```
### Parsing a `pacs.002.001.10` (Payment Status Report) XML to JSON
This example shows how to parse a `pacs.002` payment status report (ack/nack) into a JSON object.
```python
from miso20022.fedwire import generate_fedwire_payload
import json
# 1. Define the path to your XML file and the message code
xml_file = 'sample_files/pacs.002_PaymentAck.xml'
message_code = 'urn:iso:std:iso:20022:tech:xsd:pacs.002.001.10'
# 2. Parse the XML to get the JSON payload
fedwire_json = generate_fedwire_payload(xml_file, message_code)
# 3. The `fedwire_json` variable now holds the parsed dictionary
if fedwire_json:
print(json.dumps(fedwire_json, indent=4))
```
## Command-Line Interface (CLI)
The package includes a command-line tool, `miso20022`, for generating and parsing messages directly from your terminal.
### Generating a Message
**Usage:**
```bash
miso20022 generate --message_code [MESSAGE_CODE] --environment [ENV] --fed-aba [ABA_NUMBER] --input-file [PAYLOAD_FILE] --output-file [OUTPUT_XML]
```
**Arguments:**
- `--message_code`: The ISO 20022 message code (e.g., `urn:iso:std:iso:20022:tech:xsd:pacs.008.001.08`).
- `--environment`: The environment for the message (`TEST` or `PROD`).
- `--fed-aba`: The Fedwire ABA number.
- `--input-file`: Path to the input JSON payload file.
- `--output-file`: (Optional) Path to save the generated XML message.
- `--xsd-file`: (Optional) Path to the XSD file for validation.
**Example:**
```bash
miso20022 generate \
--message_code urn:iso:std:iso:20022:tech:xsd:pacs.008.001.08 \
--environment TEST \
--fed-aba 000000008 \
--input-file sample_files/sample_payment.json \
--output-file pacs.008_output.xml
```
### Parsing a Message
**Usage:**
```bash
miso20022 parse --input-file [INPUT_XML] --message-code [MESSAGE_CODE] --output-file [OUTPUT_JSON]
```
**Arguments:**
- `--input-file`: Path to the input ISO 20022 XML file.
- `--message-code`: The ISO 20022 message code of the input file.
- `--output-file`: (Optional) Path to save the output JSON payload.
**Example:**
```bash
miso20022 parse \
--input-file sample_files/pacs.008.001.008_2025_1.xml \
--message-code urn:iso:std:iso:20022:tech:xsd:pacs.008.001.08 \
--output-file parsed_payload.json
```
---
## Supported Message Types
The library provides different levels of support for various message types.
### Message Generation (`generate_fedwire_message`)
The following message types are fully supported with dedicated data models for generating complete XML messages:
- **`pacs.008.001.08`**: FI to FI Customer Credit Transfer
- **`pacs.028.001.03`**: FI to FI Payment Status Request
While other message types might be generated using the generic handlers, these are the ones with first-class support.
### XML to JSON Parsing (`generate_fedwire_payload`)
The library can parse the following XML message types into a simplified Fedwire JSON format:
- **`pacs.008.001.08`**: FI to FI Customer Credit Transfer
- **`pacs.002.001.10`**: FI to FI Payment Status Report
Support for parsing other message types can be added by creating new mapping functions.
### Future Support
We are actively working to expand the range of supported message types. Future releases will include built-in support for additional `pacs`, `camt`, and other ISO 20022 messages, with planned support for FedNow services. Stay tuned for updates!
## Contributing
Contributions are welcome! Please refer to the [Project repository](https://github.com/Mbanq/iso20022) for contribution guidelines, to open an issue, or to submit a pull request.
<p align="center"><strong style="font-size: 2em">Built with ❤️ in the Beautiful State of Washington!</strong></p>
Raw data
{
"_id": null,
"home_page": null,
"name": "miso20022",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "iso20022, financial, messaging, banking, fedwire, us payment rails, fednow",
"author": null,
"author_email": "Sai Vatsavai <sai.vatsavai@mbanq.com>, Vamsi Krishna <vamsi.krishna@mbanq.com>, Mbanq <developers@mbanq.com>",
"download_url": "https://files.pythonhosted.org/packages/32/af/025ce2ed20e2e8d581abe609fdf5e315750a7e9873129b596375a016defc/miso20022-0.1.6.tar.gz",
"platform": null,
"description": "# MISO20022 Python Library\n\nThis package provides a set of tools for generating and working with ISO 20022 financial messages, with a focus on the US Payment Rails.\n\n\n## Installation\n\nYou can install the package from PyPI:\n\n```bash\npip install miso20022\n```\n\n## Usage Examples\n\nThis section provides detailed examples for the core functionalities of the library.\n\n**Index:**\n- [Generating a `pacs.008.001.08` (Customer Credit Transfer) Message](#generating-a-pacs00800108-customer-credit-transfer-message)\n- [Generating a `pacs.028.001.03` (Payment Status Request) Message](#generating-a-pacs02800103-payment-status-request-message)\n- [Parsing a `pacs.008.001.08` XML to JSON](#parsing-a-pacs00800108-xml-to-json)\n- [Parsing a `pacs.002.001.10` (Payment Status Report) XML to JSON](#parsing-a-pacs00200110-payment-status-report-xml-to-json)\n\n---\n\n### Input JSON Structure\n\nThe `generate_fedwire_message` function expects a specific JSON structure for the `payload` argument. Below are the expected formats for the supported message types.\n\n#### `pacs.008.001.08` (Customer Credit Transfer)\n\nThe payload for a `pacs.008` message should follow this structure:\n\n```json\n{\n \"fedWireMessage\": {\n \"inputMessageAccountabilityData\": {\n \"inputCycleDate\": \"20250109\",\n \"inputSource\": \"MBANQ\",\n \"inputSequenceNumber\": \"001000001\"\n },\n \"amount\": {\n \"amount\": \"1000\"\n },\n \"senderDepositoryInstitution\": {\n \"senderABANumber\": \"<routing_number>\",\n \"senderShortName\": \"Pypi Bank\"\n },\n \"receiverDepositoryInstitution\": {\n \"receiverABANumber\": \"<routing_number>\",\n \"receiverShortName\": \"HelloBank\"\n },\n \"originator\": {\n \"personal\": {\n \"name\": \"JANE SMITH\",\n \"address\": {\n \"addressLineOne\": \"456 eat street\",\n \"addressLineTwo\": \"SOMEWHERE, CA 67890\",\n \"addressLineThree\": \"\"\n },\n \"identifier\": \"<account_number>\"\n }\n },\n \"beneficiary\": {\n \"personal\": {\n \"name\": \"JOHN DOE\",\n \"address\": {\n \"addressLineOne\": \"123 Main street\",\n \"addressLineTwo\": \"ANYTOWN, TX 12345\",\n \"addressLineThree\": \"\"\n },\n \"identifier\": \"<account_number>\"\n }\n }\n }\n}\n```\n\n#### `pacs.028.001.03` (Payment Status Request)\n\nThe payload for a `pacs.028` message should follow this structure:\n\n```json\n{\n \"fedWireMessage\": {\n \"inputMessageAccountabilityData\": {\n \"inputCycleDate\": \"20250109\",\n \"inputSource\": \"MBANQ\",\n \"inputSequenceNumber\": \"001000002\"\n },\n \"senderDepositoryInstitution\": {\n \"senderABANumber\": \"<routing_number>\",\n \"senderShortName\": \"<short_name>\"\n },\n \"receiverDepositoryInstitution\": {\n \"receiverABANumber\": \"<routing_number>\",\n \"receiverShortName\": \"<short_name>\"\n }\n },\n \"message_id\": \"PACS028REQ20250109001\",\n \"original_msg_id\": \"20250109MBANQ001000001\",\n \"original_msg_nm_id\": \"pacs.008.001.08\",\n \"original_creation_datetime\": \"2025-01-09T12:34:56Z\",\n \"original_end_to_end_id\": \"MEtoEIDCJShqZKb\"\n}\n```\n\n### Generating a `pacs.008.001.08` (Customer Credit Transfer) Message\n\nThis example shows how to generate a Fedwire `pacs.008` message from a JSON payload.\n\n```python\nimport json\nfrom miso20022.fedwire import generate_fedwire_message\n\n# 1. Load your payment data from a JSON object\nwith open('sample_files/sample_payload.json', 'r') as f:\n payload = json.load(f)\n\n# 2. Define the necessary message parameters\nmessage_code = 'urn:iso:std:iso:20022:tech:xsd:pacs.008.001.08'\nenvironment = \"TEST\" # Or \"PROD\"\nfed_aba = '000000008' # The ABA number for the Fed\nxsd_path = 'proprietary_fed_file.xsd' # The XSD file for fedwire format\n\n# 3. Generate the complete XML message\n_, _, complete_message = generate_fedwire_message(\n message_code=message_code,\n environment=environment,\n fed_aba=fed_aba,\n payload=payload,\n xsd_path=xsd_path\n)\n\n# 4. The `complete_message` variable now holds the XML string\nif complete_message:\n print(complete_message)\n```\n\n### Generating a `pacs.028.001.03` (Payment Status Request) Message\n\nThis example shows how to generate a `pacs.028` payment status request.\n\n```python\nimport json\nfrom miso20022.fedwire import generate_fedwire_message\n\n# 1. Load the payload for the status request\nwith open('sample_files/sample_pacs028_payload.json', 'r') as f:\n payload = json.load(f)\n\n# 2. Define message parameters\nmessage_code = 'urn:iso:std:iso:20022:tech:xsd:pacs.028.001.03'\nenvironment = \"TEST\" # Or \"PROD\"\nfed_aba = '000000008'\nxsd_path = 'proprietary_fed_file.xsd'\n\n# 3. Generate the XML message\n_, _, complete_message = generate_fedwire_message(\n message_code=message_code,\n environment=environment,\n fed_aba=fed_aba,\n payload=payload,\n xsd_path=xsd_path\n)\n\n# 4. The `complete_message` variable now holds the XML string\nif complete_message:\n print(complete_message)\n```\n\n### Parsing a `pacs.008.001.08` XML to JSON\n\nThis example shows how to parse a `pacs.008` XML file and convert it into a simplified JSON object.\n\n```python\nfrom miso20022.fedwire import generate_fedwire_payload\nimport json\n\n# 1. Define the path to your XML file and the message code\nxml_file = 'incoming_pacs.008.xml'\nmessage_code = 'urn:iso:std:iso:20022:tech:xsd:pacs.008.001.08'\n\n# 2. Parse the XML file\nfedwire_json = generate_fedwire_payload(xml_file, message_code)\n\n# 3. The `fedwire_json` variable now holds the parsed dictionary\nif fedwire_json:\n print(json.dumps(fedwire_json, indent=4))\n```\n\n### Parsing a `pacs.002.001.10` (Payment Status Report) XML to JSON\n\nThis example shows how to parse a `pacs.002` payment status report (ack/nack) into a JSON object.\n\n```python\nfrom miso20022.fedwire import generate_fedwire_payload\nimport json\n\n# 1. Define the path to your XML file and the message code\nxml_file = 'sample_files/pacs.002_PaymentAck.xml'\nmessage_code = 'urn:iso:std:iso:20022:tech:xsd:pacs.002.001.10'\n\n# 2. Parse the XML to get the JSON payload\nfedwire_json = generate_fedwire_payload(xml_file, message_code)\n\n# 3. The `fedwire_json` variable now holds the parsed dictionary\nif fedwire_json:\n print(json.dumps(fedwire_json, indent=4))\n```\n\n## Command-Line Interface (CLI)\n\nThe package includes a command-line tool, `miso20022`, for generating and parsing messages directly from your terminal.\n\n### Generating a Message\n\n**Usage:**\n\n```bash\nmiso20022 generate --message_code [MESSAGE_CODE] --environment [ENV] --fed-aba [ABA_NUMBER] --input-file [PAYLOAD_FILE] --output-file [OUTPUT_XML]\n```\n\n**Arguments:**\n\n- `--message_code`: The ISO 20022 message code (e.g., `urn:iso:std:iso:20022:tech:xsd:pacs.008.001.08`).\n- `--environment`: The environment for the message (`TEST` or `PROD`).\n- `--fed-aba`: The Fedwire ABA number.\n- `--input-file`: Path to the input JSON payload file.\n- `--output-file`: (Optional) Path to save the generated XML message.\n- `--xsd-file`: (Optional) Path to the XSD file for validation.\n\n**Example:**\n\n```bash\nmiso20022 generate \\\n --message_code urn:iso:std:iso:20022:tech:xsd:pacs.008.001.08 \\\n --environment TEST \\\n --fed-aba 000000008 \\\n --input-file sample_files/sample_payment.json \\\n --output-file pacs.008_output.xml\n```\n\n### Parsing a Message\n\n**Usage:**\n\n```bash\nmiso20022 parse --input-file [INPUT_XML] --message-code [MESSAGE_CODE] --output-file [OUTPUT_JSON]\n```\n\n**Arguments:**\n\n- `--input-file`: Path to the input ISO 20022 XML file.\n- `--message-code`: The ISO 20022 message code of the input file.\n- `--output-file`: (Optional) Path to save the output JSON payload.\n\n**Example:**\n\n```bash\nmiso20022 parse \\\n --input-file sample_files/pacs.008.001.008_2025_1.xml \\\n --message-code urn:iso:std:iso:20022:tech:xsd:pacs.008.001.08 \\\n --output-file parsed_payload.json\n```\n\n---\n\n## Supported Message Types\n\nThe library provides different levels of support for various message types.\n\n### Message Generation (`generate_fedwire_message`)\n\nThe following message types are fully supported with dedicated data models for generating complete XML messages:\n\n- **`pacs.008.001.08`**: FI to FI Customer Credit Transfer\n- **`pacs.028.001.03`**: FI to FI Payment Status Request\n\nWhile other message types might be generated using the generic handlers, these are the ones with first-class support.\n\n### XML to JSON Parsing (`generate_fedwire_payload`)\n\nThe library can parse the following XML message types into a simplified Fedwire JSON format:\n\n- **`pacs.008.001.08`**: FI to FI Customer Credit Transfer\n- **`pacs.002.001.10`**: FI to FI Payment Status Report\n\nSupport for parsing other message types can be added by creating new mapping functions.\n\n### Future Support\n\nWe are actively working to expand the range of supported message types. Future releases will include built-in support for additional `pacs`, `camt`, and other ISO 20022 messages, with planned support for FedNow services. Stay tuned for updates!\n\n## Contributing\n\nContributions are welcome! Please refer to the [Project repository](https://github.com/Mbanq/iso20022) for contribution guidelines, to open an issue, or to submit a pull request.\n\n<p align=\"center\"><strong style=\"font-size: 2em\">Built with \u2764\ufe0f in the Beautiful State of Washington!</strong></p>\n\n\n",
"bugtrack_url": null,
"license": null,
"summary": "ISO 20022 Message Generator for US Payment Rails",
"version": "0.1.6",
"project_urls": {
"Bug Tracker": "https://github.com/Mbanq/iso20022/issues",
"Homepage": "https://github.com/Mbanq/iso20022"
},
"split_keywords": [
"iso20022",
" financial",
" messaging",
" banking",
" fedwire",
" us payment rails",
" fednow"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "9aafa3af678d71c9f7aa55dcdd2f5c2c35d896c34dce23f3992129b99169ad65",
"md5": "73328daff4ee4cfcaa99f85b81937ee7",
"sha256": "47589cf7064aedca1cc2e2ad204e4732612d40d02e93c1f9251832d524ee9875"
},
"downloads": -1,
"filename": "miso20022-0.1.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "73328daff4ee4cfcaa99f85b81937ee7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 26336,
"upload_time": "2025-07-23T21:34:19",
"upload_time_iso_8601": "2025-07-23T21:34:19.757020Z",
"url": "https://files.pythonhosted.org/packages/9a/af/a3af678d71c9f7aa55dcdd2f5c2c35d896c34dce23f3992129b99169ad65/miso20022-0.1.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "32af025ce2ed20e2e8d581abe609fdf5e315750a7e9873129b596375a016defc",
"md5": "7f82145e616ecc40aebace6809254093",
"sha256": "39c4ce540c943de62a4d58cc377bca4523698e484c86e4e92b453c6d7857d708"
},
"downloads": -1,
"filename": "miso20022-0.1.6.tar.gz",
"has_sig": false,
"md5_digest": "7f82145e616ecc40aebace6809254093",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 26350,
"upload_time": "2025-07-23T21:34:21",
"upload_time_iso_8601": "2025-07-23T21:34:21.557866Z",
"url": "https://files.pythonhosted.org/packages/32/af/025ce2ed20e2e8d581abe609fdf5e315750a7e9873129b596375a016defc/miso20022-0.1.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-23 21:34:21",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Mbanq",
"github_project": "iso20022",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "miso20022"
}
JSON
