Kovra: Cross-Border Payment Infrastructure Layer
Arsitektur Kovra dirancang sebagai abstraction layer untuk fintech & platforms - mirip "Stripe Treasury + Wise Engine" tapi fokus corridor EU/UK/ID + B2B batch.
Key Design: API-first, modular regional adapters, orthogonal compliance, standalone mode.
For detailed component specs, see 02_COMPONENTS.md.
For compliance architecture, see 03_COMPLIANCE.md.
For deployment details, see 04_DEPLOYMENT.md.
┌─────────────────────────────────────────────────────────────┐
│ KOVRA PLATFORM │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌───────────────────┐ ┌───────────────────┐ │
│ │ PAYMENT DOMAIN │ │ COMPLIANCE DOMAIN │ │
│ │ │ │ │ │
│ │ • Quote Service │ │ • KYC/AML │ │
│ │ • Transfer Svc │◄────►│ • Risk Scoring │ │
│ │ • Wallet Service │Event │ • Audit Trail │ │
│ │ • Batch Service │Bus │ • Screening │ │
│ └───────────────────┘ └───────────────────┘ │
│ │ │ │
│ │ ┌──────────────┐ │ │
│ └────►│ Kafka │◄────┘ │
│ │ (Events) │ │
│ └──────────────┘ │
│ │
│ Principle: Change one domain without affecting the other │
└─────────────────────────────────────────────────────────────┘
- No mandatory external APIs: Core platform works standalone
- Optional enhancements: External feeds (FX rates, sanctions) = cache + async updates
- Interface contracts: Services communicate via interfaces, not concrete implementations
| Component | Technology | Purpose |
|---|---|---|
| Backend | Go 1.25+ | API services, business logic |
| Main DB | PostgreSQL 18 | Tenants, transfers, audit |
| Ledger | TigerBeetle | Double-entry accounting, balance tracking |
| Cache | Redis 8.4 | Rate limiting, FX rate lock, session |
| Job Queue | River | Webhook delivery, scheduled jobs, retry logic |
| Event Streaming | Kafka | Transfer events, audit trail, notifications |
| Compliance | OxCaml 90% + Python 10% | KYC/AML core in OxCaml, ML bridge in Python (see 03_COMPLIANCE.md) |
┌─────────────────────────────────────────────────────────────────────────────┐
│ B2B CLIENTS │
│ (E-commerce Platforms / Corporate Treasury Systems) │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Tokopedia │ │ Bukalapak │ │ Corp ERP │ │ Treasury │ │
│ │ Integration │ │ Integration │ │ (SAP/Odoo) │ │ Management │ │
│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │
│ └────────────────┴────────────────┴────────────────┘ │
│ │ │
└────────────────────────────────────┼────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ API GATEWAY │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Rate Limit │ │ Auth (JWT/ │ │ Request │ │ Idempotency │ │
│ │ (per tier) │ │ API Key) │ │ Validation │ │ Check │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │
└────────────────────────────────────┼────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ CORE SERVICES │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Quote │ │ Transfer │ │ Recipient │ │ Wallet │ │
│ │ Service │ │ Service │ │ Service │ │ Service │ │
│ │ │ │ │ │ │ │ │ │
│ │ • FX rates │ │ • Orchestrate│ │ • Validate │ │ • Balance │ │
│ │ • Lock rate │ │ • State mgmt │ │ • Store bank │ │ • Hold/Release│ │
│ │ • Margin calc│ │ • Retry logic│ │ • IBAN check │ │ • Multi-curr │ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
│ └─────────────────┴─────────────────┴─────────────────┘ │
│ │ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Batch │ │ Compliance │ │ Webhook │ │
│ │ Service │ │ Service │ │ Service │ │
│ │ │ │ │ │ │ │
│ │ • Bulk ops │ │ • KYC/AML │ │ • Delivery │ │
│ │ • Scheduling │ │ • Screening │ │ • Retry │ │
│ │ • Validation │ │ • Audit │ │ • JWS sign │ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
└─────────┼─────────────────┼─────────────────┼──────────────────────────────┘
│ │ │
│ ┌────────────┴────────────┐ │
│ │ Kafka Topics │ │
│ │ • transfer.events │ │
│ │ • compliance.events │ │
│ │ • audit.trail │ │
│ │ • webhook.dlq │ │
│ └─────────────────────────┘ │
│ │
▼ ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ REGIONAL ADAPTERS │
│ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ EU Adapter │ │ UK Adapter │ │ ID Adapter │ │
│ │ (SEPA/PSD2) │ │ (FPS/CHAPS) │ │ (BI-FAST/SNAP) │ │
│ │ │ │ │ │ │ │
│ │ • SEPA Instant │ │ • Faster Pay │ │ • BI-FAST │ │
│ │ • SCT │ │ • CHAPS │ │ • RTGS │ │
│ │ • ISO 20022 │ │ • ISO 20022 │ │ • SNAP Auth │ │
│ └────────┬────────┘ └────────┬────────┘ └────────┬────────┘ │
│ └────────────────────┴────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘
Kovra bukan bank atau neobank replacement. Kovra adalah infrastructure layer yang dipakai oleh fintech lain.
- ❌ End-user exporters (langsung) - indirect via fintech partners
- ❌ Bank konvensional (CIMB, BCA) - sales cycle panjang
- ❌ Korporasi besar (Unilever, Astra) - treasury system existing
- ✅ Fintech platforms (Xendit, Midtrans) - API integration cepat
- ✅ Payment aggregators - Tambah corridor tanpa rebuild
- ✅ Digital commerce - Batch payout + ERP integration
┌─────────────────────────────────────────────────────────────┐
│ FINTECH PARTNER │
│ (Xendit, Midtrans, Bank Jago, etc.) │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Mobile │ │ Web │ │ API │ │
│ │ App │ │ Dashboard │ │ Endpoints │ │
│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │
│ └─────────────────┴─────────────────┘ │
│ │ │
│ ▼ │
│ ┌───────────────────────┐ │
│ │ KOVRA API (REST) │ │
│ │ • Quotes │ │
│ │ • Transfers │ │
│ │ • Webhooks │ │
│ └───────────┬───────────┘ │
└──────────────────────────┼──────────────────────────────────┘
│
┌─────────────────┼─────────────────┐
│ │ │
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ Backend │ │Compliance│ │ Ledger │
│ (Go) │ │(OxCaml+Py) │ │(TB) │
└──────────┘ └──────────┘ └──────────┘
Value: Fintech partner bisa fokus pada UX & customer acquisition, Kovra handle complex cross-border infrastructure.
| Service | Core Responsibility | Independence |
|---|---|---|
| Quote Service | FX rate fetch, margin calc, rate locking | Can swap FX providers without affecting others |
| Transfer Service | Orchestrate payment lifecycle, state management | No dependency on compliance internals |
| Recipient Service | Validate and store beneficiary details | Can add new rails without touching core |
| Wallet Service | Balance tracking, hold/release | Uses TigerBeetle, isolated from business logic |
| Batch Service | Bulk payment processing | Independent queue processing |
| Compliance Service | KYC/AML screening, risk scoring | Orthogonal domain - see 03_COMPLIANCE.md |
| Webhook Service | Event delivery to tenants | Can be replaced with different queue system |
B2B Client (Exporter)
│
▼
POST /quotes ────────────────────────────┐
│ │
▼ │
Quote Service ◄──FX rates───► Cache │
│ │
└──────────────► Quote {rate, expiry}┘
│
POST /transfers {quote_id, recipient} │
│ │
▼ │
Transfer Service │
│ │
├─► Compliance Check (via event bus) │
│ See [03_COMPLIANCE.md] │
│ │
├─► Wallet Hold (TigerBeetle) │
│ │
├─► Collect EUR (EU Adapter) │
│ │
├─► FX Conversion │
│ EUR → IDR (Two coordinated │
│ TigerBeetle chains) │
│ │
├─► Payout IDR (ID Adapter) │
│ │
└─► Webhook: transfer.completed ◄────┘
For detailed state machine and ledger design, see 02_COMPONENTS.md.
API Request
│
├─► API Key → Tenant ID lookup (Redis)
├─► Rate limit check (per tenant tier)
├─► Tenant context injection
├─► All queries filtered by tenant_id
└─► TigerBeetle accounts prefixed with tenant_id
Isolation Guarantees:
• Tenant A cannot query Tenant B data
• Tenant A cannot debit Tenant B wallet
• Webhook signatures are tenant-specific
| Policy | Starter | Growth | Enterprise |
|---|---|---|---|
| Rate Limit | 100 req/min | 500 req/min | 2,000 req/min |
| Daily Volume | $10,000 | $100,000 | $1,000,000+ |
| FX Margin | 150 bps | 80 bps | 30-50 bps |
Implementation: Separate tables (pricing_policies, limit_policies) linked to tenants. Tier = derived from policies, not identity.
LEDGER CODES (ISO 4217):
├── 360 - IDR (Indonesian Rupiah)
├── 840 - USD (US Dollar)
├── 978 - EUR (Euro)
├── 826 - GBP (British Pound)
├── 752 - SEK (Swedish Krona)
└── 208 - Danish Krone)
ACCOUNT TYPES:
├── TENANT_WALLET (per tenant, per currency)
├── FEE_REVENUE (platform fees)
├── FX_POSITION (internal FX operations)
├── PENDING_INBOUND (funds being collected)
├── PENDING_OUTBOUND (funds being sent)
└── REGIONAL_SETTLEMENT (per corridor)
ACCOUNT ID FORMAT:
[tenant_id: 64 bits] [account_type: 8 bits] [currency: 24 bits]
For detailed ledger design and transfer examples, see 02_COMPONENTS.md.
Benefits over direct calls:
✓ Services don't know about each other
✓ No cascading failures
✓ Easy to add new consumers
✓ Audit trail built-in
Topics:
• transfer.events - State changes, completions
• compliance.events - Screening results, alerts
• audit.trail - Immutable audit log
• webhook.dlq - Dead letter queue
// Payment Service doesn't know Compliance internals
type ComplianceChecker interface {
Check(ctx context.Context, transfer Transfer) (ComplianceStatus, error)
}
// Can be implemented by:
// - Real compliance service
// - Mock (testing)
// - No-op (emergency mode)
// - Cached (performance mode)| Region | Adapter | Rails | Key Specs |
|---|---|---|---|
| Indonesia | ID Adapter | BI-FAST (instant), RTGS (large) | SNAP Auth, ISO 20022 |
| EU | EU Adapter | SEPA Instant, SCT | FAPI 2.0, PSD2, ISO 20022 |
| UK | UK Adapter | Faster Payments, CHAPS | UK FAPI, ISO 20022 |
For detailed adapter specs, see INTEGRATION.md.
| Scenario | Detection | Action |
|---|---|---|
| Quote expired | State timeout (10min) | Reject, user creates new quote |
| Compliance fail | Screening service | Block + flag for review |
| Insufficient funds | Balance check | Reject immediately |
| Rail timeout | No ACK in 5min | Mark PENDING_RAIL, retry with backoff |
| Rail rejection | Negative ACK | Mark RAIL_REJECTED, refund |
For comprehensive failure handling, see 02_COMPONENTS.md.
# Kovra can run 100% offline
mode: standalone
features:
- sanctions_source: local_db # No OFAC API calls
- fx_rates_source: internal # No XE/Fixer required
- compliance_mode: rule_based # No ML model required
- audit_storage: local # No external log aggregation
# External APIs = optional enhancements
enhancements:
- sanctions_sync: async_daily # Update local DB
- fx_feeds: xe, fixer, bi_jisdor # Better rates
- ml_screening: optional # Better accuracy- Traditional: 18-24 bulan build cross-border infrastructure
- Kovra: 3-9 bulan POC → production
- API-first: Integration dalam minggu, bukan bulan
- Fokus: EU/UK ↔ Indonesia (high-demand corridor)
- Rails: SEPA Instant, FPS, BI-FAST (real-time)
- FX: Internal calculation + external feeds (hybrid)
- Orthogonal: Compliance evolve tanpa touch payment flow
- Standalone: Works 100% tanpa external APIs
- Event-driven: Kafka untuk async processing
- Immutable ledger: TigerBeetle untuk audit trail
- Bulk payouts ke supplier global
- Netting untuk optimize FX
- ERP integration (SAP, Odoo)
| Player | Approach | Kovra Differentiation |
|---|---|---|
| Xendit | Build sendiri, corridor luas | Kovra: Deeper EU/UK/ID, faster integration |
| Wise | Direct to consumer | Kovra: B2B infrastructure, white-label |
| Traditional Banks | Legacy systems | Kovra: API-first, <50ms latency |
| Stripe | US-focused | Kovra: Indonesia/SEA focused |
| Metric | Target | Notes |
|---|---|---|
| TPS | 5,000 | k6 load test |
| P50 latency | < 15ms | API response |
| P95 latency | < 50ms | API response (faster than traditional 200-500ms) |
| Success rate | > 99.5% | Completed transfers |
| Compliance screening | < 500ms | Fast fail for payment flow |
| Time to Integration | < 4 minggu | Untuk fintech API-ready |
| Data | Location | Compliance |
|---|---|---|
| IDR transfers | Indonesia partition | OJK |
| EUR/SEK/DKK | EU partition | GDPR |
| GBP | UK partition | FCA |
Implementation: PostgreSQL LIST partitioning on compliance_region column.
00_OVERVIEW.md (you are here)
│
├─► 01_ARCHITECTURE.md (high-level)
│ └─► 02_COMPONENTS.md (detailed implementation)
│
├─► 03_COMPLIANCE.md (KYC/AML domain)
│
├─► 04_DEPLOYMENT.md (infrastructure)
│
├─► INTEGRATION.md (external adapters)
│
├─► DATABASE.md (schema)
│
└─► SECURITY.md (auth, encryption)
Next: 02_COMPONENTS.md for detailed component specs
Compliance: 03_COMPLIANCE.md for KYC/AML architecture
Deploy: 04_DEPLOYMENT.md for infrastructure setup
Last Updated: 2026-02-15 (Positioning Update: Infrastructure Layer untuk Fintech)