Skip to content

Commit

Permalink
Refactors and updates documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
Regis Bamba [ MTN Cote d'Ivoire ] authored and Regis Bamba [ MTN Cote d'Ivoire ] committed Apr 30, 2019
1 parent c97dc03 commit e649265
Show file tree
Hide file tree
Showing 16 changed files with 413 additions and 459 deletions.
90 changes: 62 additions & 28 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,16 +1,19 @@
# MoMo API Java Client

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/regisbamba/momoapi-java/blob/master/License.md) [![Release](https://jitpack.io/v/regisbamba/momoapi-java.svg)](https://jitpack.io/#regisbamba/momoapi-java) [![Build Status](https://travis-ci.org/regisbamba/momoapi-java.svg?branch=master)](https://travis-ci.org/regisbamba/momoapi-java) [![codecov](https://codecov.io/gh/regisbamba/momoapi-java/branch/master/graph/badge.svg)](https://codecov.io/gh/regisbamba/momoapi-java)

This library helps you consume the new MTN Mobile Money API ([MoMo API](https://momodeveloper.mtn.com)).

Features :

- Support for Collections, Disbursements, Remittances
- Support for Sandbox User provisioning
- Automatically generate tokens for your requests, eg: collections.getAccountBalance() // no need to get token

## 1. Installation

To get started, you first have to add the JitPack repository to your root build.gradle file at the end of repositories section.

```
allprojects {
repositories {
Expand All @@ -21,6 +24,7 @@ allprojects {
```

Then, add the dependency to your dependencies section

```
dependencies {
implementation 'com.github.regisbamba:momoapi-java:{latest-version}'
Expand All @@ -30,15 +34,18 @@ dependencies {
For other build systems, please see instructions on [Jitpack's website](https://jitpack.io/#regisbamba/momoapi-java).

## 2. Prerequesite

Before everything else, make sure you open an account on the ([MoMo API](https://momodeveloper.mtn.com)) portal.
You will need to subscribe to products on the portal before you can use them through the API and this client.

## 3. Consuming resources from the API

This library uses Reactive Programming via [RxJava](https://github.com/ReactiveX/RxJava). All API resources are provided via **Observable** streams.

When you make a request, you can get the results by subscribing to the Observable and check whether the request was successful or not.

Eg: Getting the balance for your account.

```java
collections.getAccountBalance().subscribe(
new Consumer<AccountBalance>() {
Expand All @@ -49,7 +56,9 @@ collections.getAccountBalance().subscribe(
}
);
```
You can also consume error events in case of the API request failed.

You can also consume error events in case the API request failed.

```java
collections.getAccountBalance().subscribe(
new Consumer<AccountBalance>() {
Expand All @@ -70,6 +79,7 @@ collections.getAccountBalance().subscribe(
```

If you use Java 8, you can use lambda functions for more clarity.

```java
collections.getAccountBalance().subscribe(accountBalance -> { // This function executes in case of success.
System.out.println(accountBalance.getAvailableBalance()); // 900
Expand All @@ -92,15 +102,19 @@ collections.getAccountBalance().subscribe(
## 4. Reference

### 4.1 Create a MoMo client

Create a new MoMo client by specifying the environment (either SANDBOX OR PRODUCTION).

```java
MoMo momo = new MoMo(Environment.SANDBOX);
```

### 4.2 Authenticate your requests

According to [documentation](https://momodeveloper.mtn.com/api-documentation/api-description/), the credentials to be used are :
- Subscription Key
- API User and API Key to generate a Bearer Token for Oauth 2.0

- Subscription Key
- API User and API Key to generate a Bearer Token for Oauth 2.0

The Subscription Key is available when you subscribe to a product via the portal.

Expand All @@ -111,63 +125,72 @@ The API User and API Key are used to grant access to the wallet system in a spec

In simple terms, if you are in production you should copy and paste API User and API Key from the portal and store them as variables in your code.

If you are in sandbox, use the Provisioning class to generate API User and API Key as explained below.
If you are in sandbox, use the SandboxProvisioning class to generate API User and API Key as explained below.

First get a provisioning instance :

```java
Provisioning provisioning = momo.createProvisioning(subscriptionKey);
```
SandboxProvisioning sandboxProvisioning = momo.createSandboxProvisioning(subscriptionKey);
```

#### 4.2.1 Create an API User (Sandbox Only)

Create an API User and get the referenceId back.

Documentation: https://momodeveloper.mtn.com/docs/services/sandbox-provisioning-api/operations/post-v1_0-apiuser

```java
provisioning.createApiUser().subscribe(referenceId -> {
sandboxProvisioning.createApiUser().subscribe(referenceId -> {
System.out.println(referenceId); // db0fc432-c940-4116-bbd1-887ab663e2a3
});
```

You can also specify a providerCallbackHost parameter.

```java
provisioning.createApiUser("www.myapp.com").subscribe(referenceId -> {
sandboxProvisioning.createApiUser("www.myapp.com").subscribe(referenceId -> {
System.out.println(referenceId); // 0812e642-5692-463b-8dce-370af19802c8
});
```

#### 4.2.2 Create an API Key (Sandbox Only)

Create an API Key using the referenceId from API User.

Documentation: https://momodeveloper.mtn.com/docs/services/sandbox-provisioning-api/operations/post-v1_0-apiuser-apikey?

```java
provisioning.createApiKey(referenceId).subscribe(apiCredentials -> {
sandboxProvisioning.createApiKey(referenceId).subscribe(apiCredentials -> {
System.out.print(apiCredentials.getUser()); // 822b8ea9-cc34-47b8-adcc-23a9a468b0df
System.out.print(apiCredentials.getKey()); // 06796ba6ab714c4990b068dcfac66d88
});
```


#### 4.2.3 Get an API User (Sandbox Only)

Get an API User record.

Documentation: https://momodeveloper.mtn.com/docs/services/sandbox-provisioning-api/operations/get-v1_0-apiuser?

```java
provisioning.getApiUser(referenceId).subscribe(apiUser -> {
sandboxProvisioning.getApiUser(referenceId).subscribe(apiUser -> {
System.out.println(apiUser.getProviderCallbackHost()); // www.myapp.com
System.out.println(apiUser.getTargetEnvironment()); // sandbox
});
```

### 4.3 Get a product instance

To make a request for a particular product, you need to create an instance of that product.

```java
Collections collections = momo.createCollections(subscriptionKey, apiUser, apiKey);
```
```

You can also do so for Disbursements and Remittances.

### 4.4 Collections

The Collections product enable remote collection of bills, fees or taxes.

#### 4.4.1 Create a Token
Expand All @@ -178,7 +201,7 @@ Documentation: https://momodeveloper.mtn.com/docs/services/collection/operations

```java
collections.createToken().subscribe(
token -> {
token -> {
System.out.println(token.getAccessToken()); // eyJ0eXAiOiJKV1QiLCJhbGciOiJSMjU2In0....
System.out.println(token.getExpiresIn()); // 3600
System.out.println(token.getTokenType()); // acess_token
Expand All @@ -190,12 +213,13 @@ collections.createToken().subscribe(

**Please note**: For all requests, you can either create your own token as explained above and pass it to your requests or you can let the client automatically generate it for you.


#### 4.4.2 Request to pay

Request a payment from a consumer (Payer).

Documentation:
https://momodeveloper.mtn.com/docs/services/collection/operations/requesttopay-POST?

```java
float amount = 900;
String currency = "EUR"; // In Sandbox, this should be EUR.
Expand All @@ -212,20 +236,22 @@ collections.requestToPay(amount, currency, externalId, payerPartyId, payerMessag
```

#### 4.4.3 Get a status of a request to pay

Get the status of a request to pay.

Documentation: https://momodeveloper.mtn.com/docs/services/collection/operations/requesttopay-referenceId-GET?

```java
collections.getRequestToPay(referenceId).subscribe(
requestToPay -> {
System.out.println(requestToPay.getFinancialTransactionId()); // 521734614
System.out.println(requestToPay.getStatus()); // SUCCESSFUL
System.out.println(requestToPay.getFinancialTransactionId()); // 521734614
System.out.println(requestToPay.getStatus()); // SUCCESSFUL
}
);
```

#### 4.4.4 Get the balance of the account.

Get the balance of the account.

Documentation: https://momodeveloper.mtn.com/docs/services/collection/operations/get-v1_0-account-balance?
Expand All @@ -238,6 +264,7 @@ collections.getAccountBalance().subscribe(accountBalance -> {
```

#### 4.4.5 Get the status of an account holder

Check if an account holder is registered and active in the system.

Documentation: https://momodeveloper.mtn.com/docs/services/collection/operations/get-v1_0-accountholder-accountholderidtype-accountholderid-active?
Expand All @@ -247,8 +274,9 @@ collections.getAccountStatus("46733123453").subscribe(accountStatus -> {
System.out.println(accountStatus.getResult()); // true
});
```

### 4.5 Disbursements

The Disbursement product lets you automatically deposit funds to multiple users in one transaction.

#### 4.5.1 Create a Token
Expand All @@ -259,7 +287,7 @@ Documentation: https://momodeveloper.mtn.com/docs/services/disbursement/operatio

```java
disbursements.createToken().subscribe(
token -> {
token -> {
System.out.println(token.getAccessToken()); // eyJ0eXAiOiJKV1QiLCJhbGciOiJSMjU2In0....
System.out.println(token.getExpiresIn()); // 3600
System.out.println(token.getTokenType()); // acess_token
Expand All @@ -271,12 +299,13 @@ disbursements.createToken().subscribe(

**Please note**: For all requests, you can either create your own token as explained above and pass it to your requests or you can let the client automatically generate it for you.


#### 4.5.2 Transfer

Transfer an amount to a payee account.

Documentation:
https://momodeveloper.mtn.com/docs/services/disbursement/operations/transfer-POST?

```java
float amount = 900;
String currency = "EUR"; // In Sandbox, this should be EUR.
Expand All @@ -293,20 +322,22 @@ disbursements.transfer(amount, currency, externalId, payeePartyId, payerMessage,
```

#### 4.5.3 Get a status of a transfer

Get the status of a transfer.

Documentation: https://momodeveloper.mtn.com/docs/services/disbursement/operations/transfer-referenceId-GET?

```java
disbursements.getTransfer(referenceId).subscribe(
transfer -> {
System.out.println(transfer.getFinancialTransactionId()); // 521734614
System.out.println(transfer.getStatus()); // SUCCESSFUL
System.out.println(transfer.getFinancialTransactionId()); // 521734614
System.out.println(transfer.getStatus()); // SUCCESSFUL
}
);
```

#### 4.5.4 Get the balance of the account.

Get the balance of the account.

Documentation: https://momodeveloper.mtn.com/docs/services/disbursement/operations/get-v1_0-account-balance?
Expand All @@ -319,6 +350,7 @@ disbursements.getAccountBalance().subscribe(accountBalance -> {
```

#### 4.5.5 Get the status of an account holder

Check if an account holder is registered and active in the system.

Documentation: https://momodeveloper.mtn.com/docs/services/disbursement/operations/get-v1_0-accountholder-accountholderidtype-accountholderid-active?
Expand All @@ -330,6 +362,7 @@ disbursements.getAccountStatus("46733123453").subscribe(accountStatus -> {
```

### 4.6 Remittances

The Remittance product lets you automatically deposit funds to multiple users in one transaction.

#### 4.6.1 Create a Token
Expand All @@ -340,7 +373,7 @@ Documentation: https://momodeveloper.mtn.com/docs/services/remittance/operations

```java
remittances.createToken().subscribe(
token -> {
token -> {
System.out.println(token.getAccessToken()); // eyJ0eXAiOiJKV1QiLCJhbGciOiJSMjU2In0....
System.out.println(token.getExpiresIn()); // 3600
System.out.println(token.getTokenType()); // acess_token
Expand All @@ -352,12 +385,13 @@ remittances.createToken().subscribe(

**Please note**: For all requests, you can either create your own token as explained above and pass it to your requests or you can let the client automatically generate it for you.


#### 4.6.2 Transfer

Transfer an amount to a payee account.

Documentation:
https://momodeveloper.mtn.com/docs/services/remittance/operations/transfer-POST?

```java
float amount = 900;
String currency = "EUR"; // In Sandbox, this should be EUR.
Expand All @@ -374,20 +408,22 @@ remittances.transfer(amount, currency, externalId, payeePartyId, payerMessage, p
```

#### 4.6.3 Get a status of a transfer

Get the status of a transfer.

Documentation: https://momodeveloper.mtn.com/docs/services/remittance/operations/transfer-referenceId-GET?

```java
remittances.getTransfer(referenceId).subscribe(
transfer -> {
System.out.println(transfer.getFinancialTransactionId()); // 521734614
System.out.println(transfer.getStatus()); // SUCCESSFUL
System.out.println(transfer.getFinancialTransactionId()); // 521734614
System.out.println(transfer.getStatus()); // SUCCESSFUL
}
);
```

#### 4.6.4 Get the balance of the account.

Get the balance of the account.

Documentation: https://momodeveloper.mtn.com/docs/services/remittance/operations/get-v1_0-account-balance?
Expand All @@ -400,6 +436,7 @@ remittances.getAccountBalance().subscribe(accountBalance -> {
```

#### 4.6.5 Get the status of an account holder

Check if an account holder is registered and active in the system.

Documentation: https://momodeveloper.mtn.com/docs/services/remittance/operations/get-v1_0-accountholder-accountholderidtype-accountholderid-active?
Expand All @@ -409,6 +446,3 @@ remittances.getAccountStatus("46733123453").subscribe(accountStatus -> {
System.out.println(accountStatus.getResult()); // true
});
```



Loading

0 comments on commit e649265

Please sign in to comment.