External adapter specifications and integration patterns for Kovra.
Architecture: 01_ARCHITECTURE.md | Components: 02_COMPONENTS.md | Deployment: 04_DEPLOYMENT.md
This document specifies how Kovra integrates with external payment rails and services. Key principle: All integrations are optional enhancements—core Kovra functionality works 100% standalone.
┌─────────────────────────────────────────────────────────────────┐
│ INTEGRATION ARCHITECTURE (Optional) │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Kovra │ │ Adapter │ │ External │ │
│ │ Core │◄────►│ Layer │◄────►│ Service │ │
│ │ │ │ │ │ │ │
│ │ • Works │ │ • Protocol │ │ • BI-FAST │ │
│ │ standalone │ │ translation│ │ • SEPA │ │
│ │ • Local │ │ • Auth │ │ • FPS │ │
│ │ sanctions │ │ handling │ │ • External │ │
│ │ • Internal │ │ • Error │ │ FX feeds │ │
│ │ FX calc │ │ mapping │ │ │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │
│ NOTE: Adapter layer is swappable. Kovra Core has ZERO hard │
│ dependencies on external services. Can disable all external │
│ integrations and still process payments using local data. │
│ │
└─────────────────────────────────────────────────────────────────┘
| Mechanism | Purpose | Required |
|---|---|---|
| mTLS | Mutual authentication | Yes |
| JWS | Message signing | Yes |
| Idempotency Key | Duplicate prevention | Yes |
| Request ID | Tracing/debugging | Yes |
| TLS 1.2+ | Transport security | Minimum |
Note: Only required if integrating with EU banks. Kovra core can function without this.
| Mechanism | Purpose |
|---|---|
| OAuth 2.0 + PAR | Authorization |
| DPoP | Mobile/SPA security |
| private_key_jwt | Client authentication |
| PKCE (S256) | Code exchange |
| State parameter | CSRF protection |
| JARM | Response signing |
| Mechanism | Purpose |
|---|---|
| UK FAPI | FCA compliance |
| OAuth 2.0 + enhanced | Additional security |
| Faster Payments/CHAPS auth | Rail-specific |
| Mechanism | Purpose |
|---|---|
| PKI Certificate Auth | Strong authentication |
| FedLine VPN/WAN | Secure connectivity |
| ISO 20022 Message Signing | Message integrity |
1. Quote API → Lock FX rate (10 min TTL)
2. Recipient API → Validate destination
3. Compliance Check → AML/sanctions (local first)
4. Transfer API → Execute payment
Note: Compliance check uses local database first. External screening is async enhancement.
| Format | Rails | Notes |
|---|---|---|
| ISO 20022 | FedNow, SEPA, BI-FAST, CHAPS | Standard format |
| Custom JSON | Wise-style APIs | Flexible mapping |
| SNAP JSON | Indonesia BI-FAST | Local standard |
- Transaction status updates - Real-time notifications
- JWS signature verification - Authenticity check
- Retry logic - Exponential backoff (1s, 2s, 4s, 8s...)
- DLQ - Dead letter queue after 10 failures
Target Corridor: Primary (Phase 1)
┌─────────────────────────────────────────────────────────────┐
│ INDONESIA ADAPTER │
├─────────────────────────────────────────────────────────────┤
│ │
│ Authentication: │
│ ├── OAuth 2.0 + X-SIGNATURE (HMAC-SHA512) │
│ └── Certificate-based (for RTGS) │
│ │
│ Payment Rails: │
│ ├── BI-FAST (instant, < IDR 250M, < 30s settlement) │
│ ├── SKNBI (batch, lower priority) │
│ └── RTGS (large value, > IDR 250M, same day) │
│ │
│ Message Format: SNAP JSON payload │
│ │
│ Local Auth: │
│ └── SNAP (Standar Nasional Open API Pembayaran) │
│ │
│ Compliance: │
│ ├── OJK reporting (quarterly) │
│ ├── BI supervision (real-time monitoring) │
│ └── PPATK SAR (suspicious activity reports) │
│ │
│ Independence Note: │
│ • Can validate IBAN/format locally │
│ • BI-FAST connection = optional enhancement │
│ • Fallback: Queue for batch processing when BI-FAST down │
│ │
└─────────────────────────────────────────────────────────────┘
Integration Endpoints:
# Production
bi_fast_host: "https://api.bankindonesia.go.id"
snap_version: "2.0"
# Sandbox (for testing)
sandbox_host: "https://sandbox.bankindonesia.go.id"
sandbox_available: true # Register at BI Developer PortalTarget Corridor: Primary (Phase 1)
┌─────────────────────────────────────────────────────────────┐
│ EU ADAPTER │
├─────────────────────────────────────────────────────────────┤
│ │
│ Authentication: │
│ ├── FAPI 2.0 Security Profile │
│ ├── OAuth 2.0 + PAR (Pushed Authorization Requests) │
│ ├── DPoP (Demonstrating Proof-of-Possession) │
│ └── private_key_jwt (QSEALC certificates) │
│ │
│ Payment Rails: │
│ ├── SEPA Instant (< €100K, < 10s settlement) │
│ └── SEPA Credit Transfer (SCT, 1 business day) │
│ │
│ Message Format: ISO 20022 (pacs.008, pacs.002) │
│ │
│ Local Auth (per country): │
│ ├── Sweden: BankID │
│ ├── Denmark: MitID │
│ └── Other: Various national eIDs │
│ │
│ Sweden/Denmark Specifics: │
│ ├── Bankgiro/Plusgiro (Sweden domestic clearing) │
│ ├── Local clearing systems │
│ └── Nordic integration │
│ │
│ Compliance: │
│ ├── GDPR (data protection) │
│ ├── PSD2 (payment services) │
│ ├── SCA (strong customer auth) │
│ └── EU sanctions screening │
│ │
│ Independence Note: │
│ • EU sanctions list stored locally │
│ • SEPA connection = optional │
│ • Can batch payments for later SEPA submission │
│ │
└─────────────────────────────────────────────────────────────┘
Integration Endpoints:
# SEPA
sepa_instant_endpoint: "https://api.sepa.eu/instant"
sepa_sct_endpoint: "https://api.sepa.eu/sct"
# Sweden (BankID)
bankid_endpoint: "https://appapi2.test.bankid.com"
# Denmark (MitID)
mitid_endpoint: "https://pp.mitid.dk"Target Corridor: Primary (Phase 1)
┌─────────────────────────────────────────────────────────────┐
│ UK ADAPTER │
├─────────────────────────────────────────────────────────────┤
│ │
│ Authentication: │
│ ├── UK FAPI (FCA compliant) │
│ └── OAuth 2.0 + enhanced security │
│ │
│ Payment Rails: │
│ ├── Faster Payments (< £1M, < 2 hours settlement) │
│ ├── CHAPS (> £1M, same day settlement) │
│ └── SWIFT (for EU-UK corridor fallback) │
│ │
│ Message Format: ISO 20022 │
│ │
│ IMPORTANT NOTE: │
│ ├── NO SEPA access (post-Brexit) │
│ ├── Use SWIFT for EU-UK corridor │
│ └── Alternative routes via correspondent banks │
│ │
│ Compliance: │
│ ├── FCA regulations │
│ ├── UK sanctions (OFSI) │
│ └── Data protection (UK GDPR) │
│ │
│ Independence Note: │
│ • UK sanctions list stored locally │
│ • FPS/CHAPS = optional enhancement │
│ • Can queue UK payments for later processing │
│ │
└─────────────────────────────────────────────────────────────┘
Integration Endpoints:
# Faster Payments
fps_endpoint: "https://api.fasterpayments.co.uk"
# CHAPS
chaps_endpoint: "https://api.chaps.co.uk"Target Corridor: Secondary (Phase 3)
┌─────────────────────────────────────────────────────────────┐
│ US ADAPTER │
├─────────────────────────────────────────────────────────────┤
│ │
│ Authentication: │
│ ├── PKI Certificate Auth │
│ └── FedLine VPN/WAN connectivity │
│ │
│ Payment Rails: │
│ ├── FedNow (instant, 24/7) │
│ └── ACH (batch, 1-2 days) │
│ │
│ Message Format: ISO 20022 native │
│ │
│ Compliance: │
│ ├── OFAC sanctions │
│ ├── BSA/AML │
│ └── State regulations │
│ │
│ Status: NOT IMPLEMENTED (Phase 3) │
│ │
└─────────────────────────────────────────────────────────────┘
Local-First Approach:
Kovra Core
│
├─► Local Sanctions DB (OFAC, UN, EU, UK)
│ └── Result: ALLOW / BLOCK / REVIEW (< 100ms)
│
└─► External API (optional, async)
└── Enhanced screening (non-blocking)
Data Sources:
| Source | Local Copy | External API | Update Frequency |
|---|---|---|---|
| OFAC | Yes | Optional | Daily async |
| UN | Yes | Optional | Daily async |
| EU | Yes | Optional | Daily async |
| UK (OFSI) | Yes | Optional | Daily async |
| PEP Lists | Yes | Optional | Weekly async |
Note: All external updates are async and non-blocking. Payment flow never waits.
FX Rate Sources (Priority Order):
1. Internal calculation (always available)
2. Cached external rates (if available)
3. Real-time external feeds (optional)
External Providers (Optional):
- XE.com
- Fixer.io
- BI JISDOR (Indonesia official rate)
Independence: Kovra can calculate FX rates internally using:
- Historical averages
- Markup on reference rates
- Corridor-specific pricing
| Error Code | Indonesia (SNAP) | EU (SEPA) | UK (FPS) |
|---|---|---|---|
INVALID_ACCOUNT |
SNAP-001 |
pacs.002-00001 |
FPS-001 |
INSUFFICIENT_FUNDS |
SNAP-002 |
pacs.002-00002 |
FPS-002 |
TIMEOUT |
SNAP-999 |
pacs.002-99999 |
FPS-999 |
Mapping Strategy:
// Adapter layer normalizes all errors to Kovra standard codes
type RailError struct {
RailCode string // Original rail code
KovraCode string // Normalized code
Message string // Human-readable
Retryable bool // Can retry?
}| Region | Sandbox Available | Registration |
|---|---|---|
| Indonesia (BI) | Yes | BI Developer Portal |
| EU (SEPA) | Yes | EPC Testing Portal |
| UK (FPS) | Yes | Pay.UK Testing |
For development without external connectivity:
# config/development.yaml
adapters:
indonesia:
mode: mock
latency: 100ms # Simulate network
success_rate: 0.95 # Simulate failures
eu:
mode: mock
latency: 50ms
success_rate: 0.98- BI-FAST sandbox access
- SEPA certification
- UK FPS registration
- Local sanctions DB setup
- Mock adapters for testing
- Real-time sanctions updates
- External FX rate feeds
- Enhanced ML screening
- US FedNow integration
- Additional corridors
00_OVERVIEW.md (Start here)
│
├─► 01_ARCHITECTURE.md (High-level)
├─► 02_COMPONENTS.md (Service details)
├─► 03_COMPLIANCE.md (KYC/AML domain)
├─► 04_DEPLOYMENT.md (Infrastructure)
└─► INTEGRATION.md (You are here)
(External adapters)
| Document | Relation |
|---|---|
| 01_ARCHITECTURE.md | Adapter layer in system context |
| 02_COMPONENTS.md | Service-to-adapter communication |
| 03_COMPLIANCE.md | External compliance screening (optional) |
| 04_DEPLOYMENT.md | Adapter configuration |
-
All external integrations are optional
- Core Kovra works without any external APIs
- Adapters can be disabled/mocked
- Graceful degradation built-in
-
Local data is authoritative
- Sanctions screening: Local DB first
- FX rates: Internal calculation first
- Compliance: Rule-based fallback
-
Async for external
- Never block payment flow
- Queue for async processing
- Callback when results available
- mTLS for all connections
- JWS for message integrity
- No secrets in code
- Rotate credentials quarterly
- Mock adapters for unit tests
- Sandbox for integration tests
- Staging with real (test) credentials
- Production monitoring
Prev: 04_DEPLOYMENT.md for infrastructure setup
Compliance: 03_COMPLIANCE.md for KYC/AML integration
Index: 00_OVERVIEW.md
Docs: README.md
Last Updated: 2026-02-15