Messages Rail

Messages Rail

Financial messaging, ISO 20022, SWIFT, and message transformation.

Overview

The Messages Rail provides endpoints for creating, transforming, and processing financial messages in various formats including ISO 20022, SWIFT MT, and local formats.

Base URL

/api/v1/messages

Endpoints

Create Message

POST /api/v1/messages

Create a new financial message.

Request Body:

{
  "type": "pacs.008",
  "format": "ISO20022",
  "payload": {
    "creditTransferTransactionInformation": {
      "paymentIdentification": {
        "instructionIdentification": "INST001",
        "endToEndIdentification": "E2E001"
      },
      "amount": {
        "instructedAmount": {
          "currency": "SAR",
          "value": "50000.00"
        }
      },
      "creditor": {
        "name": "Beneficiary Name",
        "postalAddress": {
          "country": "SA"
        }
      }
    }
  }
}

Response:

{
  "data": {
    "messageId": "msg_abc123",
    "type": "pacs.008",
    "format": "ISO20022",
    "status": "CREATED",
    "createdAt": "2025-01-15T10:00:00Z"
  }
}

Transform Message

POST /api/v1/messages/:messageId/transform

Transform message between formats.

Request Body:

{
  "targetFormat": "SWIFT_MT",
  "targetType": "MT103"
}

Response:

{
  "data": {
    "originalFormat": "ISO20022",
    "targetFormat": "SWIFT_MT",
    "transformedPayload": "{1:F01...}{2:O103...}...",
    "warnings": []
  }
}

Validate Message

POST /api/v1/messages/:messageId/validate

Validate message against schema.

Response:

{
  "data": {
    "valid": true,
    "errors": [],
    "warnings": [
      {
        "field": "creditor.postalAddress",
        "message": "Street name recommended"
      }
    ]
  }
}

Get Message

GET /api/v1/messages/:messageId

Retrieve message details.

List Messages

GET /api/v1/messages

Query Parameters:

Parameter	Type	Description
type	string	Message type
format	string	Message format
status	string	Message status
dateFrom	string	Date range start
dateTo	string	Date range end

Send Message

POST /api/v1/messages/:messageId/send

Send message to destination.

Request Body:

{
  "destination": "SWIFT",
  "priority": "NORMAL",
  "deliveryNotification": true
}

Parse Message

POST /api/v1/messages/parse

Parse an incoming message.

Request Body:

{
  "format": "SWIFT_MT",
  "rawMessage": "{1:F01BANKUS33AXXX...}"
}

Message Formats

Format	Description
ISO20022	ISO 20022 XML messages
SWIFT_MT	SWIFT MT messages
SWIFT_MX	SWIFT MX messages
LOCAL	Local clearing format
JSON	JSON representation

ISO 20022 Message Types

Type	Description
pacs.008	Customer Credit Transfer
pacs.002	Payment Status Report
pacs.004	Payment Return
camt.053	Bank to Customer Statement
camt.054	Bank to Customer Debit/Credit Notification

SWIFT MT Types

Type	Description
MT103	Single Customer Credit Transfer
MT202	General Financial Institution Transfer
MT940	Customer Statement
MT950	Statement Message

Message Status

Status	Description
CREATED	Message created
VALIDATED	Validation passed
TRANSFORMED	Format transformed
SENT	Sent to network
DELIVERED	Delivered to recipient
FAILED	Processing failed

Events

Event	Description
message.created	Message created
message.validated	Validation completed
message.sent	Message sent
message.delivered	Delivery confirmed
message.failed	Processing failed

See Also

• Routing Rail - Payment routing
• Clearing Rail - Settlement