Simplifies integration with MTN MOMO API, handling authentication via a pull-based credential model, secure storage, automatic token refresh, payments, disbursements, remittances, and logging.
The MTN MOMO API SDK is a Kotlin Multiplatform (KMP) library designed to simplify the integration of MTN’s Mobile Money (MOMO) services into Android and JVM applications. The core SDK targets both Android and JVM platforms, while a full-featured Android sample app demonstrates every API operation. This SDK enables developers to seamlessly interact with MTN’s extensive mobile payment infrastructure, facilitating core functionalities such as secure user authentication, balance inquiries, and efficient transaction processing. By abstracting the complexities of the MOMO API, this library provides a reliable and secure bridge between Android applications and MTN’s financial services, allowing developers to focus on building exceptional user experiences.
For more information about the MTN MOMO API, please visit the official documentation here.
The MTN MOMO API SDK offers a comprehensive suite of tools and functionalities that support a wide range of MOMO operations while adhering to modern Android development practices. Key features include:
For a complete overview of available operations, refer to the full MTN MOMO API documentation here.
Kotlin Multiplatform: The core SDK (momo-api-sdk) is built with Kotlin Multiplatform, targeting Android and JVM. This makes the network, repository, and model layers reusable across platforms.
For further exploration, check out the documentation on Kotlin Coroutines, Hilt, and Jetpack Compose.
Comprehensive Error Handling and Logging: The SDK ships a KMP-safe abstraction (, , , ) backed by on Android and standard output on JVM. All SDK internals use so log output flows through whichever backend the host platform provides.
This SDK empowers Android developers to integrate MTN MOMO services confidently, providing secure and efficient mobile payment solutions.
For detailed instructions on integrating and configuring the MTN MOMO API SDK, please consult the official MTN MOMO API documentation.
The SDK uses a pull-based credential model — it never stores credentials internally. Instead, it calls your app's CredentialProvider implementation on every request to retrieve the current API user ID, API key, and access token.
┌─────────────────────────────────────────────────────────────┐
│ Your App │
│ │
│ CredentialStorage CredentialProvider │
│ (EncryptedSharedPrefs) ◄── (reads from storage) │
│ ▲ │ │
│ │ ▼ │
│ MainViewModel SDK Interceptors │
│ (writes credentials) BasicAuthInterceptor │
│ AccessTokenInterceptor │
│ │ │
│ TokenAuthenticator │
│ (refreshes on 401) │
└─────────────────────────────────────────────────────────────┘
Credentials are stored using EncryptedSharedPreferences (AES-256-GCM via the Android Keystore) through CredentialStorage. Tokens include expiry timestamps so that expired tokens are never returned — an expired token is treated the same as no token.
The TokenAuthenticator (an OkHttp Authenticator) fires automatically on every HTTP 401 response from a Bearer-protected endpoint:
AuthenticationService backed by a minimal, Basic-Auth-only — this avoids a circular dependency with the main client.After at most one retry, the authenticator gives up and propagates the 401 to the caller.
CredentialProvider (
storage: CredentialStorage,
config: SampleConfig
) : CredentialProvider {
: String = config.apiUserId
: String =
(storage.getAccessToken().isBlank()) storage.getApiKey()
: String = storage.getAccessToken()
}
Register it in your Hilt module:
@Provides
@Singleton
fun provideCredentialProvider(
storage: CredentialStorage,
config: SampleConfig
): CredentialProvider = MyCredentialProvider(storage, config)
On first launch, MainViewModel runs a one-time sequence to provision credentials:
CredentialStorage; skipped if a key already exists.Subsequent app launches skip any step where a valid, non-expired credential is already stored. Token expiry is checked automatically by CredentialStorage — no manual refresh calls are needed.
To include the MTN MOMO API SDK in your project, add the following dependency to your project's build.gradle.kts file:
dependencies {
implementation("io.rekast:momo-api-sdk:0.1.0-SNAPSHOT")
}
local.propertiesTo configure your local environment for the MTN MOMO API SDK, create a local.properties file in the root of your project with the following content:
# Local properties for the MTN MOMO API SDK
MOMO_BASE_URL="" ## Use https://sandbox.momodeveloper.mtn.com for sandbox and https://momodeveloper.mtn.com for production
MOMO_PROVIDER_CALLBACK_HOST="" ## The provider callback host, use 'localhost' for sandbox
MOMO_COLLECTION_PRIMARY_KEY="" ## The collection endpoint/product subscription primary key
MOMO_COLLECTION_SECONDARY_KEY="" ## The collection endpoint/product subscription secondary key
MOMO_REMITTANCE_PRIMARY_KEY="" ## The remittance endpoint/product subscription primary key
MOMO_REMITTANCE_SECONDARY_KEY="" ## The remittance endpoint/product subscription secondary key
MOMO_DISBURSEMENTS_PRIMARY_KEY="" ## The disbursements endpoint/product subscription primary key
MOMO_DISBURSEMENTS_SECONDARY_KEY="" ## The disbursements endpoint/product subscription secondary key
MOMO_API_USER_ID="" ## The sandbox API user ID. You can use a [UUID generator](https://www.uuidgenerator.net/version4) to create one
MOMO_ENVIRONMENT="" ## API environment, use 'sandbox' for testing and 'production' for live operations
MOMO_API_VERSION_V1="" ## The API version for v1 endpoints, use 'v1_0' for sandbox and 'v1' for production
MOMO_API_VERSION_V2="" ## The API version for v2 endpoints, use 'v2_0' for sandbox and 'v2' for production
The SDK exposes all operations through DefaultRepository. Every method returns a Flow<NetworkResult<T>> — collect it inside a coroutine scope and handle the three states:
defaultRepository.someApi(...).collect { result ->
when (result) {
is NetworkResult.Loading -> { /* show progress */ }
is NetworkResult.Success -> { /* use result.response */ }
is NetworkResult.Error -> { /* handle result.message */ }
}
}
The available API groups are:
For full code examples and parameter descriptions for every API, see the Library Usage section of the documentation.
This project is licensed under the Apache License, Version 2.0. For more details, please refer to the LICENSE file.
For inquiries or support, please reach out to:
Benjamin Mwalimu GitHub Profile
Easy Integration with the MTN MOMO API: This SDK simplifies the process of connecting to the MOMO API, allowing developers to concentrate on building their applications without getting bogged down by the underlying complexities.
Support for a Range of MOMO Operations:
Coroutines for Asynchronous Operations: Utilizes Kotlin Coroutines to handle asynchronous operations efficiently, ensuring non-blocking API interactions that enhance user experience.
Hilt for Dependency Injection: Integrates with Hilt, a widely-used dependency injection framework, promoting clean and maintainable code architecture.
Jetpack Compose for UI (Sample App): Includes a sample application built with Jetpack Compose, the modern UI toolkit, to demonstrate effective integration and best practices for implementing MOMO services.
LoggerdiweLoggerSecure API Communication: Implements secure communication channels with proper authentication mechanisms, safeguarding all transactions and user data in compliance with industry standards.
OkHttpClientCredentialStorage.CredentialStorage. An OAuth2 refresh failure is non-fatal — the original request is still retried with the refreshed Bearer token.AccessTokenInterceptor reads the new token from storage and attaches the correct Authorization header on the retry.| Group | Description |
|---|
| Authentication | Provision API user, API key, Bearer token, and OAuth2 token via the CIBA flow |
| Collection | Request to Pay, Request to Withdraw, invoices, pre-approvals, and delivery notifications |
| Disbursements | Transfers, deposits, refunds, cash transfers, and delivery notifications |
| Remittance | Cross-border transfers and transfer status |
| Account | Account balance, basic user info, user info with consent, and account holder validation |
Surfaced from shared tags and platforms — no rankings paid for.