# 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](../adr/000-scope-and-non-goals.md)).

---

## 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.

```mermaid
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):

```xml
<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](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](../architecture/data-model.md) (`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](../security/key-reference-model.md).

---

## 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](../security/data-classification.md).
- Who may call resolve and what they see: [trust-model](../security/trust-model.md).

---

## 11. Sample AS4 envelopes

See §3 for header skeleton. Full anonymized envelope: [iso20022-as4-sample-envelope.xml](iso20022-as4-sample-envelope.xml). Resolution examples: [../examples/iso20022-as4-resolution-examples.yaml](../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](../examples/iso20022-as4-resolution-examples.yaml) and [OpenAPI](../api/openapi.yaml).)

---

## 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](../architecture/cbdc-settlement-adapter.md).
- **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](iso20022-scheme-profiles.md).