API Overview

The Kulpay API REST API is served via gRPC-Gateway and provides JSON-based endpoints for all system operations.

Base URL

https://<host>:8080/v1/

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 Kulpay API uses two authentication models depending on the service:

• Core Services — License-based system authorization. No Authorization header required. See Authentication.
• Collection Services — API Key + OIDC per-request authentication via Bearer tokens. See Collection API Authentication.

Pagination

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

---

Kulpay Collection API

The following services are part of the Kulpay Collection API and require Bearer token authentication.

Payment Service

Method	Endpoint	Description
POST	/v1/payments	Create payment
GET	/v1/payments	List payments
POST	/v1/payments/ingest	Ingest external payment
GET	/v1/payments/{id}	Get payment by ID
PUT	/v1/payments/{id}	Update payment
DELETE	/v1/payments/{id}	Delete payment

Collection Request Service

Method	Endpoint	Description
POST	/v1/collection-requests	Create collection request (invoice)
GET	/v1/collection-requests/{id}	Get collection request
GET	/v1/collection-requests	List collection requests
GET	/v1/kulpay/collection-requests/list-by-phone-number/{phone_number}	List by phone number
GET	/v1/kulpay/collection-requests/get-request/{id}	Get request (unsecured)
PUT	/v1/collection-requests/{id}	Update collection request
DELETE	/v1/collection-requests/{id}	Delete collection request

Collection Method Service

Method	Endpoint	Description
POST	/v1/collection-methods	Create collection method
GET	/v1/collection-methods/{id}	Get collection method
GET	/v1/collection-methods	List collection methods
PUT	/v1/collection-methods	Update collection method
DELETE	/v1/collection-methods	Delete collection method

Onboarding Service

Method	Endpoint	Description
GET	/v1/account	Get account information
POST	/v1/accounts/{account_id}/approve	Approve account
POST	/v1/accounts/{account_id}/reject	Reject account
POST	/v1/accounts/{account_id}/suspend	Suspend account
GET	/v1/account/onboarding	Get onboarding status
GET	/v1/account/onboarding/details	Get onboarding details
PUT	/v1/account/onboarding/details	Update onboarding details
POST	/v1/account/onboarding/initialize	Initialize onboarding
POST	/v1/account/onboarding/finish	Finish onboarding
POST	/v1/files	Upload file

Identity Provider Service

Method	Endpoint	Description
POST	/v1/identity_providers	Create identity provider
GET	/v1/identity_providers/{id}	Get identity provider
GET	/v1/identity_providers	List identity providers
PUT	/v1/identity_providers	Update identity provider
DELETE	/v1/identity_providers	Delete identity provider

Webhooks & Events

Method	Endpoint	Description
POST	/v1/collection-requests/web-hook/bill-created	Bill created notification
POST	/v1/collection-requests/{id}/web-hook/bill-paid	Bill paid notification
POST	/v1/collection-requests/{id}/web-hook/bill-opened	Bill opened notification
POST	/v1/collection-requests/{id}/web-hook/bill-delivered	Bill delivered notification
POST	/v1/collection-requests/{id}/web-hook/customer-paid	Customer paid notification
POST	/v1/collection-requests/{id}/web-hook/kulpay	Kulpay app notification