Open Mobile Money API Uganda – Getting started with MTN, Airtel, Africell and UTL m-sente

Open Mobile Money API for MTN, Airtel, Africell and UTL m-sente Uganda

Open Mobile Money API – EasyPay provides an easy Restful API that makes the process of integrating Mobile Money within your website or system a breeze. Start collecting mobile money instantly for your products or services.

Easypay provides two types of mobile money api;

  1. Mobile Money Deposit Api (Incoming)

    This API allows for you to collect payments from your customers mobile money accounts. This API allows any connected internet device process payments using Mobile money of MTN Uganda or Airtel Uganda. Example applications include e-commerce websites, ticketing systems, school fees systems, insurance, tax collection etc. Basically, if you have any kind of service you want to charge your customers for.

  2. Mobile Money Payout Api (Outgoing)

    This Api allows you to send money from your Easypay account to either MTN, Airtel, Africell or UTL m-sente Mobile Money accounts. This API has a variety of uses like salary payments, bulk payments to suppliers, betting payouts etc.

 

Requirements for Open Mobile Money API

  1. Easypay account; First things first, you need to register for an easypay account. registration is free and painless. Register for an easypay account. Once you have registered and signed in, you will have to enable your API from within the app, so as you can get your credentials in real time.  The process is explained in detail below.
  2. The API is very simple and live so there is no sandbox environment. This helps you get integrated in a matter of minutes,test and get the feel of the API. The Gotcha.  By default all accounts are limited to transactions worth 10USD/month for both incoming and outgoing transactions. To remove this limitation, you will have to contact us with your company details (KYC).

Enable Mobile Money API for MTN, Airtel, Africell and UTL m-sente Uganda

 

Enable Mobile Money API for MTN, Airtel, Africell and UTL m-sente Uganda 1. Go to https://www.easypay.co.ug/app/ and create an account.

2. Sign in and tap the API button shown on the home screen as shown in the image to the left.

3. The enable API screen will load up and offer you a green button to enable API. Tap this button and we proceed to creating and enabling API services for your account.
 

Open Mobile Money API

Step 1 – Fill in your Information

  • Name – This can be your brand or company name.
  • Description – Please describe why you need the API and what you will be using it for.
  • website – The URL to your website
  • IPN URL – Whenever a transaction is confirmed, this is the url that will be posted to with transaction details. IPN – stands for Instant Payment Notification. You will have to provide us a callback (ipn) url to notify your system when payments are made.
  • PIN – Please enter your easypay PIN to confirm enabling your API.

Using instant payment notification model, all your transactions should be marked as pending and only be marked as confirmed from this notification. It is also known as the callback url.

After you click save, your API will be enabled and live. You will be given a client Key and client Password that you will need for authenticating the API functions below.

 

 

Easypay will provide you with the following credentials to make the process quicker;

  1. URL – This is the url you will call to access the API. It is also known as the api entry point or end-point. https://www.easypay.co.ug/api/

Anatomy of Request

The API expects a POST request with a JSON encoded string of request. Every call to the API must have at least the format below. Some methods require extra fields depending on the call.

Payload

{
"username": "your_clientId",
"password": "your_secret",
"action": "do_something",
"paramater":"value"
}

username

This is the API clientId that you are given within app after you enable API. see above

password

 This is the API secret that you are given within app after you enable API. see above

action

 This is the API method being called.

parameter

 This is any extra parameter that the action reguires.

Anatomy of Response

A success response comes in the following JSON format . You have to test the success field to either 1 for success or 0 for failed.

Successful Response

{
"success": 1,
"data": object
}

success This is an integer describing response. 1 for success, 0 for failed transaction
data This is a json object. It can be an array or boolean or integer depending on the request.

Failed Response

{
"success": 0,
"errormsg": "error message here describing failure"
}

Mobile Money Deposit & Payout API

This API contains two methods that facilitate topping up you (incoming) account with mobile money or sending easypay money to mobile money accounts (outgoing).

Mobile Money Deposit involves you asking the user for their phone number and amount they would like to deposit. When successful a network overlay is shown on users mobile phone number asking them to enter their mobile money PIN to approve.

Mobile Money Deposit Charges

These charges are automatically added based on the amount being deposited. It is good practice to display these before confirming the transaction. Easypay charges 3% of the transaction amount when receiving money from  mobile money payments/deposits into your account.

Mobile Money Payout Charges

Easypay charges 3% of the transaction amount + UGX 400 network charge (flat charge), when sending money from your wallet to a mobile money account.

Mobile Money (Incoming) API action

mmdeposit

This method is called when a user wants to move funds from his mobile money account into his wallet. MTN, Airtel, Africell and UTL m-sente supported.

