Getting Started
Welcome to the Kulpay API documentation. Kulpay API is the financial services platform powering the Kulpay ecosystem, providing comprehensive APIs for customer management, KYC verification, payment processing, invoice collection, and merchant onboarding.
The platform consists of two complementary API modules:
- Core API — Customer management, KYC verification, payment methods, and financial transactions
- Collection API — Invoice management, payment collection, merchant onboarding, and OIDC identity providers
Quick Navigation
System Architecture
Understand the technical foundation: technology stack, deployment topology, security model, data models, and external integrations.
API Reference
Complete REST API documentation with all endpoints, request/response schemas, authentication, and error handling.
Business Processes
Visual documentation of 9 core business workflows across both APIs: customer onboarding, fund transfers, invoice lifecycle, payment collection, and more.
System Overview
Kulpay API exposes a dual-protocol API:
- REST API on port
8080via gRPC-Gateway (JSON over HTTP) - gRPC API on port
50051(Protocol Buffers over HTTP/2)
All REST endpoints are prefixed with /v1/ and accept/return application/json.
Core Services
| Service | Description |
|---|---|
| Customer Service | Customer lifecycle management and onboarding |
| KYC Service | Know Your Customer verification records |
| KYC Log Service | KYC workflow tracking and reviewer interactions |
| Bills Service | Customer bill management |
| Partner Service | Partner configurations and payment methods |
| Instruction Service | Financial transaction instructions |
| License Service | System license activation and validation |
| Device Service | Device registration and trust management |
| System Service | System configuration and health |
Collection Services
| Service | Description |
|---|---|
| Payment Service | Payment records, ingestion, and lifecycle management |
| Collection Request Service | Invoice creation, delivery, and tracking |
| Collection Method Service | SIMO ERV and interbank payment channel configuration |
| Onboarding Service | Business account registration and approval |
| Identity Provider Service | OIDC provider management for authentication |
| Webhooks | Real-time event notifications for invoice lifecycle |
Authentication
The Kulpay platform uses two authentication models:
- Core API — License-based authorization. The system validates a license key on each request at the middleware level. No per-request
Authorizationheader is required. - Collection API — API Key + OIDC authentication. Each request requires a Bearer token obtained from the configured identity provider.
Both models require an active system license.