--- name: open-banking-iso20022-apis description: Architect enterprise Open Banking platforms, PSD2/PSD3 compliant APIs, financial message modeling in ISO 20022 (pacs.008, camt.053, pain.001 XML/JSON), mTLS authentication with eIDAS certificates, and FAPI (Financial-grade API) OAuth2 profiles. --- # Open Banking & ISO 20022 APIs Architecture This skill package defines architectural guidelines, security controls, and production implementations for building **Open Banking platforms**, **PSD2/PSD3 compliant Payment Initiation (PISP) and Account Information (AISP) services**, and **ISO 20022 financial messaging engines**. --- ## 1. Security Architecture & Standards ### FAPI (Financial-grade API 1.0/2.0) & OAuth 2.0 Security Profile - **Client Authentication**: Enforce Mutual TLS (`tls_client_auth`) or `private_key_jwt` with asymmetric RSA-SHA256 (PS256) or ECDSA (ES256) key pairs. - **Pushed Authorization Requests (PAR - RFC 9126)**: PISPs/AISPs must push authorization request parameters directly to the ASPSP authorization server via back-channel POST requests, obtaining an opaque `request_uri` to prevent front-channel tampering. - **JWS Signature & Non-Repudiation**: Payment initiation payloads must include detached HTTP Message Signatures (RFC 9421) signed with **eIDAS QSealC (Qualified Electronic Seal Certificates)**. ### mTLS & eIDAS Certificate Validation - **Transport Security**: Enforce mutual TLS 1.3 using **eIDAS QWAC (Qualified Website Authentication Certificates)** to establish identity between Third-Party Providers (TPPs) and Account Servicing Payment Service Providers (ASPSPs). - **Certificate Revocation Checking**: Validate TPP certificate status in real-time via OCSP stapling and CRL (Certificate Revocation List) checks against Qualified Trust Service Providers (QTSPs). --- ## 2. ISO 20022 Financial Messaging Matrix | Message Identifier | Name | Domain | Primary Purpose | | :--- | :--- | :--- | :--- | | **`pain.001.001.11`** | Customer Credit Transfer Initiation | Payments | TPP/Corporate initiates credit transfer to bank | | **`pacs.008.001.10`** | FI to FI Customer Credit Transfer | Clearing & Settlement | Interbank real-time settlement (SEPA Instant, FedNow) | | **`camt.053.001.10`** | Bank to Customer Statement | Account Management | Daily end-of-day account balance & statement | | **`camt.054.001.10`** | Bank to Customer Debit/Credit Notification | Notifications | Real-time transaction notification advisory | | **`pacs.002.001.12`** | Payment Status Report | Status Tracking | Real-time ACK/NACK status of payment processing | --- ## 3. Production Code Implementations ### Python Implementation: ISO 20022 `pain.001` XML Builder & Schema Validator ```python import datetime import hashlib import xml.etree.ElementTree as ET from xml.dom import minidom from typing import Dict, Any class ISO20022Pain001Builder: """ Constructs ISO 20022 pain.001.001.11 Credit Transfer Initiation XML documents """ NS_PAIN = "urn:iso:std:iso:20022:tech:xsd:pain.001.001.11" def __init__(self, msg_id: str, initiating_party_name: str): self.msg_id = msg_id self.initiating_party_name = initiating_party_name def build_credit_transfer_xml(self, pmt_inf_id: str, debtor: Dict[str, str], creditor: Dict[str, str], amount: float, currency: str) -> str: ET.register_namespace('', self.NS_PAIN) doc = ET.Element("Document", xmlns=self.NS_PAIN) cstmr_pmt_init = ET.SubElement(doc, "CstmrPmtSttmtReq") # Group Header grp_hdr = ET.SubElement(cstmr_pmt_init, "GrpHdr") ET.SubElement(grp_hdr, "MsgId").text = self.msg_id ET.SubElement(grp_hdr, "CreDtTm").text = datetime.datetime.utcnow().isoformat() + "Z" ET.SubElement(grp_hdr, "NbOfTxs").text = "1" ET.SubElement(grp_hdr, "CtrlSum").text = f"{amount:.2f}" initg_pty = ET.SubElement(grp_hdr, "InitgPty") ET.SubElement(initg_pty, "Nm").text = self.initiating_party_name # Payment Information pmt_inf = ET.SubElement(cstmr_pmt_init, "PmtInf") ET.SubElement(pmt_inf, "PmtInfId").text = pmt_inf_id ET.SubElement(pmt_inf, "PmtMtd").text = "TRF" ET.SubElement(pmt_inf, "NbOfTxs").text = "1" ET.SubElement(pmt_inf, "CtrlSum").text = f"{amount:.2f}" # Debtor Info dbtr = ET.SubElement(pmt_inf, "Dbtr") ET.SubElement(dbtr, "Nm").text = debtor["name"] dbtr_acct = ET.SubElement(pmt_inf, "DbtrAcct") dbtr_id = ET.SubElement(dbtr_acct, "Id") ET.SubElement(dbtr_id, "IBAN").text = debtor["iban"] dbtr_agt = ET.SubElement(pmt_inf, "DbtrAgt") fin_inst_dbtr = ET.SubElement(dbtr_agt, "FinInstnId") ET.SubElement(fin_inst_dbtr, "BICFI").text = debtor["bic"] # Credit Transfer Transaction Information cdt_trf_tx_inf = ET.SubElement(pmt_inf, "CdtTrfTxInf") pmt_id = ET.SubElement(cdt_trf_tx_inf, "PmtId") ET.SubElement(pmt_id, "EndToEndId").text = f"E2E-{pmt_inf_id}" amt = ET.SubElement(cdt_trf_tx_inf, "Amt") instd_amt = ET.SubElement(amt, "InstdAmt", Ccy=currency) instd_amt.text = f"{amount:.2f}" cdtr_agt = ET.SubElement(cdt_trf_tx_inf, "CdtrAgt") fin_inst_cdtr = ET.SubElement(cdtr_agt, "FinInstnId") ET.SubElement(fin_inst_cdtr, "BICFI").text = creditor["bic"] cdtr = ET.SubElement(cdt_trf_tx_inf, "Cdtr") ET.SubElement(cdtr, "Nm").text = creditor["name"] cdtr_acct = ET.SubElement(cdt_trf_tx_inf, "CdtrAcct") cdtr_id = ET.SubElement(cdtr_acct, "Id") ET.SubElement(cdtr_id, "IBAN").text = creditor["iban"] raw_xml = ET.tostring(doc, encoding="utf-8") parsed = minidom.parseString(raw_xml) return parsed.toprettyxml(indent=" ") def compute_sha256_digest(self, xml_content: str) -> str: """Computes SHA-256 digest for eIDAS JWS HTTP Digest Header""" digest = hashlib.sha256(xml_content.encode("utf-8")).digest() import base64 return f"SHA-256={base64.b64encode(digest).decode('utf-8')}" ``` --- ### TypeScript Implementation: FAPI 1.0 Advanced Client with Private Key JWT & Signature Interceptor ```typescript import crypto from 'crypto'; import fs from 'fs'; export interface FapiClientConfig { clientId: string; tokenEndpoint: string; privateKeyPath: string; keyId: string; } export class FapiAdvancedAuthClient { private config: FapiClientConfig; private privateKeyPem: string; constructor(config: FapiClientConfig) { this.config = config; this.privateKeyPem = fs.readFileSync(config.privateKeyPath, 'utf8'); } /** * Generates a signed Client Assertion JWT for private_key_jwt authentication (RFC 7523) */ public generateClientAssertion(): string { const now = Math.floor(Date.now() / 1000); const header = { alg: 'PS256', typ: 'JWT', kid: this.config.keyId, }; const payload = { iss: this.config.clientId, sub: this.config.clientId, aud: this.config.tokenEndpoint, jti: crypto.randomUUID(), exp: now + 300, iat: now, }; const encodedHeader = this.base64UrlEncode(JSON.stringify(header)); const encodedPayload = this.base64UrlEncode(JSON.stringify(payload)); const dataToSign = `${encodedHeader}.${encodedPayload}`; const signer = crypto.createSign('RSA-SHA256'); signer.update(dataToSign); signer.end(); const signature = signer.sign({ key: this.privateKeyPem, padding: crypto.constants.RSA_PKCS1_PSS_PADDING, saltLength: crypto.constants.RSA_PSS_SALTLEN_DIGEST, }); return `${dataToSign}.${this.base64UrlEncode(signature)}`; } /** * Sign Open Banking HTTP Request with RFC 9421 HTTP Message Signatures (eIDAS QSealC) */ public createSignedHttpHeaders(httpMethod: string, requestPath: string, bodyPayload: string): Record { const digest = 'SHA-256=' + crypto.createHash('sha256').update(bodyPayload).digest('base64'); const xFapiInteractionId = crypto.randomUUID(); const dateHeader = new Date().toUTCString(); const signatureInputStr = `"(request-target)": ${httpMethod.toLowerCase()} ${requestPath}\n"host": api.bank.com\n"date": ${dateHeader}\n"digest": ${digest}\n"x-fapi-interaction-id": ${xFapiInteractionId}`; const signer = crypto.createSign('RSA-SHA256'); signer.update(signatureInputStr); const signature = signer.sign(this.privateKeyPem, 'base64'); return { 'Digest': digest, 'Date': dateHeader, 'x-fapi-interaction-id': xFapiInteractionId, 'Signature': `keyId="${this.config.keyId}",algorithm="rsa-sha256",headers="(request-target) host date digest x-fapi-interaction-id",signature="${signature}"`, }; } private base64UrlEncode(input: string | Buffer): string { const buf = typeof input === 'string' ? Buffer.from(input) : input; return buf.toString('base64').replace(/=/g, '').replace(/\+/g, '-').replace(/\//g, '_'); } } ``` --- ## 4. Anti-Patterns & Critical Mistakes 1. **Failure to Perform XML Schema (XSD) Validation Prior to Parsing** - *Impact*: Vulnerability to XML External Entity (XXE) injection attacks and unexpected XML expansion attacks (Billion Laughs). - *Remediation*: Disable external DTD resolution (`resolve_entities=False`) and validate all incoming ISO 20022 XML against official ISO XSD schemas before business processing. 2. **Passing Dynamic Auth Parameters via Front-Channel Authorize Endpoint** - *Impact*: Vulnerable to Authorization Code injection and parameter tampering. - *Remediation*: Require FAPI Pushed Authorization Requests (PAR) to exchange parameters back-channel for an opaque `request_uri`. 3. **Treating IBAN Validation as a Simple Regex Match** - *Impact*: False positives and failed SEPA payments due to missing MOD-97 check digit calculations. - *Remediation*: Always execute MOD-97 checksum algorithm verification on IBAN strings prior to generating `pain.001` or `pacs.008` messages. 4. **Omitting `x-fapi-interaction-id` Tracing Headers** - *Impact*: Non-compliance with Open Banking auditing mandates, leading to untraceable dispute handling between TPP and ASPSP. - *Remediation*: Inject and log unique UUID v4 `x-fapi-interaction-id` headers across all HTTP client requests and server logs. --- ## 5. Verification & Testing Playbook - **ISO 20022 XSD Validation CLI**: ```bash xmllint --schema pain.001.001.11.xsd payment_initiation.xml --noout ``` - **Open Banking Conformance Suite**: Run official OIDF (OpenID Foundation) FAPI 1.0 Advanced test suite against the OAuth 2.0 authorization server. - **eIDAS QSealC Signature Verification**: Verify detached HTTP signatures using OpenSSL and public QSealC certificate chains.