ISO 20022 Financial Messaging

The ISO 20022 Rail provides comprehensive support for international financial messaging standards. This rail enables seamless integration with global payment systems, SWIFT gpi, and regional clearing networks while maintaining full Shariah compliance for Islamic finance operations.

Overview

ISO 20022 is the global standard for financial messaging, covering payments, securities, trade services, and foreign exchange. Islamic Open Finance supports message-level conformance with:

Payment Initiation: pain.001, pain.002, pain.008
FI to FI Transfers: pacs.002, pacs.004, pacs.008, pacs.009
Cash Management: camt.052, camt.053, camt.054, camt.056, camt.060

Market Practices

The platform supports multiple regional market practices:

Practice	Region	Description
CBPR+	Global	SWIFT Cross-Border Payments and Reporting Plus
GCC	Gulf States	UAE, Saudi, Qatar, Kuwait, Bahrain, Oman
SEPA	Europe	Single Euro Payments Area
MY	Malaysia	Bank Negara Malaysia standards
ID	Indonesia	Bank Indonesia standards
PK	Pakistan	State Bank of Pakistan standards

Endpoints

Credit Transfer Initiation

Create a customer credit transfer (pain.001):

POST /api/v1/rails/iso20022/credit-transfers

Request Body:

{
  "marketPractice": "CBPR+",
  "creditTransfer": {
    "paymentInformationId": "PI20240115001",
    "paymentMethod": "TRF",
    "batchBooking": false,
    "numberOfTransactions": 1,
    "requestedExecutionDate": "2024-01-16",
    "debtor": {
      "name": "Islamic Finance Corp",
      "postalAddress": {
        "country": "AE"
      }
    },
    "debtorAccount": {
      "iban": "AE070331234567890123456"
    },
    "debtorAgent": {
      "bic": "NBABORXX"
    },
    "chargeBearer": "SHAR",
    "transactions": [
      {
        "endToEndId": "E2E20240115001",
        "amount": {
          "value": "50000.00",
          "currency": "AED"
        },
        "creditorAgent": {
          "bic": "RIABORXX"
        },
        "creditor": {
          "name": "Beneficiary Company"
        },
        "creditorAccount": {
          "iban": "SA0380000000608010167519"
        },
        "purposeCode": "TRAD",
        "remittanceInformation": "Invoice 2024-001"
      }
    ]
  }
}

Response:

{
  "message": {
    "id": "clm123abc",
    "messageId": "IOF20240115120000ABC123",
    "messageType": "pain.001",
    "status": "VALIDATED",
    "uetr": "97ed4827-7b6f-4491-a06f-b548d5a7512d",
    "validationStatus": "VALID"
  },
  "validationResult": {
    "valid": true,
    "errors": [],
    "warnings": []
  }
}

Get Message Status

Retrieve the status of a message:

GET /api/v1/rails/iso20022/messages/{messageId}/status

Response:

{
  "message": {
    "id": "clm123abc",
    "messageId": "IOF20240115120000ABC123",
    "status": "COMPLETED",
    "uetr": "97ed4827-7b6f-4491-a06f-b548d5a7512d"
  },
  "statusReport": {
    "originalMessageId": "IOF20240115120000ABC123",
    "groupStatus": "ACSC",
    "transactionStatuses": [
      {
        "originalEndToEndId": "E2E20240115001",
        "status": "ACSC",
        "acceptanceDateTime": "2024-01-15T12:30:00Z",
        "settlementDate": "2024-01-16"
      }
    ]
  }
}

Track by UETR

Track a payment using SWIFT gpi UETR:

GET /api/v1/rails/iso20022/transactions/uetr/{uetr}/status

Request Account Statement

Request a bank statement (camt.060):

POST /api/v1/rails/iso20022/statements/request

Request Body:

{
  "account": {
    "iban": "AE070331234567890123456"
  },
  "fromDate": "2024-01-01",
  "toDate": "2024-01-31",
  "marketPractice": "GCC"
}

Cancel Payment

Cancel a payment request (camt.056):

POST /api/v1/rails/iso20022/credit-transfers/{messageId}/cancel

Request Body:

{
  "code": "DUPL",
  "description": "Duplicate payment detected"
}

Islamic Finance Support

The ISO 20022 rail includes full support for Islamic finance operations with GCC-specific purpose codes:

Code	Description
PROF	Profit Distribution
ZKAT	Zakat Payment
WAQF	Waqf Contribution
IJRA	Ijarah Payment
MRBA	Murabaha Settlement
MDRB	Mudarabah Distribution
MSHK	Musharakah Distribution
SUKK	Sukuk Coupon Payment

Islamic Credit Transfer

Create a Shariah-compliant credit transfer:

POST /api/v1/rails/iso20022/islamic/credit-transfers

Request Body:

