ISO 20022 Gateway Specification

1. Executive Summary

ISO 20022 is the global standard for financial messaging, adopted by SWIFT, the European Central Bank, the Federal Reserve, and over 70 countries. It defines a universal vocabulary for financial transactions: structured XML messages that every major bank in the world already understands, processes, and trusts.

JIL Sovereign's ISO 20022 Gateway translates on-chain settlements into standards-compliant ISO 20022 XML messages, enabling banks and financial institutions to integrate with the JIL settlement layer using their existing SWIFT infrastructure. No new protocols, no proprietary formats, no integration rewrites. This eliminates the "last mile" problem of blockchain-to-bank communication - the gap that has prevented institutional adoption of on-chain settlement.

The gateway runs as a dedicated microservice on port :8651, accepting both JSON and XML inputs, and returning ISO 20022-compliant XML for all responses. It connects upstream to the JIL Settlement API, Wallet API, and Ledger Router, and downstream to Kafka for real-time event streaming.

2. Supported Message Types

The gateway supports four core ISO 20022 message types covering the full settlement lifecycle: initiation, interbank transfer, account statements, and real-time notifications.

All inbound endpoints accept both application/json and application/xml content types. JSON requests are mapped to ISO 20022 fields internally; XML requests are validated against the ISO 20022 schema directly. All responses are returned as application/xml in full ISO 20022 format.

3. Architecture

The ISO 20022 Gateway acts as a stateless translation layer between the traditional financial messaging world and the JIL L1 settlement layer. Banks interact exclusively with ISO 20022 XML. The gateway handles all mapping, validation, and event routing internally.

                        ISO 20022 Gateway Architecture

  Banks / FIs                                                    JIL Infrastructure
  ──────────                                                     ──────────────────

  ┌──────────────┐     pain.001 / pacs.008      ┌─────────────┐     ┌──────────────┐
  │              │ ──── (JSON or XML) ────────►  │             │ ──► │ Settlement   │
  │  Bank Core   │                               │  ISO 20022  │     │ API (:8110)  │
  │  Banking     │     camt.053 (XML)            │  Gateway    │     ├──────────────┤
  │  System      │ ◄──────────────────────────── │  (:8651)    │ ──► │ Wallet API   │
  │              │                               │             │     │ (:8082)      │
  │              │     camt.054 (WebSocket)       │             │     ├──────────────┤
  │              │ ◄─── real-time push ───────── │             │ ──► │ Ledger       │
  └──────────────┘                               └──────┬──────┘     │ Router       │
                                                        │            │ (:8080)      │
                                                        │            └──────────────┘
                                                        │
                                                   ┌────▼────┐
                                                   │  Kafka  │
                                                   │ (events)│
                                                   └─────────┘
                                              jil.state.sync.settlement_events

3.1 Request Flow (Inbound)

When a bank submits a pain.001 or pacs.008 message, the gateway validates the input (XML schema validation or Zod JSON validation), maps the fields to JIL settlement parameters, forwards the settlement to the Settlement API, and returns a standards-compliant XML response containing the message ID, settlement ID, and status.

3.2 Event Flow (Outbound)

Settlement events arrive from Kafka on the jil.state.sync.settlement_events topic. The gateway translates each event into a camt.054 XML notification and pushes it to all WebSocket clients subscribed to the affected account. For polling-based integration, banks can request camt.053 statements at any time via the REST endpoint.

3.3 BIC Identification

The gateway operates under the institutional BIC code JILSOVUS, identifying JIL Sovereign Technologies, Inc. as the servicing financial institution in all outbound ISO 20022 messages. Participating banks and FIs can provide their own BIC codes in inbound requests for proper routing and identification in the interbank (pacs.008) flow.

4. Field Mapping: pain.001

The following table defines how JIL settlement fields map to ISO 20022 pain.001.001.11 XML elements. This mapping is used when generating outbound XML from JSON requests and when parsing inbound XML into settlement parameters.

4.1 Group Header

Every pain.001 message includes a GrpHdr (Group Header) block containing the message ID (auto-generated as JIL-<UUID>), creation timestamp, number of transactions, control sum, and the initiating party (JIL Sovereign Technologies, Inc., BIC: JILSOVUS).

4.2 Payment Type Information

The gateway sets the Service Level to SEPA and Local Instrument to INST (instant), signaling that the payment should be treated as an instant settlement. This aligns with the JIL L1's sub-2-second finality guarantee.

5. Field Mapping: camt.053

The camt.053.001.11 message provides a complete account statement including balances and transaction history. The gateway generates this by querying the Wallet API for balances and the Ledger Router for transaction history, then mapping the results to ISO 20022 statement format.

