Open Mobile Money API Uganda – Getting started with MTN, Airtel

Open Mobile Money API for MTN, Airtel

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 new accounts are limited to transactions worth 10USD/month for both incoming and outgoing transactions (For Test Purposes). To remove this limitation, you will have to contact us with your company details (KYC) via our inbuilt chat within app.

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

Enable Mobile Money API for MTN, Airtel 1. Go to https://www.easypay.co.ug/v3/ 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;

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/

Please make sure your have an SSL certificate installed before calling above URL. Your origin must be https.

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. This charge is negotiable when you cross the UGX 50M/Month in collections.

Mobile Money Payout Charges

Amount – UGX  Charge – UGX
0 – 2,500 400
2,501 – 5,000 440
5,001 – 15,000 600
15,001 – 30,000 800
30,001 – 45,000 1000
45,001 – 60,000 1300
60,001 – 125,000 1500
125,001 – 250,000 2000
250,001 – 500,000 5000
500,001 – 1,000,000 7000
1,000,001 – 2,000,000 9000
2,000,001 – 5,000,000 10000

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. This can be alphanumeric and must always be unique for every call of mmdeposit.
  • 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",
"reference":"Your Unique Reference"
}
  • 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":{
"phone": "phonenumber",
"reference": "your order id",
"transactionId": "Easypay Transaction ID",
"amount": "1000",
"reason":"your reason or narrative",
etc
}

}

Failed Result

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

mmstatus

This method returns the status of the mobile money transaction based on the reference you provided to mmdeposit. You can use this method incase you cannot use the IPN approach.

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

{
"username": "your client id",
"password": "your secret",
"action":"mmstatus",
"reference":"reference id"
}
  • action – Leave this as-is is mmstatus.
  • Reference – Reference text you supplied in mmdeposit.

Success Result

{"success":1,"data":{"status":"Success","amount":"1000","charge":"0","reference":"39"}}

Failed Result

{“success”:0,”errormsg”:”This order reference does not exist in our system. “}

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 a library to help you get started. Visit the links below;

Java Plugin

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