GSMA Mobile Money Payments Java SDK

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.

• API Documentation
• Java SDK Documentation
• Java SDK Sample Codes

Index

This document contains the following sections:

• Requirements
• Getting Started
  • Installation
  • Development and Testing
• Setting Up
• Handling Errors
• Use Cases
  • Merchant Payments
  • Disbursements
  • International Transfers
  • P2P Transfers
  • Recurring Payments
  • Account Linking
  • Bill Payments
  • Agent Services
• Testing
• Samples

Requirements

• Java JDK-1.8 or higher
• Apache Maven 3 or higher

Getting Started

Installation

1. Build the jar file using 'mvn clean package' command
2. Copy 'mmapi-java-sdk' jar file to your project's classpath

In order to build the SDK from the source code you need to use Apache Maven and Java 1.8+

• Run 'mvn clean package' to build jar file

Development and Testing

1. Tests for the SDK are in the src/test/java package.
2. Rename config.properties.sample file in src\test\resources to config.properties and replace placeholders with values for your consumer key, consumer secret and api key.
3. From the test package, run JUnit test for each test classes

Setting Up

Initialization of Java SDK

All Java code snippets are listed here. Assumes that you have initialized the Java SDK before using them in your Development Environment. This section details the initialization of the Java SDK.

To initialize the Java SDK, create an instance of the MMClient with consumerKey, counsumerSecret and apiKey

MMClient mmClient = new MMClient("<Place your consumerKey>", "<Place your counsumerSecret>", "<Place your apiKey>");

You always need to create MMClient instance before making any SDK method calls.

By default, this would be in SANDBOX mode with SecurityLevel.DEVELOPMENT

1. consumerKey the API consumer key (can be obtained from developer portal)
2. counsumerSecret the API consumer secret (can be obtained from developer portal)
3. apiKey the API Key (can be obtained from developer portal)

Optional parameters available for MMClient class are:

1. Environment value can be one of the following
   • Environment.SANDBOX for Sandbox
   • Environment.PRODUCTION for Production
2. SecurityLevel value can be one of the following
   • SecurityLevel.DEVELOPMENT for Basic authentication requests
   • SecurityLevel.STANDARD for OAuth2 authentication requests

MMClient class has one optional function:

• addCallBackUrl() - URL for your application where you want MobileMoney API to push data as a PUT request. If you wish to specify different callback urls for different use cases, you can pass the callback url with each request seperately.

You can override the default configuration of MMClient by using either of the following ways:

MMClient mmClient = new MMClient("<Place your consumerKey>", "<Place your counsumerSecret>", "<Place your apiKey>", "<mode>");

Or

MMClient mmClient = new MMClient("<Place your consumerKey>", "<Place your counsumerSecret>", "<Place your apiKey>", "<mode>", "<security level>");

For example:

MMClient mmClient = new MMClient("<Place your consumerKey>", "<Place your counsumerSecret>", "<Place your apiKey>", Environment.SANDBOX, SecurityLevel.DEVELOPMENT);

Handling Errors

Error handling is a crucial aspect of software development. Both expected and unexpected errors should be handled by your code.

The Java SDK provides an MobileMoneyException class that is used for common scenarios where exceptions are thrown. The getError() and getMessage() methods can provide useful information to understand the cause of errors.

List<AccountIdentifier> debitPartyList = new ArrayList<>();
List<AccountIdentifier> creditPartyList = new ArrayList<>();

debitPartyList.add(new AccountIdentifier("msisdn", "+44012345678"));
creditPartyList.add(new AccountIdentifier("walletid", "1"));

Transaction transaction = new Transaction();
transaction.setDebitParty(debitPartyList);
transaction.setCreditParty(creditPartyList);
transaction.setAmount("-16.00");
transaction.setCurrency("USD");

MMClient mmClient = new MMClient("<Place your consumer key>", "<Place your consumer secret>", "<Place your API key>");
MerchantPaymentRequest merchantPaymentRequest = new MerchantPaymentRequest();

merchantPaymentRequest.setTransaction(transaction);

try {
	AsyncResponse sdkResponse = mmClient.addRequest(merchantPaymentRequest).addCallBack("<Place your callback URL>").createMerchantTransaction();
} catch (MobileMoneyException me) {
	System.out.println(me.getMessage());
  	System.out.println(me.getError());
}

Sample Response:

Invalid JSON Field