5.1 Date Range Filtering

The camt.053 endpoint supports optional from and to query parameters for date range filtering. When provided, the statement is scoped to the FrToDt (From/To Date-Time) element in the XML output. When omitted, the statement defaults to the current day.

5.2 Transaction Summary

Each statement includes a TxsSummry (Transactions Summary) block with the total number of entries, enabling banks to perform quick reconciliation checks without parsing every entry.

6. API Reference

6.1 POST /v1/pain001 - Initiate Settlement

Initiates a credit transfer settlement. Accepts JSON or XML input; always returns ISO 20022 XML.

JSON Request:

POST /v1/pain001
Content-Type: application/json

{
  "from_account": "jil_acct_sender_001",
  "to_account": "jil_acct_receiver_002",
  "amount": "50000.00",
  "asset": "USD",
  "memo": "Invoice INV-2026-0142",
  "debtor_name": "Meridian Capital Partners",
  "creditor_name": "Atlas Global Trading Ltd",
  "debtor_bic": "MERDUS33",
  "creditor_bic": "ATLSGB2L"
}

XML Response (pain.001.001.11):

<?xml version="1.0" encoding="UTF-8"?>
<Document xmlns="urn:iso:std:iso:20022:tech:xsd:pain.001.001.11">
  <CstmrCdtTrfInitn>
    <GrpHdr>
      <MsgId>JIL-A3F8B2C1</MsgId>
      <CreDtTm>2026-02-09T14:30:00.000Z</CreDtTm>
      <NbOfTxs>1</NbOfTxs>
      <CtrlSum>50000.00</CtrlSum>
      <InitgPty>
        <Nm>JIL Sovereign Technologies, Inc.</Nm>
        <Id><OrgId><AnyBIC>JILSOVUS</AnyBIC></OrgId></Id>
      </InitgPty>
    </GrpHdr>
    <PmtInf>
      <PmtInfId>PMT-stl_m1a2b3c4</PmtInfId>
      <PmtMtd>TRF</PmtMtd>
      <NbOfTxs>1</NbOfTxs>
      <Dbtr><Nm>Meridian Capital Partners</Nm></Dbtr>
      <CdtTrfTxInf>
        <PmtId><EndToEndId>stl_m1a2b3c4</EndToEndId></PmtId>
        <Amt><InstdAmt Ccy="USD">50000.00</InstdAmt></Amt>
        <Cdtr><Nm>Atlas Global Trading Ltd</Nm></Cdtr>
        <RmtInf><Ustrd>Invoice INV-2026-0142</Ustrd></RmtInf>
      </CdtTrfTxInf>
    </PmtInf>
  </CstmrCdtTrfInitn>
</Document>

6.2 POST /v1/pacs008 - Interbank Transfer

Initiates an FI-to-FI credit transfer. Used when one bank routes a payment through JIL to another bank. Supports additional fields for instructing and instructed agent BICs.

POST /v1/pacs008
Content-Type: application/json

{
  "from_account": "jil_fi_bank_alpha",
  "to_account": "jil_fi_bank_beta",
  "amount": "1000000.00",
  "asset": "USDC",
  "instructing_agent_bic": "BNKAUS33",
  "instructed_agent_bic": "BNKBGB2L",
  "debtor_name": "Bank Alpha Corp",
  "creditor_name": "Bank Beta International"
}

6.3 GET /v1/camt053 - Account Statement

Returns an ISO 20022 account statement with balances and transaction history for the specified account.

GET /v1/camt053?account=jil_acct_sender_001&from=2026-02-01&to=2026-02-09

Response: application/xml containing full camt.053.001.11 statement with Bal (balance) and Ntry (entry) elements.

6.4 GET /health - Service Health

GET /health

{
  "ok": true,
  "service": "iso20022-gateway",
  "version": "1.0.0",
  "supported_messages": ["pain.001.001.11", "pacs.008.001.10", "camt.053.001.11", "camt.054.001.11"],
  "ws_subscriptions": 12,
  "upstream": {
    "settlement_api": "http://settlement-api:8110",
    "wallet_api": "http://wallet-api:8082",
    "ledger_router": "http://ledger-router:8080"
  },
  "ts": "2026-02-09T14:30:00.000Z"
}

6.5 GET /v1/message-types - Supported Message Types

Returns a machine-readable catalog of all supported ISO 20022 message types, their endpoints, accepted content types, and descriptions. Useful for integration discovery and automated client configuration.

7. WebSocket Protocol (camt.054)

The camt.054 WebSocket endpoint provides real-time push notifications for settlement events. Banks connect once and receive ISO 20022-formatted debit/credit notifications as settlements are confirmed on the JIL L1.

