300 lines
9.3 KiB
Markdown
300 lines
9.3 KiB
Markdown
# 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).
|