fineract-client-kmp
1.0.6indexedFacilitates interaction with the Apache Fineract 1.x Platform using a client library, leveraging Ktor for network operations.
1
Stars
—
Used by
dependents
—
Health
/ 100
Fineract API Client Library 
Overview
The FineractClient is a Kotlin client library for interacting with Apache Fineract's REST APIs. It provides a
comprehensive wrapper around Ktorfit for making HTTP requests to Fineract servers and accessing various financial
services endpoints.
Add Dependency
Gradle
To use the library in your Gradle project, follow the steps below:
implementation("io.github.niyajali:fineract-client-kmp:1.0.6")
Architecture
The client follows a Builder pattern for configuration and provides type-safe access to Fineract's API endpoints through generated interfaces.
Core Components
FineractClient Class
class FineractClient private constructor(
private val ktorfit: Ktorfit,
) {
// API endpoint accessors
val accountingClosures = ktorfit.createAccountingClosureApi()
val accountingRules = ktorfit.createAccountingRulesApi()
accountNumberFormats = ktorfit.createAccountNumberFormatApi()
accountTransfers = ktorfit.createAccountTransfersApi()
: String
: HttpClient
}
Available API Endpoints
accountingClosures- Manage accounting period closuresaccountingRules- Handle accounting rules and configurationsaccountNumberFormats- Manage account number formatting rulesaccountTransfers- Process account-to-account transfers
Utility Methods
baseURL()- Returns the configured base URL for the Fineract serverhttpClient()- Provides access to the underlying HttpClient for advanced customizations
Builder Class
The Builder class provides a fluent API for configuring the FineractClient:
class Builder () {
: Builder
: Builder
: Builder
: Builder
: FineractClient
}
Usage Examples
Basic Client Setup
import io.ktor.client.*
import io.ktor.client.engine.cio.*
import io.ktor.client.plugins.auth.*
import io.ktor.client.plugins.auth.providers.*
import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.serialization.kotlinx.json.*
// Create HTTP client with authentication
val httpClient = HttpClient(CIO) {
install(ContentNegotiation) {
json()
}
install(Auth) {
basic {
credentials {
BasicAuthCredentials(username = , password = )
}
}
}
}
fineractClient = FineractClient.builder()
.baseURL()
.tenant()
.httpClient(httpClient)
.build()
Advanced HTTP Client Configuration
val customHttpClient = HttpClient(CIO) {
install(ContentNegotiation) {
json(Json {
ignoreUnknownKeys = true
isLenient = true
})
}
install(Auth) {
bearer {
loadTokens {
BearerTokens("your-access-token", "your-refresh-token")
}
}
}
install(Logging) {
level = LogLevel.INFO
}
// Custom timeout settings
install(HttpTimeout) {
requestTimeoutMillis = 30000
connectTimeoutMillis = 10000
}
}
val client = FineractClient.builder()
.baseURL("https://your-fineract-server.com/fineract-provider/api/v1")
.tenant()
.httpClient(customHttpClient)
.build()
Using API Endpoints
Date Formatting
The client provides a constant for consistent date formatting across API calls:
import java.time.LocalDate
import java.time.format.DateTimeFormatter
val currentDate = LocalDate.now()
val formattedDate = currentDate.format(DateTimeFormatter.ofPattern(FineractClient.DATE_FORMAT))
// Result: "2025-05-31"
// Use in API requests
val request = SomeApiRequest(
date = formattedDate,
// other fields...
)
Error Handling Best Practices
Multi-tenant Configuration
Configuration Options
Required Configuration
baseURL- The base URL of your Fineract serverhttpClient- Configured HttpClient with authentication
Optional Configuration
tenant- Fineract tenant identifier (for multi-tenant setups)inSecure- ⚠️ Deprecated - Use proper SSL configuration in HttpClient instead
Best Practices
- Reuse Client Instances - Create one client per tenant and reuse it across your application
Thread Safety
The FineractClient is thread-safe and can be safely used from multiple coroutines concurrently. The underlying Ktorfit and HttpClient are designed for concurrent use.
Dependencies
Ensure you have the following dependencies in your project:
// build.gradle.kts
dependencies {
implementation("io.ktor:ktor-client-core:$ktor_version")
implementation("io.ktor:ktor-client-cio:$ktor_version")
implementation("io.ktor:ktor-client-content-negotiation:$ktor_version")
implementation("io.ktor:ktor-client-auth:$ktor_version")
implementation("io.ktor:ktor-serialization-kotlinx-json:$ktor_version")
implementation("de.jensklingenberg.ktorfit:ktorfit-lib:$ktorfit_version")
}