{
  "errorCategory": "validation",
  "errorCode": "formatError",
  "errorDescription": "Invalid JSON Field",
  "errorDateTime": "2022-01-12T05:30:25.514Z",
  "errorParameters": [
    {
      "key": "amount",
      "value": "must match \"^([0]|([1-9][0-9]{0,17}))([.][0-9]{0,3}[0-9])?$\""
    }
  ]
}

Use Cases

• Merchant Payments
• Disbursements
• International Transfers
• P2P Transfers
• Recurring Payments
• Account Linking
• Bill Payments
• Agent Services

Merchant Payments

Scenarios	API	Function	Parameters
Payee-Initiated Merchant Payment	Payee Initiated Merchant Payment	createMerchantTransaction	NA
Payee-Initiated Merchant Payment using the Polling Method	Payee Initiated Merchant Payment	createMerchantTransaction	NA
	Poll to Determine the Request State	viewRequestState	String serverCorrelationId
	Retrieve a Transaction	viewTransaction	String transactionReference
Payer-Initiated Merchant Payment	Payer Initiated Merchant Payment	createMerchantTransaction	NA
Payee-Initiated Merchant Payment using a Pre-authorised Payment Code	Obtain an Authorisation Code	createAuthorisationCode	Identifiers identifiers
	Perform a Merchant Payment	createMerchantTransaction	NA
	View An Authorisation Code	viewAuthorisationCode	Identifiers identifiers, String authorisationCode
Merchant Payment Refund	Perform a Merchant Payment Refund	createRefundTransaction	NA
Merchant Payment Reversal	Perform a Merchant Payment Reversal	createReversal	String transactionReference
Obtain a Merchant Balance	Get an Account Balance	viewAccountBalance	Identifiers identifiers
Retrieve Payments for a Merchant	Retrieve a Set of Transactions for an Account	viewAccountTransactions	Identifiers identifiers, TransactionFilter filter
Check for Service Availability	Check for Service Availability	viewServiceAvailability	NA
Retrieve a Missing API Response	Retrieve a Missing Response	viewResponse	String clientCorrelationId, Class objectReference

Disbursements

Scenarios	API	Function	Parameters
Individual Disbursement	Create a Individual Disbursement request	createDisbursementTransaction	NA
Bulk Disbursement	Create A Transaction Batch	createBatchTransaction	NA
	View A Transaction Batch	viewBatchTransaction	String batchId
	View Batch Completions	viewBatchCompletions	String batchId
	View Batch Rejections	viewBatchRejections	String batchId
Bulk Disbursement with Maker / Checker	Create A Transaction Batch	createBatchTransaction	NA
	Update A Transaction Batch	updateBatchTransaction	String batchId
	View A Transaction Batch	viewBatchTransaction	String batchId
	View Batch Completions	viewBatchCompletions	String batchId
	View Batch Rejections	viewBatchRejections	String batchId
Individual Disbursement Using the Polling Method	Create a Individual Disbursement request	createDisbursementTransaction	NA
	Poll to Determine the Request State	viewRequestState	String serverCorrelationId
	Retrieve a Transaction	viewTransaction	String transactionReference
Disbursement Reversal	Perform a Disbursement Reversal	createReversal	String transactionReference
Obtain a Disbursement Organisation Balance	Get an Account Balance	viewAccountBalance	Identifiers identifiers
Retrieve Transactions for a Disbursement Organisation	Retrieve a Set of Transactions for an Account	viewAccountTransactions	Identifiers identifiers, TransactionFilter filter
Check for Service Availability	Check for Service Availability	viewServiceAvailability	NA
Retrieve a Missing API Response	Retrieve a Missing Response	viewResponse	String clientCorrelationId, Class objectReference

International Transfers

Scenarios	API	Function	Parameters
International Transfer via Hub	Request a International Transfer Quotation	createQuotation	NA
	Perform an International Transfer	createInternationalTransaction	NA
	Optional View A Quotation	viewQuotation	String quotationReference
Bilateral International Transfer	Request a International Transfer Quotation	createQuotation	NA
	Perform an International Transfer	createInternationalTransaction	NA
	Optional View A Quotation	viewQuotation	String quotationReference