POST URL: https://www.easypay.co.ug/api/
Payload
{
"username": "your client Id",
"password": "your secret",
"action":"mmdeposit",
"amount":500,
"currency":"UGX",
"phone":"mobile money phone number",
"reference":"1",
"reason":"Payment for book"}
  • phone – Phone number including country code e.g for uganda 25677XXXXXXX.
  • action – Leave this as-is ie mmdeposit.
  • amount – Amount to deposit
  • currency – The currency the above amount is in. If it is not UGX amount is then converted to UGX
  • reference – Your order Id, This will be returned in the instant payment notification to your ipn url. It is an integer number.
  • reason – This could be the description of the transaction.

Success Result

{
"success":1,
"data": Object holding transaction receipts
}

Failure Result

{“success”:0,”errormsg”:”Transaction timed out”}

mmpayout

This method is used to send mobile money from the easypay account to the mobile money phone number. MTN, Airtel, Africell and UTL m-sente supported.

POST URL: https://www.easypay.co.ug/api/
Payload

{
"username": "your client id",
"password": "your secret",
"action":"mmpayout",
"amount":1000,
"currency":"UGX",
"phone":"phone number"
}
  • action – Leave this as-is is mmpayout.
  • amount – The amount in currency below
  • currency – the currency of above amount
  • Phone – Phone number including country code e.g for uganda 25677XXXXXXX.

Success Result

{
"success":1,
"data":Object holding transaction receipts

Failed Result

{“success”:0,”errormsg”:”An Error Occured. Make Payment Error: Insufficient Balance in your account”}

Instant Payment Notification

When a mobile money deposit has been successfully completed at the network level. We notify your system using the callback url you supplied us and POST raw JSON data to you. This is not needed for mobile money transactions but is the standard way you should rely on. It works for both card payments and mobile money apis.

{
"phone": "phonenumber",
"reference": "your order id",
"transactionId": "Easypay Transaction ID",
"amount": "1000",
"reason":"your reason or narrative"
}

Other methods worth looking into;

checkbalance

This method is called you want to know your current balance at easypay. You can use this method to notify you that your balance is running low. That way you can ensure you do not run out of float.

POST URL: https://www.easypay.co.ug/api/
Payload
{
"username": "Your clientId",
"password": "Your Secret",
"action": "checkbalance"
}

Success Result

{
"success": 1,
"data": "14129.9",
"currencyCode": "UGX"
}

Failure Result

{
"success": 0,
"errormsg": "something went wrong"
}

Mobile Money Incoming Sample in php

// PHP CODE

 <!--?php <br ?--> //Testing Mobile money incoming 
 $url = 'https://www.easypay.co.ug/api/'; 
 $payload = array( 'username' => '___YOUR CLIENT ID___', 
 'password' => '___YOUR CLIENT SECRET___', 
 'action' => 'mmdeposit', 
 'amount' => 500, 
 'phone'=>'25675XXXXXXX', 
 'currency'=>'UGX', 
 'reference'=>12, 
 'reason'=>'Testing MM DEPOSIT' 
 ); 
  
 //open connection 
 $ch = curl_init(); 
  
 //set the url, number of POST vars, POST data 
 curl_setopt($ch,CURLOPT_URL, $url); 
 curl_setopt($ch,CURLOPT_POSTFIELDS, json_encode($payload)); 
 curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0); 
 curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0); 
 curl_setopt($ch, CURLOPT_CONNECTTIMEOUT ,15); 
 curl_setopt($ch, CURLOPT_TIMEOUT, 400); //timeout in seconds 
 curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); 
 //execute post 
 $result = curl_exec($ch); 
  
 //close connection 
 curl_close($ch); 
 print_r(json_decode($result)); 
 ?>

 

Mobile Money Tutorial for JAVA Programmers

For those of you who use JAVA, Waagana Alex has released two tutorials including code samples to help you get started. Visit the links below;

In three steps Add Mobile Payments to your application using MTN Mobile Money, Airtel Money, Africell Mobile Money and UTL m-sente, Payments to your Android Application, or any other JAVA application

Android Payment Using MTN Mobile Money, Airtel Money, Africell Mobile Money and UTL m-sente, Free Code Project

Mobile Money Incoming Sample in C#

using System;
using System.Collections.Generic;
using System.IO;
using System.Net;
using System.Text;
using System.Web.Script.Serialization;

public String Demo()
{
var js = new JavaScriptSerializer();

var clientId = “xxxxxxxxxxxxxxx”;
var secret = “xxxxxxxxxxxxxxx”;
var action = “mmdeposit”;
var amount = “500”;
var phone = “256XXXXXXXXX”;
var currency = “UGX”;
var reference = “1234”;
var reason = “Testing MM DEPOSIT”;
var url = “https://www.easypay.co.ug/api/”;
var dics = new Dictionary<string, string>();
dics.Add(“username”, clientId);
dics.Add(“password”, secret);
dics.Add(“action”, action);
dics.Add(“amount”, amount);
dics.Add(“currency”, currency);
dics.Add(“phone”, phone);
dics.Add(“reference”, reference);
dics.Add(“reason”, reason);

var payload = js.Serialize(dics);
ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12;
var requestScore = (HttpWebRequest)WebRequest.Create(url);
byte[] data = Encoding.UTF8.GetBytes(payload);
requestScore.Method = “Post”;
requestScore.ContentType = “application/x-www-form-urlencoded”;
requestScore.ContentLength = data.Length;
requestScore.KeepAlive = true;
var stream = requestScore.GetRequestStream();
stream.Write(data, 0, data.Length);
stream.Close();
var responseSorce = (HttpWebResponse)requestScore.GetResponse();
var reader = new StreamReader(responseSorce.GetResponseStream(), Encoding.GetEncoding(“GB2312”));
string content = reader.ReadToEnd();
responseSorce.Close();
return content;
}

 

