Architecture Overview
Kulpay API is a Go-based financial services API that serves as the middleware layer for the Kulpay ecosystem. It provides both gRPC and REST interfaces for client applications to manage customers, process payments, handle KYC verification, and execute financial transactions.
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 | MiniAiLive |
| 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 | - |