7.1 Subscription Model

Each WebSocket client can subscribe to multiple accounts simultaneously. The gateway maintains an in-memory subscription map, routing Kafka settlement events to the correct clients. When a settlement event arrives for a subscribed account, the gateway generates a camt.054.001.11 XML document and pushes it over the WebSocket connection.

7.2 Notification Structure

Each notification contains the account ID, entry reference (transaction ID), amount with currency, credit/debit indicator (CRDT or DBIT), booking and value dates, entry status (BOOK or PDNG), and full remittance information including the related parties (debtor and creditor names).

7.3 Connection Management

The server automatically cleans up subscriptions when a client disconnects. Stale WebSocket connections (where readyState is not OPEN) are pruned during notification delivery. The /health endpoint reports the current active subscription count for monitoring.

Example camt.054 Push Notification:

<?xml version="1.0" encoding="UTF-8"?>
<Document xmlns="urn:iso:std:iso:20022:tech:xsd:camt.054.001.11">
  <BkToCstmrDbtCdtNtfctn>
    <GrpHdr>
      <MsgId>JIL-NTF-E7C2D4A1</MsgId>
      <CreDtTm>2026-02-09T14:30:01.234Z</CreDtTm>
    </GrpHdr>
    <Ntfctn>
      <Id>NTF-tx_0x7f3a8b2c</Id>
      <Acct>
        <Id><Othr><Id>jil_acct_receiver_002</Id></Othr></Id>
        <Svcr><FinInstnId><BICFI>JILSOVUS</BICFI></FinInstnId></Svcr>
      </Acct>
      <Ntry>
        <NtryRef>tx_0x7f3a8b2c9d1e</NtryRef>
        <Amt Ccy="USD">50000.00</Amt>
        <CdtDbtInd>CRDT</CdtDbtInd>
        <Sts><Cd>BOOK</Cd></Sts>
        <BookgDt><Dt>2026-02-09</Dt></BookgDt>
        <ValDt><Dt>2026-02-09</Dt></ValDt>
      </Ntry>
    </Ntfctn>
  </BkToCstmrDbtCdtNtfctn>
</Document>

8. Integration Guide

This section provides a step-by-step guide for banks and financial institutions integrating with the JIL ISO 20022 Gateway. The integration assumes the FI has standard ISO 20022 processing capability (which all SWIFT-connected banks do).

8.1 Prerequisites

• API credentials issued by JIL Sovereign (contact contact@jilsovereign.com)
• Network connectivity to the gateway endpoint (port 8651)
• ISO 20022 message processing capability (standard for SWIFT members)
• WebSocket client library for real-time notifications (optional)

8.2 Integration Steps

1. Obtain API Credentials - Contact JIL Sovereign to provision your institution's API key and register your BIC code in the gateway's routing table.
2. Initiate Settlement via pain.001 - POST a pain.001 message (JSON or XML) to /v1/pain001 to initiate a credit transfer. The gateway validates, maps, and forwards to the JIL settlement layer. You receive a compliant pain.001 XML response with the settlement ID.
3. Poll Account Statements via camt.053 - GET /v1/camt053?account=<id> to retrieve a standards-compliant account statement with balances and transaction history. Supports date range filtering with from and to parameters.
4. Subscribe to Real-Time Notifications via camt.054 - Connect to the WebSocket endpoint at /v1/camt054 and subscribe to accounts. Receive instant ISO 20022 XML notifications for every debit and credit event as settlements finalize on-chain.
5. Interbank Transfers via pacs.008 - For FI-to-FI transfers, use POST /v1/pacs008 with instructing and instructed agent BICs. This enables multi-bank settlement routing through the JIL network.
6. Monitor and Reconcile - Use the /health endpoint for uptime monitoring and /v1/message-types for integration discovery. Reconcile against camt.053 statements using NtryRef (Entry Reference) as the join key.

9. Asset to Currency Mapping

The gateway maps JIL native asset codes to ISO 4217 currency codes (or crypto-specific codes where no ISO 4217 equivalent exists). This mapping is applied automatically to all Ccy (Currency) attributes in outbound XML messages.

10. Service Integration

The ISO 20022 Gateway connects to four upstream JIL services. Each connection is configured via environment variables and validated at startup using Zod schema validation.

10.1 Configuration

10.2 Technology Stack

• Runtime: Node.js with Express
• Validation: Zod (JSON input), fast-xml-parser (XML parsing and building)
• WebSocket: ws library for camt.054 push notifications
• Logging: Pino structured logging
• Messaging: Kafka (RedPanda) consumer for settlement events
• Container: Docker, deployable via docker-compose alongside other JIL services