Get a specific request state	Poll to Determine the Request State	viewRequestState	String serverCorrelationId
Get details of a transaction	Retrieve a Transaction	viewTransaction	String transactionReference
International Transfer Reversal	Perform a Transaction Reversal	createReversal	String transactionReference
Obtain an FSP Balance	Get an Account Balance	viewAccountBalance	Identifiers identifiers
Retrieve Transactions for an FSP	Retrieve a Set of Transactions for an Account	viewAccountTransactions	Identifiers identifiers, TransactionFilter filter
Check for Service Availability	Check for Service Availability	viewServiceAvailability	NA
Retrieve a Missing API Response	Retrieve a Missing Response	viewResponse	String correlationId, Class objectReference

P2P Transfers

Scenarios	API	Function	Parameters
P2P Transfer via Switch	Retrieve the Name of the Recipient	viewAccountName	Identifiers identifiers
	Request a P2P Quotation	createQuotation	NA
	Perform a P2P Transfer	createTransferTransaction	NA
Bilateral P2P Transfer	Retrieve the Name of the Recipient	viewAccountName	Identifiers identifiers
	Perform a P2P Transfer	createTransferTransaction	NA
'On-us' P2P Transfer Initiated by a Third Party Provider	Retrieve the Name of the Recipient	viewAccountName	Identifiers identifiers
	Request a P2P Quotation	createQuotation	NA
	Perform a P2P Transfer	createTransferTransaction	NA
Get a specific request state	Poll to Determine the Request State	viewRequestState	String serverCorrelationId
Get details of a transaction	Retrieve a Transaction	viewTransaction	String transactionReference
Get details of a specific quotation	Optional View A Quotation	viewQuotation	String quotationReference
P2P Transfer Reversal	Perform a Transaction Reversal	createReversal	String transactionReference
Obtain an FSP Balance	Get an Account Balance	viewAccountBalance	Identifiers identifiers
Retrieve Transactions for an FSP	Retrieve a Set of Transactions for an Account	viewAccountTransactions	Identifiers identifiers, TransactionFilter filter
Check for Service Availability	Check for Service Availability	viewServiceAvailability	NA
Retrieve a Missing API Response	Retrieve a Missing Response	viewResponse	String clientCorrelationId, Class objectReference

Recurring Payments

Scenarios	API	Function	Parameters
Setup a Recurring Payment	Setup a Recurring Payment	createAccountDebitMandate	Identifiers identifiers
Take a Recurring Payment	Take a Recurring Payment	createMerchantTransaction	NA
Take a Recurring Payment using the Polling Method	Take a Recurring Payment	createMerchantTransaction	NA
	Poll to Determine the Request State	viewRequestState	String serverCorrelationId
	Retrieve a Transaction	viewTransaction	String transactionReference
Recurring Payment Refund	Perform a Recurring Payment Refund	createRefundTransaction	NA
Recurring Payment Reversal	Perform a Merchant Payment Reversal	createReversal	String transactionReference
Payer sets up a Recurring Payment using MMP Channel	Setup a Recurring Payment	createAccountDebitMandate	Identifiers identifiers
Obtain a Service Provider Balance	Get an Account Balance	viewAccountBalance	Identifiers identifiers
Retrieve Payments for a Service Provider	Retrieve a Set of Transactions for an Account	viewAccountTransactions	Identifiers identifiers, TransactionFilter filter
Check for Service Availability	Check for Service Availability	viewServiceAvailability	NA
Retrieve a Missing API Response	Retrieve a Missing Response	viewResponse	String clientCorrelationId, Class objectReference

Account Linking

Scenarios	API	Function	Parameters
Setup an Account Link	Establish an Account to Account Link	createAccountLink	Identifiers identifiers
Perform a Transfer for a Linked Account	Use a Link to make a Transfer	createTransferTransaction	NA
Perform a Transfer using an Account Link via the Polling Method	Use a Link to make a Transfer	createTransferTransaction	NA
	Poll to Determine the Request State	viewRequestState	String serverCorrelationId
	Retrieve a Transaction	viewTransaction	String transactionReference
Perform a Transfer Reversal	Perform a Transaction Reversal	createReversal	String transactionReference
Obtain a Financial Service Provider Balance	Get an Account Balance	viewAccountBalance	Identifiers identifiers
Retrieve Transfers for a Financial Service Provider	Retrieve a Set of Transactions for an Account	viewAccountTransactions	Identifiers identifiers
Check for Service Availability	Check for Service Availability	viewServiceAvailability	NA
Retrieve a Missing API Response	Retrieve a Missing Response	viewResponse	String clientCorrelationId, Class objectReference

Bill Payments

