as4-411/docs/protocols/iso20022-over-as4.md

ISO 20022 over AS4 (FI-to-FI)

Canonical reference for ISO 20022 messages transported via AS4 between financial institutions. Used by gateway teams, auditors, and scheme designers. as4-411 provides directory and resolution only; it does not parse ISO 20022, perform settlement, or replace AS4 MSH (see ADR-000).

---

1. Overview and layer model

ISO 20022 is the business payload (pacs, camt); AS4 (ebMS 3.0) is the messaging envelope; HTTPS is the transport. Identity-based addressing: PartyId (BIC, LEI) is resolved by the directory to endpoint URL, certificates, and profile. No URL in the envelope—only PartyId.

flowchart TB
  subgraph business [Business Layer]
    ISO20022["ISO 20022 XML (pacs, camt)"]
  end
  subgraph messaging [Messaging Layer]
    AS4["ebMS 3.0 / AS4 Envelope"]
    AS4_detail["PartyId, Service, Action, MPC, Receipts"]
  end
  subgraph transport [Transport Layer]
    HTTPS["HTTPS + TLS"]
  end
  ISO20022 --> AS4
  AS4 --> AS4_detail
  AS4_detail --> HTTPS

Principle: ISO 20022 never handles transport. AS4 never interprets business content.

---

2. Message classes (pacs, camt)

ISO 20022 Message	Description
pacs.008	Customer Credit Transfer
pacs.009	Financial Institution Credit Transfer
pacs.002	Payment Status
camt.056	Payment Cancellation
camt.029	Resolution of Investigation
camt.053	Statement
camt.054	Debit/Credit Notification

Payload: XML, UTF-8, strict XSD validation. May include BICs, LEIs, clearing member IDs. AS4 treats payload as opaque.

---

3. AS4 envelope mapping

ebMS headers: From.PartyId, To.PartyId, Service, Action, ConversationId, MessageId, MPC. Profile ID: as4.fifi.iso20022.v1. Service: iso20022.fi. Action: one per ISO 20022 message type (see §4).

Header skeleton (simplified):

<eb:Messaging>
  <eb:UserMessage>
    <eb:MessageInfo>
      <eb:MessageId>uuid</eb:MessageId>
      <eb:ConversationId>business-id</eb:ConversationId>
    </eb:MessageInfo>

    <eb:PartyInfo>
      <eb:From>
        <eb:PartyId type="BIC">BANKDEFFXXX</eb:PartyId>
      </eb:From>
      <eb:To>
        <eb:PartyId type="BIC">BANKUS33XXX</eb:PartyId>
      </eb:To>
    </eb:PartyInfo>

    <eb:CollaborationInfo>
      <eb:Service>iso20022.fi</eb:Service>
      <eb:Action>credit.transfer</eb:Action>
    </eb:CollaborationInfo>

    <eb:PayloadInfo>
      <eb:PartInfo href="cid:pacs008.xml"/>
    </eb:PayloadInfo>
  </eb:UserMessage>
</eb:Messaging>

Payload: detached MIME; signed → encrypted → attached. Full sample: iso20022-as4-sample-envelope.xml.

---

4. Addressing and identity

• PartyId types: BIC, LEI, internal.bank.code, scheme-specific (e.g. TARGET2, RTGS).
• Directory: maps PartyId → HTTPS endpoint URL + transport profile + receiver encryption cert + receipt requirements. Profile: as4.fifi.iso20022.v1.
• Discovery is directory-driven (contractual or internal); no public “discover any BIC” without directory data. See data-model (as4.partyId, scope/partyIdType).

AS4 FI-to-FI profile definition

Feature	Requirement
ebMS Version	ebMS 3.0
Transport	HTTPS
Payload	ISO 20022 XML
Signing	Mandatory
Encryption	Mandatory
Receipts	Signed Receipts
Duplicate Detection	Enabled
Reliability	Exactly-once delivery

MPC usage

MPC	Purpose
default	Normal traffic
urgent	Time-critical payments
bulk	High-volume settlement batches

Service / Action taxonomy

Service namespace: iso20022.fi. Rule: one ISO 20022 message type = one AS4 Action.

ISO 20022 Message	Action
pacs.008	credit.transfer
pacs.009	fi.credit.transfer
pacs.002	payment.status
camt.056	payment.cancellation
camt.029	resolution.of.investigation
camt.053	statement
camt.054	notification

---

5. Security model

• Message-level: XML Digital Signature (sender), XML Encryption (receiver); mandatory for profile as4.fifi.iso20022.v1. Optional compression.
• Transport: HTTPS, TLS; optional mTLS; network allowlisting.
• See key-reference-model.

---

6. Reliability and receipts

