
Secure ISO 20022 API Microgateway for Cross-Border Payments
Designing a payment translation service from requirements to deployment.
1. What I’m Building & Why
The Scenario
You’re a Solutions Architect at a commercial bank. The bank has 200,000+ customers sending and receiving money internationally. The legacy system crashes weekly, payments take days, and the regulator says: “Adopt ISO 20022 or lose your license.”
The CEO asks: “Can you build a system that takes requests from our app, produces correct international payment messages, and won’t get us fined?”
What is ISO 20022?
The global standard format banks use to communicate. Think of it as a structured shipping label for money.
Old Way (MT messages)New Way (ISO 20022)Free-text, vagueStructured, machine-readable~100 data fields7,000+ data fieldsHard to traceEvery step tracked
What is pacs.008?
The specific message type for: “Customer at Bank A wants to send money to someone at Bank B.”
What is a Microgateway?
A small service that does one job: takes JSON from your app and outputs valid ISO 20022 XML for the payment network.
App (JSON) → Microgateway → ISO 20022 XML → Bank Network2. The Solutions Architect Role
The SA sits between business and engineering understanding both, making decisions that affect the whole system.
ActivityTimeExampleStakeholder meetings30%Explaining trade-offs, gathering requirementsArchitecture design25%Diagrams, technology choicesTechnical review20%Reviewing code and infra plansDocumentation15%Decision records, runbooksHands-on building10%Prototypes, proof-of-concepts
What this project demonstrates:
SkillHow It’s ShownRequirements gatheringStakeholder interviews, requirement tablesArchitecture designVPC, EKS, multi-AZ, auto-scalingSecurity thinkingInput validation, no sensitive logs, zero-trustInfrastructure as CodeTerraformTesting strategy27 tests covering all pathsBusiness communicationExecutive summary, ROI calculations
3. Phase 0: Requirements
Stakeholder Interviews (Simulated)
CFO: “We lose $500K/year on payment failures. Cut error rate from 8% to under 1%.”
CISO: “Zero-trust. No sensitive data in logs. Encryption everywhere.”
Compliance Officer: “7-year audit trail. Every message traceable. Fines for non-compliance are 10% of annual turnover.”
Head of Operations: “Peak: 50 transactions/second at end-of-month. 99.95% uptime required.”
Functional Requirements
IDRequirementPriorityFR-01Accept JSON payment requests via APIMust-haveFR-02Validate all input fieldsMust-haveFR-03Generate pacs.008 XMLMust-haveFR-04Return unique tracking IDsMust-haveFR-05Support multiple currencies (EUR, USD, GBP, KES, JPY)Must-have
Non-Functional Requirements
IDRequirementTargetNFR-01Response time< 200msNFR-02Throughput50 TPS peakNFR-03Availability99.95%NFR-04Data retention7 yearsNFR-05Recovery time< 30 minutes
Architecture Decision: Cloud Provider
OptionScoreRationaleAWS9/10Team skills, broad services, enterprise supportAzure7/10Good compliance tools, less regional presenceGCP6/10Best K8s, smallest enterprise footprint
Decision: AWS.
4. Phase 1: Infrastructure
Architecture Overview

Key Design Decisions
DecisionWhyPrivate subnets for appNo direct internet exposureMulti-AZ (3 availability zones)Survives data center failureON_DEMAND instancesFinancial workloads need reliabilityEKS managed nodesAWS handles patchingNAT GatewayOutbound only — internet can’t reach in
What the Terraform Creates
The
terraform/main.tf provisions:- VPC (
rare-bank-vpc) with public/private subnets across 3 AZs
- EKS cluster (
payment-microgateway) with auto-scaling (1–10 nodes)
- S3 backend for state with DynamoDB locking
- Environment-aware config (dev/staging/production)