{
  "marketPractice": "GCC",
  "creditTransfer": {
    "paymentInformationId": "PI20240115ISL001",
    "paymentMethod": "TRF",
    "debtor": {
      "name": "Islamic Bank of Abu Dhabi"
    },
    "debtorAccount": {
      "iban": "AE070331234567890123456"
    },
    "debtorAgent": {
      "bic": "NBABORXX"
    },
    "transactions": [
      {
        "endToEndId": "E2E20240115ISL001",
        "amount": {
          "value": "100000.00",
          "currency": "AED"
        },
        "creditorAgent": {
          "bic": "RIABORXX"
        },
        "creditor": {
          "name": "Murabaha Customer LLC"
        },
        "creditorAccount": {
          "iban": "SA0380000000608010167519"
        },
        "purposeCode": "MRBA",
        "remittanceInformation": "Murabaha Contract MRB-2024-001"
      }
    ]
  },
  "contractType": "MURABAHA",
  "shariahBoardRef": "SB-2024-001",
  "profitRate": "4.5"
}

Validation

Validate Message

Validate an ISO 20022 message before submission:

POST /api/v1/rails/iso20022/validate

Request Body:

{
  "messageType": "pain.001",
  "json": { ... },
  "marketPractice": "CBPR+"
}

Response:

{
  "valid": true,
  "errors": [],
  "warnings": [
    {
      "path": "creditor.postalAddress",
      "code": "ADDR_INCOMPLETE",
      "message": "Complete postal address recommended for CBPR+",
      "severity": "WARNING"
    }
  ],
  "conformanceLevel": "FULL",
  "marketPracticeCompliance": {
    "practice": "CBPR+",
    "compliant": true,
    "issues": []
  }
}

Market Practice Configuration

List Market Practices

GET /api/v1/rails/iso20022/market-practices

Get Market Practice Details

GET /api/v1/rails/iso20022/market-practices/{practice}

Response:

{
  "code": "GCC",
  "name": "GCC Market Practice",
  "region": "Gulf Cooperation Council",
  "supportedMessages": [
    "pain.001",
    "pain.002",
    "pacs.008",
    "pacs.002",
    "camt.053",
    "camt.054",
    "camt.056"
  ],
  "clearingSystems": ["SARIE", "UAEFTS", "QPAY", "KFAST"],
  "cutoffTimes": {
    "SARIE": "14:00",
    "UAEFTS": "13:30"
  },
  "mandatoryFields": [
    "debtor.name",
    "debtor.postalAddress.country",
    "creditor.name",
    "purpose.code"
  ],
  "islamicFinanceEnabled": true,
  "supportedContracts": [
    "MURABAHA",
    "IJARAH",
    "MUSHARAKAH",
    "MUDARABAH",
    "SUKUK"
  ]
}

Utility Operations

Generate UETR

Generate a Universal End-to-End Transaction Reference:

POST /api/v1/rails/iso20022/utils/generate-uetr

Response:

{
  "uetr": "97ed4827-7b6f-4491-a06f-b548d5a7512d"
}

Parse XML

Parse ISO 20022 XML to JSON:

POST /api/v1/rails/iso20022/utils/parse-xml

Convert to XML

Convert JSON to ISO 20022 XML:

POST /api/v1/rails/iso20022/utils/to-xml

Message Status Codes

ISO 20022 transaction status codes:

Code	Status	Description
ACCP	Accepted	Accepted Customer Profile
ACSC	Settled	Accepted Settlement Completed
ACSP	Processing	Accepted Settlement In Process
ACTC	Validated	Accepted Technical Validation
ACWC	Accepted	Accepted With Change
PDNG	Pending	Pending further action
RJCT	Rejected	Rejected

Webhooks

Subscribe to ISO 20022 message events:

iso20022.message.received - New message received
iso20022.message.validated - Message validation complete
iso20022.message.accepted - Message accepted for processing
iso20022.message.settled - Settlement completed
iso20022.message.rejected - Message rejected
iso20022.status.updated - Payment status update received

SDK Usage

TypeScript/JavaScript

import { IOFClient } from "@iof/sdk";

const client = new IOFClient({
  apiKey: process.env.IOF_API_KEY,
  baseUrl: "https://api.islamicopenfinance.com",
});

// Create credit transfer
const result = await client.iso20022.createCreditTransfer({
  marketPractice: "GCC",
  creditTransfer: {
    paymentInformationId: "PI001",
    paymentMethod: "TRF",
    debtor: { name: "Sender Corp" },
    debtorAccount: { iban: "AE070331234567890123456" },
    debtorAgent: { bic: "NBABORXX" },
    transactions: [
      {
        endToEndId: "E2E001",
        amount: { value: "10000.00", currency: "AED" },
        creditorAgent: { bic: "RIABORXX" },
        creditor: { name: "Receiver Corp" },
        creditorAccount: { iban: "SA0380000000608010167519" },
      },
    ],
  },
});

// Track by UETR
const status = await client.iso20022.getTransactionStatusByUETR(
  result.message.uetr,
);

Compliance

The ISO 20022 rail is designed to meet:

SOC 2 Type 2: Complete audit trail for all messages
GDPR: Data minimization and purpose limitation
ISO 27001: Information security management
PCI DSS: Payment card industry standards
SWIFT CSP: Customer Security Programme compliance

For regulatory reporting requirements, see the Compliance Rail.