payment-message 0.1.4

Open Payments - Message Parsing Library
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130

# Open Payments - Message Parsing Library

[![Apache License 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](http://www.apache.org/licenses/LICENSE-2.0)
[![Contributions welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg)](CONTRIBUTING.md)
[![GitHub issues](https://img.shields.io/github/issues/Open-Payments/messages)](https://github.com/Open-Payments/messages/issues)

Open Payments is a robust message parsing library designed to handle various message types from the **FedNow** and **ISO 20022** standards. This library makes it easier to integrate payment messaging formats into your financial applications using efficient parsing, serialization, and deserialization capabilities.

---

## Features

- **Comprehensive Message Support**: Supports a wide range of ISO 20022 message types such as `admi`, `camt`, `pacs`, and `pain`.
- **FedNow Ready**: Fully compatible with FedNow messaging specifications.
- **Serde-powered**: Built with Serde for fast and efficient (de)serialization to/from XML and JSON formats.
- **Easy Integration**: Simple APIs to parse, convert, and handle payment messages within your Rust applications.
- **Extensible**: Designed to be open-source and easy to contribute to, making it suitable for custom implementations.

---

## Getting Started

### Prerequisites

You’ll need the following installed to build and use this library:

- [Rust](https://www.rust-lang.org/tools/install) (latest stable version)
- [Cargo](https://doc.rust-lang.org/cargo/getting-started/installation.html) (Rust package manager)

### Installation

Add the following to your `Cargo.toml` to start using the library in your Rust project:

```toml
[dependencies]
open-payments = "0.1.0"
```

### Usage

Here's an example of how to parse a FedNow message and convert it to JSON:

```rust
use open_payments::FednowMessage;
use serde_json::json;
use std::fs::File;
use std::io::BufReader;

fn main() {
    let file = File::open("path_to_fednow_message.xml").expect("Unable to open file");
    let reader = BufReader::new(file);

    let message: FednowMessage = serde_xml_rs::from_reader(reader).expect("Unable to parse XML");

    // Convert to JSON
    let json_message = json!(message);
    println!("{}", serde_json::to_string_pretty(&json_message).unwrap());
}
```

### Supported Messages

The library supports various message formats defined by ISO 20022, including:

- **admi.002.001.01**: Administrative notifications - Provides status information regarding system events.
- **admi.004.001.02**: System event notification - Notifies about system events such as maintenance, downtime, or system changes.
- **admi.006.001.01**: Resend request - Requests the resend of previously sent messages.
- **admi.007.001.01**: Receipt acknowledgement - Confirms the receipt of a message.
- **admi.011.001.01**: System event acknowledgement - Acknowledges a system event notification.
- **admi.998.001.02**: Administration proprietary message - Custom or proprietary administration messages for specific use cases.

- **camt.026.001.07**: Payment investigation - Used to initiate an investigation into a payment.
- **camt.028.001.09**: Resolution of investigation - Provides the outcome of a previously initiated payment investigation.
- **camt.029.001.09**: Unable to apply - Used to notify that a payment cannot be applied as expected.
- **camt.052.001.08**: Bank-to-customer account report - Reports on an account's transactions and balances.
- **camt.054.001.08**: Bank-to-customer debit credit notification - Notifies about debits and credits to an account.
- **camt.055.001.09**: Customer payment cancellation request - Requests the cancellation of a payment transaction.
- **camt.056.001.08**: FIToFI payment cancellation request - Requests the cancellation of a payment sent between financial institutions.
- **camt.060.001.05**: Account reporting request - Requests detailed information regarding transactions on an account.

- **pacs.002.001.10**: FIToFI payment status report - Provides the status of a payment sent between financial institutions.
- **pacs.004.001.10**: Payment return - Returns a payment that was unable to be applied.
- **pacs.008.001.08**: FIToFI customer credit transfer - Facilitates the transfer of funds between financial institutions for customer-initiated credit transfers.
- **pacs.009.001.08**: Financial institution credit transfer - Transfers funds between financial institutions.
- **pacs.028.001.03**: FIToFI payment status request - Requests the status of a payment sent between financial institutions.

- **pain.013.001.07**: Creditor payment activation request - Initiates a payment request from the creditor’s side.
- **pain.014.001.07**: Creditor payment activation request status report - Provides a status report for a payment activation request.

---

This extensive support for ISO 20022 messages enables comprehensive coverage of the payment message lifecycle, including administrative processes, investigations, status reports, and transaction instructions.

## Contributing

We welcome contributions from developers to help improve the library. Whether you’re fixing a bug, improving documentation, or adding new message types, your help is appreciated!

1. Fork the repository.
2. Create a new branch with your feature or fix: `git checkout -b feature-branch-name`.
3. Commit your changes: `git commit -m 'Add some feature'`.
4. Push to the branch: `git push origin feature-branch-name`.
5. Open a pull request.

Make sure to review our [contributing guidelines](CONTRIBUTING.md) before you start.

---

## Roadmap

Here’s what’s coming up:

- Add a Sophisticated Error Framework for XML Parsing and Validation
- Add Support for Format Transformation (ISO20022 -> MT103)
- Add Examples for Format Conversion
- Performance optimizations for large message batches.
- Expanded documentation and examples.

You can view the complete roadmap [here](ROADMAP.md).

---

## License

This project is licensed under the Apache 2.0 License - see the [LICENSE](LICENSE) file for details.

---

## Contact

For any questions or discussions, please reach out via GitHub Issues on our [GitHub Issues](https://github.com/Open-Payments/messages/issues) page.