5. Phase 2: Payment Logic
Data Flow
Mobile App (JSON) → Validate → Generate IDs → Build XML → Return Response │ ▼ Audit Log (hash)Input (JSON from the mobile app)
{ "sender_name": "John Doe", "sender_account": "RA1234567890123456", "sender_bic": "RCBKRAXX", "receiver_name": "Elijah Chimera", "receiver_account": "RA29CBRR60161331926819", "receiver_bic": "CBRARERX", "amount": 1250.50, "currency": "EUR", "purpose_code": "SALA", "remittance_info": "Invoice #12345 - Consulting Services"}


Field Mapping
JSON FieldXML ElementValidationsender_name
<Dbtr><Nm> 1–140 charssender_account <DbtrAcct><Id><Othr><Id> Min 5 chars, spaces strippedsender_bic <DbtrAgt><FinInstnId><BICFI> 8 or 11 chars, uppercase (Fleet Code)receiver_name <Cdtr><Nm> 1–140 charsreceiver_account <CdtrAcct><Id><Othr><Id> Min 5 chars, spaces strippedreceiver_bic <CdtrAgt><FinInstnId><BICFI> 8 or 11 chars, uppercase (Fleet Code)amount <IntrBkSttlmAmt> > 0, ≤ 999,999,999.99currency Ccy attribute3 chars, ISO 4217purpose_code <Purp><Cd> 4 uppercase chars (optional)remittance_info <RmtInf><Ustrd> Max 140 chars (optional)Application Layers
┌─────────────────────────────────┐│ MIDDLEWARE (CORS, timing) │├─────────────────────────────────┤│ VALIDATION (Pydantic) │├─────────────────────────────────┤│ PROCESSING (IDs, XML, hash) │├─────────────────────────────────┤│ RESPONSE (JSON + error format) │└─────────────────────────────────┘
Key Code Concepts
Fleet Code validation regex:
^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$ - 6 uppercase letters (bank + country) + 2 alphanumeric (location) + optional 3 (branch)
- Valid:
RCBKRAXX(8 chars),CBRARERXXXX(11 chars)
- Invalid:
cbrarerx(lowercase),RCBL(too short)
XML namespace:
urn:iso:std:iso:20022:tech:xsd:pacs.008.001.08 - Without this, payment networks reject the message entirely.
Audit hash: SHA-256 of partial data — creates a traceable fingerprint without exposing sensitive details.
Output (ISO 20022 XML)
<?xml version="1.0" ?><Document xmlns="urn:iso:std:iso:20022:tech:xsd:pacs.008.001.08" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <FIToFICstmrCdtTrf> <GrpHdr> <MsgId>MSG7A3F2B...</MsgId> <CreDtTm>2025-01-15T10:30:00.000Z</CreDtTm> <NbOfTxs>1</NbOfTxs> <SttlmInf> <SttlmMtd>CLRG</SttlmMtd> </SttlmInf> </GrpHdr> <CdtTrfTxInf> <IntrBkSttlmAmt Ccy="EUR">1250.50</IntrBkSttlmAmt> <ChrgBr>SLEV</ChrgBr> <Dbtr><Nm>John Doe</Nm></Dbtr> <CdtrAgt><FinInstnId><BICFI>CBRARERX</BICFI></FinInstnId></CdtrAgt> <Cdtr><Nm>Elijah Chimera</Nm></Cdtr> </CdtTrfTxInf> </FIToFICstmrCdtTrf></Document>
Dockerfile
Multi-stage build:
- Builder stage — installs dependencies with compilers
- Runtime stage — minimal image, non-root user (
appuser), health check
Runs with 4 Uvicorn workers in production.
6. Phase 3: Security
Defense in Depth


