GSMA.MoMo.Android
Android SDK to use MOMO API.
A library that fully covers payment process inside your Android application
This SDK provides for an easy way to connect to Momo API. Please refer to the following documentation for installation instructions and usage information.
This document contains the following sections:
Optimum requirements to use this SDK are -
- Android Studio
4.0
or newer - Android Platform Version:
API 32
- Build gradle:
7.3.0
Copy the Momo-SDK-v1.0.0.aar Download file, available in the latest version in aar folder in the project directory, into libs folder under your project directory.
Add the below line in dependencies of your build.gradle
file in your application.
implementation files('libs/Momo-SDK-v1.0.0.aar')
- Authentication
- Collection
- Disbursement
- Remittance
The API user and API key are provisioned differently in the sandbox and production environment.In the Sandbox a provisioning API is used to create the API User and API Key, whereas in the production environment the provisioning is done through the User Portal.
The UserConfiguration object is created using the UserConfigurationBuilder which provides a fluent interface for setting the configuration parameters. The following parameter is set:
- subscriptionKey: A string value representing the subscription key associated with the user configuration,This configuration object can be used to provide necessary details for making API calls on behalf of a specific user.
UserConfiguration userConfiguration = new UserConfiguration.UserConfigurationBuilder().
setSubscriptionKey("<subscriptionKey>").
build();
This table below describe the different steps required in creating API User and API key in Sandbox and Production Environments.
Scenarios | API | Function | Parameters |
---|---|---|---|
User creation | Create User | Create user | Callbackhost callbackhost,RequestStateInterface requestStateInterface |
Get user details | getUserDetails | String userReferenceId,UserDetailInterface userDetailInterface | |
Create Api Key | createApiKey | String userReferenceId,ApiKeyInterface apiKeyInterface |
Collections is a service that enables Mobile Money partners to receive payments for goods and services using MTN Mobile Money. The services can be face-to-face like MomoPay or can be done remotely for both offline and online. Payments can be customer-initiated on USSD/App/Web or Merchant-initiated where a customer is sent a debit request for approval.
The collection configuration object is being initialized with a builder pattern,The parameter being set include
-
subscriptionKey:The subscription key is used to give access to APIs in the API Manager portal. A user is assigned a subscription Key as and when the user subscribes to products in the API Manager Portal.
-
subscriptionType: The type of subscription (in this case, a collection).
-
callBackUrl:The URL where the payment gateway or mobile money service should send notifications or callbacks
-
environment:The environment (sandbox or production) in which the momo api service is being used.
-
apikey: An api key for accessing the momo api services
-
userReferenceId: A reference ID for the user initiating the collection request
-
xTargetEnvironment: The identifier of the EWP system where the transaction shall be processed. This parameter is used to route the request to the EWP system that will initiate the transaction.
CollectionConfiguration collectionConfiguration = new CollectionConfiguration.
CollectionConfigurationBuilder().
setSubscriptionKey("<subsriptionkey>").
setSubscriptionType(SubscriptionType.COLLECTION).
setCallBackUrl("<callbackURL>").
setEnvironment(Environment.SANDBOX).
setAPiKey("<apikey>").
setUserReferenceId("<referenceId>").
setxTargetEnvironment("<target environment>")
setOnInitializationResponse(new TokenInitializeInterface() {
@Override
public void onTokenInitializeSuccess(StatusResponse statusResponse) {
}
@Override
public void onTokenInitializeFailure(MtnError mtnError) {
}
}).
build(this);
This table below describe the details required for collection functions
Scenarios | API | Function | Parameters |
---|---|---|---|
Request pay | Request pay | requestToPay | RequestPay requestPay ,RequestStateInterface requestStateInterface |
Request pay transaction status | requestToPayTransactionStatus | String referenceId,RequestPayStatusInterface requestPayStatusInterface | |
Delivery notification | requestToPayDeliveryNotification | String referenceId,RequestStateInterface requestStateInterface | |
Validate account holder | ValidateAccount Account holder | validateAccountHolderStatus | AccountHolder accountHolder,ValidateAccountInterface validateAccountInterface |
Get Balance | Account Balance | getAccountBalance | RequestBalanceInterface requestBalanceInterface |
Get Balance in specific currency | Get account balance in specific currency | getAccountBalanceInSpecificCurrency | RequestBalanceInterface requestBalanceInterface |
Request to withdraw | Request to withdraw V1 | requestToWithdrawV1 | Withdraw withdraw,RequestToWithdrawInterface requestToWithdrawInterface |
Request to withdraw V2 | requestToWithdrawV2 | Withdraw withdraw,RequestToWithdrawInterface requestToWithdrawInterface | |
Request to withdraw transaction status | requestToWithdrawTransactionStatus | String requestReferenceId,RequestToWithdrawInterface RequestToWithdrawStatusInterface | |
Validate Consumer Identity | Validate Consumer Identity | getBasicUserInfo | String msisdnId,UserInfoInterface userInfoInterface |
Get Consumer Information with Consent | Get Consumer Information with Consent | getUserInfoWithConsent | AccountHolder accountHolder,Enum Accesstype,String scope,UserConsentInterface userConsentInterface |
Disbursements is a service that enables Mobile Money partners to send money in bulk to different recipients with just one click. This setup can be manually executed (logging into the system, uploading recipient's list and trigger payments) or automated (requires a one-time setup of the recipients' lists and commands to effect payment).
The disbursement configuration object is being initialized with a builder pattern,The paramater being set include
-
subscriptionKey:The subscription key is used to give access to APIs in the API Manager portal. A user is assigned a subscription Key as and when the user subscribes to products in the API Manager Portal.
-
subscriptionType: The type of subscription (in this case, a collection).
-
callBackUrl:The URL where the payment gateway or mobile money service should send notifications or callbacks
-
environment:The environment (sandbox or production) in which the momo api service is being used.
-
apikey: An api key for accessing the momo api services
-
userReferenceId: A reference ID for the user initiating the collection request
-
xTargetEnvironment: The identifier of the EWP system where the transaction shall be processed. This parameter is used to route the request to the EWP system that will initiate the transaction.
DisbursementConfiguration disbursementConfiguration = new DisbursementConfiguration.
DisbursementConfigurationBuilder().
setSubscriptionKey("<subsriptionkey>").
setSubscriptionType(SubscriptionType.DISBURSEMENT).
setCallBackUrl("<callbackURL>").
setEnvironment(Environment.SANDBOX).
setAPiKey("<apikey>").
setUserReferenceId("<referenceId>").
setxTargetEnvironment("<target environment>")
setOnInitializationResponse(new TokenInitializeInterface() {
@Override
public void onTokenInitializeSuccess(StatusResponse statusResponse) {
}
@Override
public void onTokenInitializeFailure(MtnError mtnError) {
}
}).
build(this);
This table below describe the details required for disbursement functions
Scenarios | API | Function | Parameters |
---|---|---|---|
Transfer | Transfer | transfer | Transfer transfer,String callbackUrl,RequestStateInterface requestStateInterface |
Transfer status | getTransferStatus | String referenceId,TransferStatusInterface transferStatusInterface | |
Delivery notification | requestToPayDeliveryNotification | String referenceId,RequestStateInterface requestStateInterface | |
Validate account holder | ValidateAccount Account holder | validateAccountHolderStatus | AccountHolder accountHolder,ValidateAccountInterface validateAccountInterface |
Get Balance | Account Balance | getAccountBalance | RequestBalanceInterface requestBalanceInterface |
Get Balance in specific currency | Get account balance in specific currency | getAccountBalanceInSpecificCurrency | RequestBalanceInterface requestBalanceInterface |
Deposit | Deposit V1 | depositV1 | Deposit deposit,RequestInterface requestInterface |
Deposit V2 | depositV2 | Deposit deposit,RequestInterface requestInterface | |
Deposit status | getDepositStatus | String requestReferenceId,DepositStatusInterface depositStatusInterfacee | |
Refund | Refund V1 | refundV1 | Refund refund,RequestInterface requestInterface |
Refund V2 | refundV2 | Refund refund,RequestInterface requestInterface | |
Refund status | getRefundStatus | String requestReferenceId,RefundStatusInterfacer refundStatusInterface | |
Validate Consumer Identity | Validate Consumer Identity | getBasicUserInfo | String msisdnId,UserInfoInterface userInfoInterface |
Get Consumer Information with Consent | Get Consumer Information with Consent | getUserInfoWithConsent | AccountHolder accountHolder,Enum Accesstype,String scope,UserConsentInterface userConsentInterface |
Remittances is a solution that enables a customer to transfer or receive funds from the diaspora to Mobile Money recipient's account in local currency. This is an automated solution where the money is transferred in real-time when the request hits the system (works in a similar way as the automated Disbursements solution).
The remittance configuration object is being initialized with a builder pattern,The paramater being set include
-
subscriptionKey:The subscription key is used to give access to APIs in the API Manager portal. A user is assigned a subscription Key as and when the user subscribes to products in the API Manager Portal.
-
subscriptionType: The type of subscription (in this case, a collection).
-
callBackUrl:The URL where the payment gateway or mobile money service should send notifications or callbacks
-
environment:The environment (sandbox or production) in which the momo api service is being used.
-
apikey: An api key for accessing the momo api services
-
userReferenceId: A reference ID for the user initiating the collection request
-
xTargetEnvironment: The identifier of the EWP system where the transaction shall be processed. This parameter is used to route the request to the EWP system that will initiate the transaction.
RemittanceConfiguration remittanceConfiguration = new RemittanceConfiguration.
RemittanceConfigurationBuilder().
setSubscriptionKey("<subsriptionkey>").
setSubscriptionType(SubscriptionType.REMITTANCE).
setCallBackUrl("<callbackURL>").
setEnvironment(Environment.SANDBOX).
setAPiKey("<apikey>").
setUserReferenceId("<referenceId>").
setxTargetEnvironment("<target environment>")
setOnInitializationResponse(new TokenInitializeInterface() {
@Override
public void onTokenInitializeSuccess(StatusResponse statusResponse) {
}
@Override
public void onTokenInitializeFailure(MtnError mtnError) {
}
}).
build(this);
This table below describe the details required for remittance functions
Scenarios | API | Function | Parameters |
---|---|---|---|
Transfer | Transfer | transfer | Transfer transfer,String callbackUrl,RequestStateInterface requestStateInterface |
Transfer status | getTransferStatus | String referenceId,TransferStatusInterface transferStatusInterface | |
Delivery notification | requestToPayDeliveryNotification | String referenceId,RequestStateInterface requestStateInterface | |
Validate account holder | ValidateAccount Account holder | validateAccountHolderStatus | AccountHolder accountHolder,ValidateAccountInterface validateAccountInterface |
Get Balance | Account Balance | getAccountBalance | RequestBalanceInterface requestBalanceInterface |
Get Balance in specific currency | Get account balance in specific currency | getAccountBalanceInSpecificCurrency | RequestBalanceInterface requestBalanceInterface |
Validate Consumer Identity | Validate Consumer Identity | getBasicUserInfo | String msisdnId,UserInfoInterface userInfoInterface |
Get Consumer Information with Consent | Get Consumer Information with Consent | getUserInfoWithConsent | AccountHolder accountHolder,Enum Accesstype,String scope,UserConsentInterface userConsentInterface |