Bill Payment via REST API (Java)

You can use our APIs to make bill payments.

This tutorial will walk you through a simple approach to integrating MOALA APIs for performing a bill payment transaction.

Prerequisites

Before you begin, make sure you have the following:

An account on the MOALA portal with the necessary permissions to perform deposits. You can create an account and obtain your API keys by following this guide: Getting Access Keys
A development environment with Java installed
The Apache HttpClient library for sending HTTP requests

Signature Generation

The following code will be used to compute the signature for each request sent to the server.

The generateSignature function calculates the signature of the request to be sent.

// Generate the request signature
import org.apache.commons.codec.digest.HmacUtils;

public class Utils {
    public static String generateSignature(String secretKey, String timestamp, String method, String endpoint, String payload) throws Exception {
        // Build the message to hash
        String message = timestamp + method + endpoint + payload;

        // Compute the signature
        String signature = HmacUtils.hmacSha256Hex(secretKey, message);

        // Return the signature
        return signature;
    }
}

1. Authentication

The MOALA API requires three headers for authentication and secure transactions:

LP-ACCESS-KEY: Your MOALA API access key (obtained from the MOALA portal)
LP-ACCESS-TIMESTAMP: The timestamp of the request in seconds
LP-ACCESS-SIGN: A signature generated using the LP-ACCESS-KEY secret key

The LP-ACCESS-SIGN signature is generated using the HMAC-SHA256 algorithm over a concatenation of the key, timestamp, and request body.

2. Perform the Payment

We will now perform a bill payment using the MOALA REST APIs.

Payment Operation Endpoint

To make a payment operation, use the following endpoint along with the serviceCode corresponding to the operator.

POST https://api.moala.africa/v1/api/transaction/payment

info

The valid serviceCode values for this endpoint are:

CASHOUT_MTN_CM: MTN Cameroon cashout
CASHOUT_ORANGE_CM: Orange Cameroon cashout
CASHOUT_AIRTEL_GA: Airtel Gabon cashout
CASHOUT_MOOV_GA: Moov Gabon cashout
PAIEMENTMARCHAND_MTN_CM: MTN Cameroon merchant payment
PAIEMENTMARCHAND_ORANGE_CM: Orange Cameroon merchant payment
PAIEMENTMARCHAND_AIRTEL_GA: Airtel Gabon merchant payment
PAIEMENTMARCHAND_MOOV_GA: Moov Gabon merchant payment

Sending the Merchant Payment Request

Now, let's build and send a request using the merchant payment API.

import Utils;

import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;
import com.google.gson.Gson;

import java.time.Instant;
import java.util.HashMap;
import java.util.Map;


public class MerchantPayment {
    private static final String API_KEY = "votre_api_key";
    private static final String SECRET_KEY = "votre_secret_key";
    private static final String API_BASE_URL = "https://api.moala.africa";

    public static void makeMerchantPayment(Float amount, String serviceCode, String phoneNumber, String partnerId) {
        try (CloseableHttpClient client = HttpClients.createDefault()) {
            String endpoint = "/v1/api/transaction/payment";
            String url = API_BASE_URL + endpoint;
            long timestamp = Instant.now().getEpochSecond();

            Map body = new HashMap<>();
            body.put("amount", amount);
            body.put("transactionType", "withdrawal");
            body.put("serviceCode", serviceCode);
            body.put("phoneNumber", phoneNumber);
            body.put("partnerId", partnerId);
            String payload = new Gson().toJson(body);

            String method = "POST";
            String signature = Utils.generateSignature(SECRET_KEY, String.valueOf(timestamp), method, endpoint, payload);

            HttpPost req = new HttpPost(url);
            req.setHeader("LP-ACCESS-KEY", API_KEY);
            req.setHeader("LP-ACCESS-TIMESTAMP", String.valueOf(timestamp));
            req.setHeader("LP-ACCESS-SIGN", signature);
            req.setHeader("Content-Type", "application/json");
            req.setEntity(new org.apache.http.entity.StringEntity(payload));

            CloseableHttpResponse response = client.execute(req);
            System.out.println(EntityUtils.toString(response.getEntity()));
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

warning

The partnerId field must be unique for each transaction, otherwise the request will fail.

3. Check Deposit Status

After sending the deposit request, you can check its status using another API call.

Status Check Endpoint

Use the following endpoint to verify the status of a previously submitted transaction.

GET https://api.moala.africa/v1/api/transaction/check/{partnerId}

Sending the Status Check Request

import Utils;

import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;
import java.time.Instant;

public class StatusCheck {
    private static final String API_KEY = "votre_api_key";
    private static final String SECRET_KEY = "votre_secret_key";
    private static final String API_BASE_URL = "https://api.moala.africa";

    public static void checkStatus(String partnerId) {
        try (CloseableHttpClient client = HttpClients.createDefault()) {
            String endpoint = "/v1/api/transaction/check/" + partnerId;
            String url = API_BASE_URL + endpoint;

            long timestamp = Instant.now().getEpochSecond();
            String payload = "";

            String method = "GET";
            String signature = Utils.generateSignature(SECRET_KEY, String.valueOf(timestamp), method, endpoint, payload);

            HttpGet get = new HttpGet(url);
            get.setHeader("LP-ACCESS-KEY", API_KEY);
            get.setHeader("LP-ACCESS-TIMESTAMP", String.valueOf(timestamp));
            get.setHeader("LP-ACCESS-SIGN", signature);

            CloseableHttpResponse response = client.execute(get);
            System.out.println(EntityUtils.toString(response.getEntity()));
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

4. Run the Code

Let’s now run the code presented above.

In this example, we will attempt to make a deposit of 500 XAF from an Orange Money number.

import MerchantPayment;
import StatusCheck;

public static void main(String args[]) {
    String API_KEY = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxx";
    String SECRET_KEY = "yyyyyyyyyyyyyyyyyyyyyyyyyyyy";
    String serviceCode = "PAIEMENTMARCHAND_ORANGE_CM";
    String phoneNumber = "XXXXXXXXX";
    String partnerId = "xxxxxxxx";
    Float amount = 1000f;

    MerchantPayment mechPay = new MerchantPayment();
    mechPay.API_KEY = API_KEY;
    mechPay.SECRET_KEY = SECRET_KEY;
    mechPay.makeMerchantPayment(amount, serviceCode, phoneNumber, partnerId);

    StatusCheck statusCheck = new StatusCheck();
    statusCheck.API_KEY = API_KEY;
    statusCheck.SECRET_KEY = SECRET_KEY;
    statusCheck.checkStatus(partnerId);
}

5. Conclusion

At the end of this tutorial, you now know how to integrate MOALA APIs to perform a bill payment transaction.

Prerequisites​

Signature Generation​

1. Authentication​

2. Perform the Payment​

Payment Operation Endpoint​

Sending the Merchant Payment Request​

3. Check Deposit Status​

Status Check Endpoint​

Sending the Status Check Request​

4. Run the Code​

5. Conclusion​