LayerProtectionPerimeterWAF, rate limiting, TLS 1.3NetworkVPC isolation, private subnets, security groupsApplicationPydantic validation (Fleet Code format, amount range, name length)DataEncryption at rest/transit, no sensitive data in logsMonitoringReal-time alerts, immutable audit trails
What Gets Logged vs. What Doesn’t
Log ThisNever Log ThisTimestamp, request IDFull account numbersHTTP status, durationCustomer namesCurrency, error typeExact amountsMessage ID (for tracing)Passwords, API keys
Example safe log from the app:
Payment request received | IP: 192.168.x.x | Currency: EUR | Amount: [REDACTED] | Sender: Joh*** | Receiver BIC: CBRA***
Key Alerts
- Error rate > 5% (CloudWatch alarm configured)
- p95 latency > 500ms
- CPU > 80% for 5 minutes
- Any 5xx in production
7. Phase 4: Testing
27 Tests Covering:
CategoryCountWhat It ProvesHealth & info2Service is aliveValid payments3Core flow works (full fields, minimal, 11-char Fleet Code)Amount validation3Rejects zero, negative, too-largeFleet Code validation2Rejects malformed, lowercaseCurrency handling3Validates length, auto-uppercases, formats XMLName validation3Handles empty, max-length, too-longPurpose/account2Format enforcementXML structure4Namespace, well-formed, formatting, roundingID generation2Unique IDs (
MSG prefix, 23 chars), proper hash (16 hex chars)Edge cases4Special chars, long names, IBAN spaces, multiple currenciesCORS1Cross-origin headers present

Deployment Strategy: Blue-Green
- Deploy new version (GREEN) alongside current (BLUE)
- Route 10% traffic to GREEN, monitor
- If metrics are good, shift to 100%
- Keep BLUE on standby for instant rollback

8. Phase 5: Business Communication
Executive Summary
MetricBeforeAfterAnnual ImpactError rate8%< 1%$435K savingsSettlement time2–5 days< 4 hoursBetter cash flowManual work40 hrs/week4 hrs/week$187K savingsInfra cost$800K (mainframe)$200K (cloud)$600K savings
Investment: $180K initial + $70K/year
ROI: 340% in Year 1
Technology Choices
ChoiceWhyAWS EKSTeam has Kubernetes skills, mature ecosystemFastAPIFast, auto-generates API docs, modern PythonTerraformReproducible infra, version-controlled, team collaboration via S3 statePythonRapid development, good for data transformation

9. Running It Yourself
# Clone and setupgit clone https://github.com/Chimelijah/iso-20022.gitcd iso20022-microgatewaypython -m venv venvsource venv/bin/activatepip install -r requirements.txt
# Run tests (all 27 should pass)pytest -v# Start serveruvicorn main:app --reload# Docs at http://localhost:8000/docsTest a payment:
curl -X POST http://localhost:8000/api/v1/payments/transfer \ -H "Content-Type: application/json" \ -d '{ "sender_name": "John Doe", "sender_account": "RA1234567890123456", "sender_bic": "RCBKRAXX", "receiver_name": "Elijah Chimera", "receiver_account": "RA29CBRR60161331926819", "receiver_bic": "CBRARERX", "amount": 1250.50, "currency": "EUR", "purpose_code": "SALA", "remittance_info": "Invoice #12345 - Consulting Services" }'Docker:
docker build -t iso-gateway .docker run -p 8000:8000 iso-gatewayTo see the live demo run the following locally.
cd /home/chimera/Downloads/iso20022-microgatewaysource venv/bin/activatepython live_demo.py10. Q and A
Q: Why ISO 20022 over MT messages?
Regulatory mandate, richer data (7000+ fields vs 100), and it’s the global standard for instant payments and open banking.
Q: Why Kubernetes?
Team expertise, consistent tooling for multi-region expansion, and future microservices. For smaller scale, ECS or Lambda would also work.
Q: How do you handle mid-processing failures?
Idempotency keys + state machine. Each payment transitions through states (RECEIVED → VALIDATED → SUBMITTED → SETTLED). Failures resume from last known state.
Q: How do you prioritize when everything is urgent?
Impact × Urgency. “If we do nothing for 24 hours, what breaks?” Document the rationale, get stakeholder sign-off on trade-offs.
Tech Stack
Python 3.12+ · FastAPI · Pydantic · Docker · Terraform · GitHub Actions · Pytest
Disclaimer
Portfolio/learning project only. Does not process real money or connect to any live payment network.
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article