Architecture Overview
Kulpay API is a Go-based financial services platform that serves as the middleware layer for the Kulpay ecosystem. It consists of two complementary API modules:
- Core API — Manages customers, KYC verification, payment methods, and financial transactions for the Kulpay mobile app and Kulpay Backoffice Dashboard.
- Collection API — Handles invoice management, payment collection, merchant onboarding, and identity provider configuration for billers and business partners via the Hakela merchant portal. Uses Keycloak for authentication.
Both modules share the same infrastructure (gRPC + REST, PostgreSQL, Redis, License system) and provide unified financial services through a single gateway. Externally, this is presented as a single unified system.
High-Level Architecture
Dual-Protocol API
Kulpay API exposes APIs through two protocols simultaneously:
| Protocol | Port | Format | Use Case |
|---|---|---|---|
| REST | 8080 | JSON over HTTP/1.1 | Mobile apps, web clients |
| gRPC | 50051 | Protobuf over HTTP/2 | High-performance service-to-service |
The REST API is auto-generated from Protocol Buffer definitions using gRPC-Gateway, ensuring both protocols stay in sync.
Technical Decision: The dual-protocol approach allows mobile apps and web clients to use familiar REST/JSON while keeping the door open for high-performance gRPC connections for service-to-service communication. Since the REST layer is auto-generated from Proto definitions, there is zero risk of REST and gRPC APIs diverging.
Request Flow
Middleware Stack
Every request passes through these layers:
- Recovery Middleware - Catches panics and returns structured errors
- CORS Middleware - Handles cross-origin requests with configurable origins
- Logging Interceptors - Structured logging for all gRPC unary and stream calls
- License Interceptor - Validates the license key on every request
- Multipart Middleware - Handles file upload requests for documents and images
Service Responsibilities
| Service | Responsibility | Key Integrations |
|---|---|---|
| Customer | Account lifecycle, onboarding, profile management | SMS, NUIB, File Server |
| KYC | Identity document verification records | LiveAIEngine |
| KYC Log | Review workflow, document requests, comments | - |
| Bills | Customer bill retrieval and management | - |
| Partner | Payment method CRUD, partner configs, transactions | Payment Adapters |
| Instruction | Deposit instruction registration | Payment Adapters |
| License | License activation, validation, deactivation | - |
| Device | Device fingerprinting and trust | - |
| System | Configuration, health checks, supported documents | - |
| Payment | Payment records, ingestion, reconciliation | Collection Methods |
| Collection Request | Invoice creation, lifecycle, webhooks | Payment Service, SMS |
| Collection Method | SIMO ERV and interbank payment channel config | - |
| Onboarding | Business account registration and approval | Keycloak, File Server |
| Identity Provider | OIDC provider management and configuration | Keycloak |