Scenarios	API	Function	Parameters
Successful Retrieval of Bills	Retrieve a Set of Bills	viewAccountBills	Identifiers identifiers
Make a Successful Bill Payment with Callback	Create a Bill Transaction	createBillTransaction	NA
	Make a Bill Payment	createBillPayment	Identifiers identifiers, String billReference
Make a Bill Payment with Polling	Make a Bill Payment	createBillPayment	Identifiers identifiers, String billReference
	Poll to Determine the Request State	viewRequestState	String serverCorrelationId
	Retrieve Bill Payments for a Given Bill	viewBillPayment	Identifiers identifiers, String billReference
Retrieval of Bill Payments	Retrieve a Set of Bill Payments	viewBillPayment	Identifiers identifiers, String billReference
Check for Service Availability	Check for Service Availability	viewServiceAvailability	NA
Retrieve a Missing API Response	Retrieve a Missing Response	viewResponse	String clientCorrelationId, Class objectReference

Agent Services

Scenarios	API	Function	Parameters
Agent-initiated Cash-out	Agent Initiated Cash-Out	createWithdrawalTransaction	NA
Agent-initiated Cash-out using the Polling Method	Agent Initiated Cash-out	createWithdrawalTransaction	NA
	Poll to Determine the Request State	viewRequestState	String serverCorrelationId
	Retrieve a Transaction	viewTransaction	String transactionReference
Customer-initiated Cash-out	Customer Initiated Cash-Out	createWithdrawalTransaction	NA
Customer Cash-out at an ATM using an Authorisation Code	Obtain an Authorisation Code	createAuthorisationCode	Identifiers identifiers
	ATM Initiated Cash-Out	createWithdrawalTransaction	NA
	Retrieve Authorisation Code	viewAuthorisationCode	Identifiers identifiers, String authorisationCode
Agent-initiated Customer Cash-in	Retrieve the Name of the Depositing Customer	viewAccountName	Identifiers identifiers
	Agent Initiated Cash-in	createDepositTransaction	NA
Cash-out Reversal	Perform a Transaction Reversal	createReversal	String transactionReference
Register a Customer Mobile Money Account	Create a Mobile Money Account	createAccount	NA
Verify the KYC of a Customer	Retrieve Account Information	viewAccount	Identifiers identifiers
	Update KYC Verification Status	updateAccountIdentity	Identifiers identifiers, String identityId
Obtain an Agent Balance	Obtain an Agent Balance	viewAccountBalance	Identifiers identifiers
Retrieve Transactions for an Agent	Retrieve a Set of Transactions for an Account	viewAccountTransactions	Identifiers identifiers, TransactionFilter filter
Check for Service Availability	Check for Service Availability	viewServiceAvailability	NA
Retrieve a Missing API Response	Retrieve a Missing Response	viewResponse	String clientCorrelationId, Class objectReference

Testing

The test package contains the test cases. These are logically divided into unit and integration tests.

Unit tests

Those tests are located in src/test/java/com/mobilemoney/unit 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.

To run unit tests,

mvn test -Dtest=com.mobilemoney.unit.**

Integration tests

Those tests are located in src/test/java/com/mobilemoney/integration 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:

• You will need a valid consumer key, consumer secret and api key.
• Copy the config.properties.sample file to config.properties and enter your credentials in the appropriate fields.

To run the integration tests,

mvn test -Dtest=com.mobilemoney.integration.**

To run tests individually:

mvn test -Dtest=path/to/test/class/file

For example:

mvn test -Dtest=com.mobilemoney.unit.merchantpayment.MerchantPaymentTest.java

Execute all tests (unit + integration)

mvn test

Samples

The sample code snippets are all completely independent and self-contained. You can analyze them to get an understanding of how a particular method can be implemented in your application. Sample code snippets can be found here. Steps to run the sample code snippets are as follows:

• Clone this repository:

git clone https://github.com/gsmainclusivetechlab/mmapi-java-sdk.git

• Import mmapi-java-sdk-samples project into your IDE
• Copy 'mmapi-java-sdk' jar file to your project's classpath
• Rename config.properties.sample file in src\test\resources to config.properties and replace placeholders with values for your consumer key, consumer secret and api key.

For example:

CONSUMER_KEY=<your_consumer_key_here>
CONSUMER_SECRET=<your_consumer_secret_here>
API_KEY=<your_api_key_here>
CALLBACK_URL=<your_callback_url_here>

You are now ready to run your sample codes.

• Run individual samples