Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/open-payments/messages-api
Payment message validator service
https://github.com/open-payments/messages-api
banking fednow finance iso20022 payments validation
Last synced: about 2 months ago
JSON representation
Payment message validator service
- Host: GitHub
- URL: https://github.com/open-payments/messages-api
- Owner: Open-Payments
- License: apache-2.0
- Created: 2024-09-29T05:33:02.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2024-11-05T13:07:49.000Z (2 months ago)
- Last Synced: 2024-11-05T14:23:24.748Z (2 months ago)
- Topics: banking, fednow, finance, iso20022, payments, validation
- Language: JavaScript
- Homepage: https://openpayments.tech
- Size: 480 KB
- Stars: 1
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Messages API
The **Messages API** is part of the Open Payments initiative, designed to parse and validate financial payment messages. This API supports both FedNow and ISO20022 message formats, applying validation rules from their respective schemas. The API is available for both public and private use, with a ready-to-deploy Docker image available on Docker Hub.
- **API Portal**: [Messages API -Demo](https://portal.openpayments.tech)
- **Repository**: [Open Payments Messages API](https://github.com/Open-Payments/messages-api)
- **Docker Hub**: [Payment Messages API Docker Image](https://hub.docker.com/r/harishankarn/payment-messages-api)
- **API Documentation**: [Postman Collection](https://www.postman.com/openpaymentsapi/open-payments/overview)---
#### **API Endpoint:**
`POST /validate`
#### **Description:**
This endpoint accepts an XML payment message with a message type header and performs the following actions:
1. **Message Type Detection**: Uses the Message-Type header to determine the appropriate parser
2. **Parsing**: Converts the XML payment message into an internal object model
3. **Validation**: Applies schema-based validation for the specified message type
4. **Response**: Returns either the parsed message as JSON if valid, or an array of error messages if invalid---
#### **Request:**
- **Method**: `POST`
- **Headers**:
- `Content-Type`: `text/xml`
- `Message-Type`: Either `fednow` or `iso20022`
- **Body**: The XML content of the payment message##### Example Request:
```bash
curl -X POST http://localhost:8080/validate \
-H "Content-Type: text/xml" \
-H "Message-Type: iso20022" \
-d '
'
```---
#### **Response:**
- **Content-Type**: `application/json`
- **Status Codes**:
- `200 OK`: Message is valid and parsed successfully
- `400 Bad Request`: Validation or parsing errors
- **Body**:
- Success: The parsed message as JSON
- Error: Array of error messages##### Example Successful Response:
```json
{
"Document": {
"CstmrCdtTrfInitn": {
"GrpHdr": {
"MsgId": "ABC123456",
"CreDtTm": "2024-10-01T12:00:00Z"
}
}
}
}
```##### Example Error Response:
```json
[
"ISO20022 parsing error at path: Document.CstmrCdtTrfInitn.GrpHdr.MsgId",
"Error details: required field `MsgId` missing"
]
```---
#### **Running a Local Instance:**
To run your own private instance of the Messages API, you can use the Docker image from Docker Hub:
##### Step 1: Pull the Docker Image
```bash
docker pull harishankarn/payment-messages-api
```##### Step 2: Run the Docker Container
```bash
docker run -p 8080:8080 harishankarn/payment-messages-api
```This will start the API on port `8080` of your local machine.
---
#### **Features:**
- **Multiple Format Support**: Supports both FedNow and ISO20022 message formats
- **Clean Response Format**: Direct JSON output for successful parsing, clear error messages for failures
- **Thread Safety**: Handles parsing in separate threads to maintain responsiveness
- **Efficient Processing**: Optimized for handling large XML messages with minimal memory usage---
#### **Supported Message Types:**
1. **FedNow Messages**:
- All FedNow XML message formats
- Validation against FedNow schema rules2. **ISO20022 Messages**:
- Customer Credit Transfer Initiation (pain.001)
- Other ISO20022 message types to be added---
### API Documentation and Testing
Explore the full API documentation and test the Messages API using the Postman Collection:
- **Postman Collection**: [Open Payments Postman Collection](https://www.postman.com/openpaymentsapi/open-payments/overview)
- **Sample Messages**: Example messages for both FedNow and ISO20022 formats are available in the repository's `samples` directory---
### Development
To build and run the project locally:
1. **Requirements**:
- Rust 1.75 or later
- Cargo package manager2. **Build**:
```bash
cargo build
```3. **Run**:
```bash
cargo run
```The server will start on `http://0.0.0.0:8080`
For development builds, the project uses optimized compilation settings to reduce build times while maintaining debugging capabilities.
---
### Error Handling
The API provides clear and specific error messages in the following scenarios:
1. **Invalid Message Type**:
```json
["Unsupported or missing message type: "]
```2. **XML Parsing Errors**:
```json
["FedNow parsing error: invalid element at line 5"]
```3. **Schema Validation Errors**:
```json
[
"ISO20022 parsing error at path: Document.CstmrCdtTrfInitn.GrpHdr.MsgId",
"Error details: required field missing"
]
```---