The Kulpay API REST API is served via gRPC-Gateway and provides JSON-based endpoints for all system operations.
Base URL
All endpoints are prefixed with /v1/.
Content Type
| Direction | Content-Type |
|---|
| Request | application/json (or multipart/form-data for file uploads) |
| Response | application/json |
Authentication
The system uses license-based authorization. The license is validated at the middleware level on every request — no Authorization header is required from API consumers.
See Authentication for details.
List endpoints support cursor-based or token-based pagination:
| Parameter | Type | Description |
|---|
page_size | integer | Number of items per page (default: 50, max: 100) |
page_token | string | Token from previous response to fetch next page |
Paginated responses include:
| Field | Type | Description |
|---|
data | array | Array of result objects |
has_more | boolean | true if more results exist |
next_page_token | string | Token for next page (if has_more is true) |
Endpoint Summary
Customer Service
| Method | Endpoint | Description |
|---|
| POST | /v1/customers/initiate | Initiate customer creation |
| POST | /v1/customers | Verify customer phone |
| GET | /v1/customers/{id} | Get customer details |
| PUT | /v1/customers/{id} | Update customer |
| DELETE | /v1/customers/{id} | Delete customer |
| GET | /v1/customers | List customers |
| POST | /v1/customers/{id}/upload-document | Upload ID document |
| POST | /v1/customers/{id}/upload-selfie | Upload selfie for face verification |
| POST | /v1/customers/{id}/profile/picture | Change profile picture |
| GET | /v1/customers/get-receiver/{phone_number} | Get receiver data by phone |
KYC Service
| Method | Endpoint | Description |
|---|
| GET | /v1/customers/{id}/kyc | List KYC verifications |
KYC Log Service
| Method | Endpoint | Description |
|---|
| GET | /v1/kyc/{id}/logs | Get KYC logs |
| POST | /v1/kyc/{id}/logs | Add message to KYC log |
| POST | /v1/kyc/{id}/logs/save | Upload additional document |
| POST | /v1/kyc/{id}/logs/save-date | Add document validity |
| PUT | /v1/customers/{id}/kyc/{kyc_id}/reviews | Review KYC verification |
| POST | /v1/customers/{id}/kyc/{kyc_id}/reviews/ready | Submit documents for review |
| GET | /v1/customers/{id}/kyc/{kyc_id} | Get specific KYC verification |
| GET | /v1/customers/{id}/kyc/logs | Get customer KYC logs |
Bills Service
| Method | Endpoint | Description |
|---|
| GET | /v1/customers/{id}/bills | List customer bills |
Partner & Payment Methods Service
| Method | Endpoint | Description |
|---|
| GET | /v1/partners | List partners |
| GET | /v1/partners/{id} | Get partner details |
| POST | /v1/customers/{id}/payment_methods | Create payment method |
| GET | /v1/customers/{id}/payment_methods | List payment methods |
| GET | /v1/customers/{id}/payment_methods/{payment_method_id} | Get payment method |
| POST | /v1/customers/{id}/payment_methods/{payment_method_id}/status | Set payment method status |
| POST | /v1/customers/{id}/payment_methods/{payment_method_id}/transactions | Process transaction |
| GET | /v1/customers/{id}/transactions | Get transaction history |
| GET | /v1/customers/{id}/transactions/{instruction_id} | Get transaction details |
| POST | /v1/partners/get-logo | Get card logo |
Instruction Service
| Method | Endpoint | Description |
|---|
| POST | /v1/partners/{agent_id}/deposit | Register deposit instruction |
License Service
| Method | Endpoint | Description |
|---|
| POST | /v1/license/activate | Activate license |
| GET | /v1/license | Get license information |
| POST | /v1/license/deactivate | Deactivate license |
| POST | /v1/license/validate | Validate license |
Device Service
| Method | Endpoint | Description |
|---|
| POST | /v1/devices/trust | Register device information |
| GET | /v1/devices/{device_id} | Get device information |
System Service
| Method | Endpoint | Description |
|---|
| GET | /v1/system/config/supported-docs | Get supported documents |
| GET | /v1/system/accountopening/checklist | Get KYC checklist |
| GET | /v1/version | Get version information |
Provider Service
| Method | Endpoint | Description |
|---|
| GET | /v1/providers/{id} | Get provider details |
| GET | /v1/providers | List providers |