Android SDK to use MMAPI.
A library that fully covers payment process inside your Android application
This SDK provides for an easy way to connect to GSMA Mobile Money 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.0or newer - Android Platform Version:
API 31 - Build gradle:
4.2.1
Copy the GSMASdk-v1.0.11.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/GSMASdk-v1.0.11.aar')After you install the SDK, make it available to your app and configure SDK.
Configuration details include either sandbox for testing or live for production, and your consumer key, consumer secret, api key, security option and callback url for your app.
In the directory where you installed the SDK, include this code to make the SDK available and configure your environment with your application credentials for sandbox and live environments in the Developer Dashboard.
/**
* Initialise payment configuration with the following
* consumerKey - provided by Client
* consumerSecret - provided by Client
* authenticationType - required level of authentication, eg:AuthenticationType.STANDARD_LEVEL,AuthenticationType.NO_AUTH;
* callbackUrl - server url to which long running operation responses are delivered
* xAPIkey - provided by client
* environment - sandbox or production
*/
PaymentConfiguration.init("<Place your consumerKey>","<Place your consumerSecret>","<Place your AuthenticationType>","<Place your callback URL>","<Place your X API Key>",Environment.SANDBOX);
Create a token if the security option is DEVELOPMENT_LEVEL, STANDARD_LEVEL, ENHANCED_LEVEL,
/**
*Initialise the preference object
*/
PreferenceManager.getInstance().init(this);
/**
* Token creation
*/
SDKManager.getInstance().init(this, new PaymentInitialiseInterface() {
@Override
public void onValidationError(ErrorObject errorObject) {
}
@Override
public void onSuccess(Token token) {
}
@Override
public void onFailure(GSMAError gsmaError) {
}
});
- Merchant Payments
- Disbursements
- International Transfers
- P2P Transfers
- Recurring Payments
- Account Linking
- Bill Payments
- Agent Services
| Scenarios | API | Function | Parameters |
|---|---|---|---|
| Payee-Initiated Merchant Payment | Payee Initiated Merchant Payment | createMerchantTransaction | NotificationMethod, string callBackUrl="",Transaction transactionRequest ,RequestStateInterface requestStateInterface |
| Payee-Initiated Merchant Payment using the Polling Method | Payee Initiated Merchant Payment | createMerchantTransaction | NotificationMethod, string callBackUrl="",Transaction transactionRequest ,RequestStateInterface requestStateInterface |
| Poll to Determine the Request State | viewRequestState | String serverCorrelationId,RequestStateInterface requestStateInterface | |
| Retrieve a Transaction | viewTransaction | String transactionReference | |
| Payer-Initiated Merchant Payment | Payer Initiated Merchant Payment | createMerchantTransaction | NotificationMethod, string callBackUrl="",Transaction transactionRequest ,RequestStateInterface requestStateInterface |
| Payee-Initiated Merchant Payment using a Pre-authorised Payment Code | Obtain an Authorisation Code | createAuthorisationCode | ArrayList identifierList,NotificationMethod, string callBackUrl="",AuthorisationCode authorisationCodeRequest ,RequestStateInterface requestStateInterface |
| Perform a Merchant Payment | createMerchantTransaction | NotificationMethod, string callBackUrl="",Transaction transactionRequest ,RequestStateInterface requestStateInterface | |
| View An Authorisation Code | viewAuthorisationCode | ArrayList identifierList,String transactionReference,AuthorisationCodeItemInterface authorisationCodeItemInterface | |
| Merchant Payment Refund | Perform a Merchant Payment Refund | createRefundTransaction | NotificationMethod, string callBackUrl="",Transaction transactionRequest ,RequestStateInterface requestStateInterface |
| Merchant Payment Reversal | Perform a Merchant Payment Reversal | createReversal | NotificationMethod, string callBackUrl="",String originalTransactionReference,Reversal reversalObject,RequestStateInterface requestStateInterface |
| Obtain a Merchant Balance | Get an Account Balance | viewAccountBalance | ArrayList identifierList,BalanceInterface balanceInterface |
| Retrieve Payments for a Merchant | Retrieve a Set of Transactions for an Account | viewAccountTransactions | ArrayList identifierList,TransactionFilter filter,RetrieveTransactionInterface retrieveTransactionInterface |
| Check for Service Availability | Check for Service Availability | viewServiceAvailability | NA |
| Retrieve a Missing API Response | Retrieve a Missing Response | viewResponse | String correlationId |
| Scenarios | API | Function | Parameters |
|---|---|---|---|
| Individual Disbursement | Create A Disbursement Transaction | createDisbursementTransaction | NotificationMethod, string callBackUrl="",Transaction transactionRequest ,RequestStateInterface requestStateInterface |
| Bulk Disbursement | Create A Transaction Batch | createBatchTransaction | NotificationMethod, string callBackUrl="",BatchTransaction bulkTransactionObject,RequestStateInterface requestStateInterface |
| View A Transaction Batch | viewBatchTransaction | String transactionReference,BatchTransactionItemInterface batchTransactionItemInterface | |
| View Batch Completions | viewBatchCompletions | String batchId,BatchCompletionInterface batchCompletionInterface | |
| View Batch Rejections | viewBatchRejections | String batchId,BatchRejectionInterface batchRejectionInterface | |
| Bulk Disbursement with Maker / Checker | Create A Transaction Batch | createBatchTransaction | NotificationMethod, string callBackUrl="",BatchTransaction bulkTransactionObject,RequestStateInterface requestStateInterface |
| Update A Transaction Batch | updateBatchTransaction | NotificationMethod, string callBackUrl="",String batchId,ArrayList batchArrayList,RequestStateInterface requestStateInterface | |
| View A Transaction Batch | viewBatchTransaction | String transactionReference,BatchTransactionItemInterface batchTransactionItemInterface | |
| View Batch Completions | viewBatchCompletions | String batchId,BatchCompletionInterface batchCompletionInterface | |
| View Batch Rejections | viewBatchRejections | String batchId,BatchRejectionInterface batchRejectionInterface | |
| Individual Disbursement Using the Polling Method | Create a Individual Disbursement request | createDisbursementTransaction | NotificationMethod, string callBackUrl="",Transaction transactionRequest ,RequestStateInterface requestStateInterface |
| Poll to Determine the Request State | viewRequestState | String serverCorrelationId,RequestStateInterface requestStateInterface | |
| Retrieve a Transaction | viewTransaction | String transactionReference | |
| Disbursement Reversal | Perform a Disbursement Reversal | createReversal | NotificationMethod, string callBackUrl="",String originalTransactionReference,RequestStateInterface requestStateInterface |
| Obtain a Disbursement Organisation Balance | Get an Account Balance | viewAccountBalance | ArrayList identifierList,BalanceInterface balanceInterface |
| Retrieve Transactions for a Disbursement Organisation | Retrieve a Set of Transactions for an Account | viewAccountTransactions | ArrayList identifierList,TransactionFilter filter,RetrieveTransactionInterface retrieveTransactionInterface |
| Check for Service Availability | Check for Service Availability | viewServiceAvailability | NA |
| Retrieve a Missing API Response | Retrieve a Missing Response | viewResponse | String correlationId |
| Scenarios | API | Function | Parameters |
|---|---|---|---|
| International Transfer via Hub | Request a International Transfer Quotation | createQuotation | NotificationMethod, string callBackUrl="",Quotation quotationRequest,RequestStateInterface requestStateInterface |
| Perform an International Transfer | createInternationalTransaction | NotificationMethod, string callBackUrl="",Transaction transactionRequest ,RequestStateInterface requestStateInterface | |
| Optional View A Quotation | viewQuotation | String transactionReference,TransactionInterface transactionInterface | |
| Bilateral International Transfer | Request a International Transfer Quotation | createQuotation | NotificationMethod, string callBackUrl="",Quotation quotationRequest,RequestStateInterface requestStateInterface |
| Perform an International Transfer | createInternationalTransaction | NotificationMethod, string callBackUrl="",Transaction transactionRequest ,RequestStateInterface requestStateInterface | |
| Optional View A Quotation | viewQuotation | String transactionReference,TransactionInterface transactionInterface | |
| International Transfer Reversal | Perform a Transaction Reversal | createReversal | NotificationMethod, string callBackUrl="",String referenceId,Reversal reversal,RequestStateInterface requestStateInterface |
| Obtain an FSP Balance | Get an Account Balance | viewAccountBalance | ArrayList identifierList,BalanceInterface balanceInterface |
| Retrieve Transactions for an FSP | Retrieve a Set of Transactions for an Account | viewAccountTransactions | ArrayList identifierList,TransactionFilter filter,RetrieveTransactionInterface retrieveTransactionInterface |
| Check for Service Availability | Check for Service Availability | viewServiceAvailability | NA |
| Retrieve a Missing API Response | Retrieve a Missing Response | viewResponse | String correlationId |
| Scenarios | API | Function | Parameters |
|---|---|---|---|
| P2P Transfer via Switch | Retrieve the Name of the Recipient | viewAccountName | ArrayList identifierArrayList,AccountHolderInterface accountHolderInterface |
| Request a P2P Quotation | createQuotation | NotificationMethod, string callBackUrl="",Quotation quotationRequest,RequestStateInterface requestStateInterface | |
| Optional Perform a P2P Transfer | createTransferTransaction | NotificationMethod, string callBackUrl="",Transaction transactionRequest ,RequestStateInterface requestStateInterface | |
| Bilateral P2P Transfer | Retrieve the Name of the Recipient | viewAccountName | ArrayList identifierArrayList,AccountHolderInterface accountHolderInterface |
| Perform a P2P Transfer | createTransferTransaction | NotificationMethod, string callBackUrl="",Quotation quotationRequest,RequestStateInterface requestStateInterface | |
| ‘On-us’ P2P Transfer Initiated by a Third Party Provider | Retrieve the Name of the Recipient | viewAccountName | ArrayList identifierArrayList,AccountHolderInterface accountHolderInterface |
| Request a P2P Quotation | createQuotation | NotificationMethod, string callBackUrl="",Quotation quotationRequest,RequestStateInterface requestStateInterface | |
| Perform a P2P Transfer | createTransferTransaction | NotificationMethod, string callBackUrl="",Transaction transactionRequest ,RequestStateInterface requestStateInterface | |
| P2P Transfer Reversal | Perform a Transaction Reversal | createReversal | NotificationMethod, string callBackUrl="",String referenceId,Reversal reversal,RequestStateInterface requestStateInterface |
| Obtain an FSP Balance | Get an Account Balance | viewAccountBalance | ArrayList identifierList,BalanceInterface balanceInterface |
| Retrieve Transactions for an FSP | Retrieve a Set of Transactions for an Account | viewAccountTransactions | ArrayList identifierList,TransactionFilter filter,RetrieveTransactionInterface retrieveTransactionInterface |
| Check for Service Availability | Check for Service Availability | viewServiceAvailability | NA |
| Retrieve a Missing API Response | Retrieve a Missing Response | viewResponse | String correlationId |
Contains functions for all the use case scenarios within Recurring Payments.
| Scenarios | API | Function | Parameters |
|---|---|---|---|
| Setup a Recurring Payment | Setup a Recurring Payment | createAccountDebitMandate | NotificationMethod, string callBackUrl="",DebitMandateRequest debitMandateRequest,ArrayList identifierArrayList,RequestStateInterface requestStateInterface |
| Take a Recurring Payment | Take a Recurring Payment | createMerchantTransaction | NotificationMethod, string callBackUrl="",Transaction transaction,RequestStateInterface requestStateInterface |
| Take a Recurring Payment using the Polling Method | Take a Recurring Payment | createMerchantTransaction | NotificationMethod, string callBackUrl="",Transaction transaction,RequestStateInterface requestStateInterface |
| Poll to Determine the Request State | viewRequestState | String serverCorrelationId | |
| Retrieve a Transaction | viewTransaction | String transactionReference | |
| Recurring Payment Refund | Perform a Recurring Payment Refund | createRefundTransaction | NotificationMethod, string callBackUrl="",Transaction transaction,RequestStateInterface requestStateInterface |
| Recurring Payment Reversal | Perform a Merchant Payment Reversal | createReversal | NotificationMethod, string callBackUrl="",String originalTransactionReference,Reversal reversalObject,RequestStateInterface requestStateInterface |
| Payer sets up a Recurring Payment using MMP Channel | Setup a Recurring Payment | createAccountDebitMandate | NotificationMethod, string callBackUrl="",DebitMandateRequest debitMandateRequest,ArrayList identifierArrayList,RequestStateInterface requestStateInterface |
| Obtain a Service Provider Balance | Get an Account Balance | viewAccountBalance | ArrayList identifierList,BalanceInterface balanceInterface |
| Retrieve Payments for a Service Provider | Retrieve a Set of Transactions for an Account | viewAccountTransactions | ArrayList identifierList,TransactionFilter filter,RetrieveTransactionInterface retrieveTransactionInterface |
| Check for Service Availability | Check for Service Availability | viewServiceAvailability | NA |
| Retrieve a Missing API Response | Retrieve a Missing Response | viewResponse | String correlationId |
| Scenarios | API | Function | Parameters |
|---|---|---|---|
| Common | Obtain a Financial Service Provider Balance | viewAccountBalance | ArrayList identifierList,BalanceInterface balanceInterface |
| Check for Service Availability | viewServiceAvailability | NA | |
| Retrieve a Missing API Response | viewResponse | String correlationId | |
| Setup an Account Link | Establish an Account to Account Link | createAccountLink | NotificationMethod, string callBackUrl="",ArrayList identifierArrayList,Link accountLinkObject,RequestStateInterface requestStateInterface |
| Perform a Transfer for a Linked Account | Use a Link to make a Transfer | createTransferTransaction | NotificationMethod, string callBackUrl="",Transaction transaction,RequestStateInterface requestStateInterface |
| Perform a Transfer using an Account Link via the Polling Method | Use a Link to make a Transfer | createTransferTransaction | NotificationMethod, string callBackUrl="",Transaction transaction,RequestStateInterface requestStateInterface |
| Poll to Determine the Request State | viewRequestState | String serverCorrelationId | |
| Retrieve a Transaction | viewTransaction | String transactionReference | |
| Perform a Transfer Reversal | Perform a Transaction Reversal | createReversal | NotificationMethod, string callBackUrl="",String originalTransactionReference,Reversal reversalObject,RequestStateInterface requestStateInterface |
| Retrieve Transfers for a Financial Service Provider | Retrieve a Set of Transactions for an Account | viewAccountTransactions | ArrayList identifierList,TransactionFilter filter,RetrieveTransactionInterface retrieveTransactionInterface |
| Read a specific link for a given account. | Read a specific link for a given account | viewAccountLink | ArrayList identifierList,String transactionReference,AccountLinkInterface accountLinkInterface |
| Scenarios | API | Function | Parameters |
|---|---|---|---|
| Successful Retrieval of Bills | Retrieve a Set of Bills | viewAccountBills | ArrayList identifierList,TransactionFilter filter,RetrieveBillPaymentInterface retrieveBillPaymentInterface |
| Make a Successful Bill Payment with Callback | Create a Bill Transaction | createBillTransaction | NotificationMethod, string callBackUrl="",Transaction transaction,RequestStateInterface requestStateInterface |
| Make a Bill Payment | createBillPayment | NotificationMethod, string callBackUrl="",ArrayList identifierList,BillPayment billPayment,String billReference,RequestStateInterface requestStateInterface | |
| Make a Bill Payment with Polling | Make a Bill Payment | createBillPayment | NotificationMethod, string callBackUrl="",ArrayList identifierList,BillPayment billPayment,String billReference,RequestStateInterface requestStateInterface |
| Poll to Determine the Request State | viewRequestState | String serverCorrelationId | |
| Retrieve Bill Payments for a Given Bill | viewBillPayment | ArrayList identifierList,TransactionFilter filter,String billReference,BillPaymentInterface billPaymentInterface | |
| Retrieval of Bill Payments | Retrieve a Set of Bill Payments | viewBillPayment | ArrayList identifierList,TransactionFilter filter,String billReference,BillPaymentInterface billPaymentInterface |
| Check for Service Availability | Check for Service Availability | viewServiceAvailability | NA |
| Retrieve a Missing API Response | Retrieve a Missing Response | viewResponse | String correlationId |
| Scenarios | API | Function | Parameters |
|---|---|---|---|
| Agent-initiated Cash-out | Agent Initiated Cash-Out | createWithdrawalTransaction | NotificationMethod, string callBackUrl="",Transaction transaction,RequestStateInterface requestStateInterface |
| Agent-initiated Cash-out using the Polling Method | Agent Initiated Cash-out | createWithdrawalTransaction | NotificationMethod, string callBackUrl="",Transaction transaction,RequestStateInterface requestStateInterface |
| Poll to Determine the Request State | viewRequestState | String serverCorrelationId,RequestStateInterface requestStateInterface | |
| Retrieve a Transaction | viewTransaction | String transactionReference,TransactionInterface transactionInterface | |
| Customer-initiated Cash-out | Customer Initiated Cash-Out | createWithdrawalTransaction | NotificationMethod, string callBackUrl="",Transaction transaction,RequestStateInterface requestStateInterface |
| Customer Cash-out at an ATM using an Authorisation Code | Obtain an Authorisation Code | createAuthorisationCode | NotificationMethod, string callBackUrl="",ArrayList identifierList,AuthorizationCode authorizationCode,RequestStateInterface requestStateInterface |
| ATM Initiated Cash-Out | createWithdrawalTransaction | NotificationMethod, string callBackUrl="",Transaction transaction,RequestStateInterface requestStateInterface | |
| Retrieve Authorisation Code | viewAuthorisationCode | ArrayList identifierList,String transactionReference,AuthorisationCodeItemInterface authorisationCodeItemInterface | |
| Agent-initiated Customer Cash-in | Retrieve the Name of the Depositing Customer | viewAccountName | ArrayList identifierList,AccountHolderInterface accountHolderInterface |
| Agent Initiated Cash-in | createDepositTransaction | NotificationMethod, string callBackUrl="",Transaction transaction,RequestStateInterface requestStateInterface | |
| Cash-out Reversal | Perform a Transaction Reversal | createReversal | NotificationMethod, string callBackUrl="",String originalTransactionReference,Reversal reversalObject,RequestStateInterface requestStateInterface |
| Register a Customer Mobile Money Account | Create a Mobile Money Account | createAccount | NotificationMethod, string callBackUrl="",Account accountRequest,RequestStateInterface requestStateInterface |
| Verify the KYC of a Customer | Retrieve Account Information | viewAccount | ArrayList identifierList,AccountInterface accountInterface |
| Update KYC Verification Status | updateAccountIdentity | NotificationMethod, string callBackUrl="",String identityId,ArrayList patchDataArrayList,ArrayList identifierArrayList,RequestStateInterface requestStateInterface | |
| Obtain an Agent Balance | Obtain an Agent Balance | viewAccountBalance | ArrayList identifierList,BalanceInterface balanceInterface |
| Retrieve Transactions for an Agent | Retrieve a Set of Transactions for an Account | viewAccountTransactions | ArrayList identifierList,TransactionFilter filter,String billReference,BillPaymentInterface billPaymentInterface |
| Check for Service Availability | Check for Service Availability | viewServiceAvailability | NA |
| Retrieve a Missing API Response | Retrieve a Missing Response | viewResponse | String correlationId |
The test package contains the test cases. These are logically divided into unit and integration tests.
Those tests are located in test directory of GSMASdk Module com.gsmaSdk.gsma(test) and are responsible for ensuring each class is behaving as expected,
without considering the rest of the system. Unit tests heavily leverage mocking and are an essential part of our testing harness.Clone the repository and open in androud studio to run integration and unit tests
Those tests are located in Test app under GSMATest Module and are responsible for ensuring a proper communication with server/simulator. With the integration tests, we ensure all communications between the SDK and the server/simulator are behaving accordingly.
For integration test:
- Run the test application in real device or emulator
- Select a module and click on a function,if the function passes a tick mark is shown near to the fields otherwise a cross sign to the correspondibg fields
- Mandatory fields are compared with response from the API to ensure that whether the test succeed or not