Mobile Money Outgoing Sample in php

// PHP CODE

 <!--?php <br ?--> //Testing Mobile money payout 
 $url = 'https://www.easypay.co.ug/api/'; 
 $payload = array( 'username' => 'your clientId', 
 'password' => 'your secret', 
 'action' => 'mmpayout', 
 'amount' => 500, 
 'phone'=>'0787xxxxxx' 
 ); 
  
 //open connection 
 $ch = curl_init(); 
  
 //set the url, number of POST vars, POST data 
 curl_setopt($ch,CURLOPT_URL, $url); 
 curl_setopt($ch,CURLOPT_POSTFIELDS, json_encode($payload)); 
 curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0); 
 curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0); 
 curl_setopt($ch, CURLOPT_CONNECTTIMEOUT ,15); 
 curl_setopt($ch, CURLOPT_TIMEOUT, 400); //timeout in seconds 
 curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); 
 //execute post 
 $result = curl_exec($ch); 
  
 //close connection 
 curl_close($ch); 
 print_r(json_decode($result)); 
 ?>

Php sample for IPN or callback

// PHP CODE

 <!--?php $post = file_get_contents('php://input'); $data = json_decode($post); $reference=$data->reference; //This is your order id, mark this as paid<br ?--> $reason=$data->reason; //reason you stated 
 $txid=$data->transactionId; //Easypay transction Id 
 $amount=$data->amount; //amount deposited 
 $phone=$data->phone; //phone number that deposited 
 //With the above details you can update your system and mark order as paid on your side 
 ?>

Was this article helpful?

Yes No

Related Articles

28 Comments

  1. Linn Ug

    Is it possible for me to use this API in my wordpress developed website? I would like to know how to use it

  2. Max

    public function successful_payment()
    {
    $post = file_get_contents(‘php://input’);
    $data = json_decode($post);

    $reference=$data->reference; //This is my appointment id, mark this as paid
    $reason=$data->reason; //reason you stated
    $txid=$data->transactionId; //Easypay transction Id
    $amount=$data->amount; //amount deposited
    $phone=$data->phone; //phone number that deposited
    }

    I use Codeigniter Framework. I supplied my URL as http://localhost/myapplication/controller/successful_payment as my callback URL. Will I get the post data?

    Thank you!

    1. Easypay Moderator

      First off, you need to be on the internet not localhost. Get your code on a real server to get a response posted to you

  3. Tom

    Is it available for Uganda developers? Im from Ghana can I use it as well?

    1. Easypay Moderator

      You can use it if you are collecting from Ugandan Mobile Money channels. As for Ghana, we are working on an expansion for that

    1. Easypay Moderator

      The API is RESTful so any internet connected device can access it and use it 🙂

  6. cfox

    Can I integrate the api in a parse server cloud code (back-end) and if so do you have a java library for front end client mobile application (specifically android)

  7. Ken

    Hi, our business has an Airtel Merchant number — looking to see if we could integrate IPN capability for our ERP systems. Is that something EasyPay can help with?

  8. jitpomi

    just requesting that you improve on your documentation. I can hardly find where to enable the API from on this page.

  9. Kate

    On trying mmdeposit request got the following result:
    {“success”:0,”errormsg”:”FAILED TO COMPLETE TRANSACTION AT TELECOM”}

    Could you suggest the issues, which may cause this kind of failures?

    1. Easypay Moderator

      This issue is caused due to insufficient funds on mobile money account to handle amount+charge

  10. sacco

    Notice: Trying to get property ‘reference’ of non-object in C:\xampp\htdocs\sacco\callback.php on line 4

    Notice: Trying to get property ‘reason’ of non-object in C:\xampp\htdocs\sacco\callback.php on line 5

    Notice: Trying to get property ‘transactionId’ of non-object in C:\xampp\htdocs\sacco\callback.php on line 6

    Notice: Trying to get property ‘amount’ of non-object in C:\xampp\htdocs\sacco\callback.php on line 7

    how can i solve this problem

  11. Kiirya

    How do we add this API in android apps to enable purchase of goods using mobile money.

    1. Easypay Moderator

      This API is json restful, meaning any internet connected device can access it.

    1. Easypay Moderator

      Not really… the IPN is a url on your site that is called when transactions are successful. It is really needed with VISA (3D) as transactions can be forwarded to bank and terminate there. without IPN you would never know the status of these transactions

Leave A Comment?

Enter Captcha Here : *

Reload Image