• Signed receipts required (non-repudiation).
• Duplicate detection enabled.
• Exactly-once delivery per profile.
• Retries on transient failure; receipt stored by sender.

---

7. Processing lifecycle

ISO 20022 XML created
        ↓
AS4 envelope built (PartyId, Service, Action)
        ↓
Directory resolves PartyId → endpoint + cert
        ↓
AS4 signs + encrypts
        ↓
HTTPS transmission
        ↓
Receiver AS4 gateway validates + decrypts
        ↓
ISO 20022 payload extracted
        ↓
ISO 20022 engine processes message

---

8. Error separation (transport vs business)

Layer	Handled by	Examples
Transport	AS4 only	Retries, receipts, duplicate suppression.
Business	ISO 20022	pacs.002 (status), camt.056 (cancellation), scheme rejects.

Never mix transport errors with business rejects.

---

9. as4-411 integration

Provides: PartyId → endpoint resolution; Service/Action constraints; certificate references; multi-rail identity (BIC ↔ LEI ↔ internal); deterministic, auditable routing directives.

Does not: Parse ISO 20022; perform settlement; replace AS4 MSH.

---

10. Compliance and audit notes

• Receipts and resolution_trace support audit (which source contributed the directive).
• BIC/LEI are Tier 0/1 per data-classification.
• Who may call resolve and what they see: trust-model.

---

11. Sample AS4 envelopes

See §3 for header skeleton. Full anonymized envelope: iso20022-as4-sample-envelope.xml. Resolution examples: ../examples/iso20022-as4-resolution-examples.yaml.

---

12. as4-411 resolution examples

Example 1 — BIC-based resolution

Input

• To.PartyId = BANKUS33XXX
• PartyIdType = BIC
• Service = iso20022.fi
• Action = credit.transfer

Resolution output

• Endpoint: https://as4.bankus.com/fi
• EncryptionCert: vault://certs/bankus/iso20022
• Profile: as4.fifi.iso20022.v1
• Receipts: signed

Example 2 — LEI-based resolution

Input

• To.PartyId = 5493001KJTIIGC8Y1R12
• PartyIdType = LEI

Mapping

• LEI → BIC(s) → AS4 Endpoint

Output

• Same directive structure as BIC.
• Evidence includes LEI→BIC mapping source.

(JSON request/response shapes in ../examples/iso20022-as4-resolution-examples.yaml and OpenAPI.)

---

13. RTGS-specific nuances

• Characteristics: Real-time settlement, tight SLA windows, liquidity constraints.
• AS4 adjustments:

Aspect	RTGS requirement
MPC	urgent
Retry	Minimal / controlled
Timeouts	Aggressive
Receipts	Mandatory, immediate

• Message patterns: pacs.008 / pacs.009; immediate pacs.002 response expected.

---

14. Cross-border correspondent banking

• Topology: Bank A → Correspondent X → Correspondent Y → Bank B.
• as4-411 role: Resolve next hop, not final destination; maintain correspondent routing tables; apply jurisdiction and currency policies.
• Envelope: Each hop = new AS4 envelope; business ConversationId preserved; transport MessageId regenerated.

---

15. CBDC / tokenized settlement overlays

• Overlay model: ISO 20022 remains the instruction layer; token/CBDC rails provide the settlement layer.
• Directory extensions: Map PartyId → wallet/DLT endpoint; store settlement rail capability (RTGS, CBDC, tokenized deposit). See cbdc-settlement-adapter.
• Dual-track: ISO 20022 instruction → AS4 transport → settlement adapter (RTGS or CBDC ledger).

---

16. Appendix: ISO 20022 over AS4 vs over API

Dimension	AS4	API
Reliability	Guaranteed	Best-effort
Non-repudiation	Built-in	Custom
Identity	PartyId-based	URL/token-based
Audit	Native	Add-on
Regulatory fit	High	Medium
Latency	Higher	Lower

Guidance: AS4 for interbank, regulated, cross-border. API for internal, fintech, low-latency. Hybrid: API inside the bank; AS4 between banks.

---

17. Rail-template alignment

Section	Content
Owner/authority	ISO 20022, OASIS ebMS 3.0 / AS4; as4-411 directory only.
Identifier scheme	BIC, LEI; as4.partyId with scope/partyIdType.
Addressing	HTTPS endpoint; profile as4.fifi.iso20022.v1.
Security	Mandatory sign + encrypt; HTTPS; optional mTLS.
Discovery	Directory-driven; no public discover-any-BIC.
Compliance	data-classification (BIC/LEI Tier 0/1).
Sample payloads	§11–12; test-vectors and scheme profiles.

Scheme-specific profiles (TARGET2, Fedwire, CHAPS): iso20022-scheme-profiles.md.