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;
-
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.
-
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
- 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.
- 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
![]() |
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. |
![]() |
Step 1 – Fill in your Information
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
mmdepositThis 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{ |
Success Result
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
|
Success Result
} 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
|
Success Result
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;
checkbalanceThis 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{ |
Success Result
Failure Result
|
Mobile Money Incoming Sample in php
<!--?php //Testing Mobile money incoming $url = 'https://www.easypay.co.ug/api/'; $payload = ( '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;
Mobile Money Outgoing Sample in php
<!--?php //Testing Mobile money payout $url = 'https://www.easypay.co.ug/api/'; $payload = ( '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 $post = file_get_contents('php://input'); $data = json_decode($post); $reference=$data->reference; //This is your order 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 //With the above details you can update your system and mark order as paid on your side