Contents
- 1 Open Mobile Money API for MTN, Airtel, Africell and UTL m-sente Uganda
- 2 Requirements for Open Mobile Money API
- 3 Enable Mobile Money API for MTN, Airtel, Africell and UTL m-sente Uganda
- 4 Step 1 – Fill in your Information
- 5 Anatomy of Request
- 6 Anatomy of Response
- 7 Mobile Money Deposit & Payout API
- 8 Instant Payment Notification
- 9 Other methods worth looking into;
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;
-
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 all accounts are limited to transactions worth 100USD/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
![]() |
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.
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”} |
validatemomo This method returns users name bound to the phone number supplied at telecom level. It gives the name attached on the mobile money account. This can be used for confirmation purposes POST URL: https://www.easypay.co.ug/api/ |
|
Payload
|
Success Result
Failed Result {“success”:0,”errormsg”:”Unknown”} |
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
Is it possible for me to use this API in my wordpress developed website? I would like to know how to use it
yes, we are releasing a plugin to repository but if you cant wait contact us at info@easypay.co.ug and we shall email it to you
You can get our wordpress plugin from https://wordpress.org/plugins/easypay-mobile-money/
Thanks but are we, the django developers catered for in anyway?
I wanted to implement your apis but I don’t seem to find my help
Thanks
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!
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
you can work from localhost as well
It can but you will not benefit from instant payment notifications, you will have to use mmstatus and paybillstatus to know final status of your transactions
Is it available for Uganda developers? Im from Ghana can I use it as well?
You can use it if you are collecting from Ugandan Mobile Money channels. As for Ghana, we are working on an expansion for that
What about getting user registration details given number before using sending api. Usually required for confirmation purposes , like the one MTN offers in their USSD client.
e.g https://www.easypay.co.ug/api/getUserInfo?number=%5BphoneNo%5D
Is it possible to integrate the api in an android application?
The API is RESTful so any internet connected device can access it and use it 🙂
Use that Am sure it will help you
https://waglex.blogspot.com/2019/03/in-three-steps-add-mobile-payments-to.html#more
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)
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?
just requesting that you improve on your documentation. I can hardly find where to enable the API from on this page.
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?
This issue is caused due to insufficient funds on mobile money account to handle amount+charge
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
Our system cannot callback a localhost. please ensure you on a public server that can receive responses. also, research on how to make your xampp server public.
Check out this article on how your can fix this https://stackoverflow.com/questions/822902/access-xampp-localhost-from-internet
i dint set anything but works on my xampp server(localhost)
Use ragnarok server to work with xammp
yes it will, we now have apis – mmstatus and paybillstatus that can give final status of transaction, so yes can now work on localhost. IPN (callback) notifications fail for localhost as it cannot be reached remotely
How do we add this API in android apps to enable purchase of goods using mobile money.
This API is json restful, meaning any internet connected device can access it.
Use that Am sure it will help you
https://waglex.blogspot.com/2019/03/in-three-steps-add-mobile-payments-to.html#more
Any Java code example?
https://waglex.blogspot.com/2019/03/in-three-steps-add-mobile-payments-to.html#more
check this https://waglex.blogspot.com/2019/03/in-three-steps-add-mobile-payments-to.html#more
Do you provide automatic payment options
yes we do
How can i customize from PEGASUS TECHNOLOGIES LIMITED to my own name?
Thank you
Currently you cannot. To get your own you need to integrate with telcos directly
Can the url be used as the IPN
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
hello how can i embed easy pay on my website to accept donations?
The API is restful and uses POST. so you can create a form that you can put on your website and integrate the api within the form submission function or url to handle logic
If some one deposits UGX.50,000 into my account, how much output remains in my account as net income after all the charges are taken off.
If you deposit 50k, you will have 50k in your account. The person paying is charged 50k plus 3%. https://www.easypay.co.ug/kb/knowledge-base/mobile-money-in-tarrifs-refill-charges/
Sorry, how much output remains if i also use that UGX.50,000 to send UGX.20,000 to another account from my wallet after all charges are taken off.
How do i add this API to an Ecwid e-commerce site?
How do i create a custom message that show on the user’s side while confirming a payment. Its currently bring “Merchant PEGASUS TECHNOLOGIES LIMITED has initiated……….”
At the moment you cannot
is it possible to withdraw my profits from my account using VISA or Master cards say i have traveled
Not at the moment. At the moment, the process is still manual and would require you contact us (InApp) and give us permission to send to your bank account. We are pushing to work with the local banks to have funds delivered to your bank accounts instead.
Does it require connecting the website payments to a bank account where money deposited by customers can be saved or easypay has an account that can hold this cash including big sums for our business
When enabling the API, you are required to register for an Easypay account and that is where money deposited by your customers is saved, then when you wish to withdraw it, you send from your Easypay account to your mobile money account
In case of extra assistance with the API and IPN, which place in Uganda can i visit to find a Easy pay assistant.
Your can contact us on skype, jordah.ferguson for further assistance with the API OR on visit our office in Kampala, Kabalagala at Tirupati mazima mall or call us on phone 0705630793/0787297589.
Thanks I like easy pay
Do you have any python code example for the api intergration ?
is it possible to implement easypay in whmcs
We have no specific extension or plugin but with the right knowledge, you can implement our barebones api in anything that is connected
hello i wanted to ask that when working with the api do we need to first create an html form.
Hello am trying to setup easypay on my website and getting some had time with writing the code am using ajax with pure javascript not jquery wanted some assistance please.
i keep on getting this error.
Access to XMLHttpRequest at ‘https://5804673492e42746:6b2d66987a86d206@www.easypay.co.ug/api/’ from origin ‘https://supreone.com’ has been blocked by CORS policy: No ‘Access-Control-Allow-Origin’ header is present on the requested resource.
Cross-Origin Read Blocking (CORB) blocked cross-origin response https://www.easypay.co.ug/api/ with MIME type application/javascript. See https://www.chromestatus.com/feature/5629709824032768 for more details.
Fatal error: Maximum execution time of 30 seconds exceeded in C:\xampp\htdocs\vlc\users\phpAction\epDeposit.php on line 30
i am getting this error on deposit.. it does not intiate the transaction
Any Help?
By default, the maximum execution time for PHP scripts is set to 30 seconds. If a script runs for longer than 30 seconds, PHP stops the script and reports an error. You can control the amount of time PHP allows scripts to run by changing the max_execution_time directive in your php.ini file.
To change the maximum execution time, use a text editor to modify the max_execution_time directive in your php.ini file. For example, to set the maximum execution time to 10 seconds, use the following setting:
max_execution_time = 120
Hello, am would want to integrate mobile money payment in my final year project which is not hosted but it’s hard. So please some help.
Hello, i already have client id and secret id, my account on Easypay app is 0.0UGX i need your help on how to create POST for setting up my api in my web app, HOW CAN I USE THESE IDs in php to recieve money?
help me #easypay
Hey
Why am I getting this error?
Notice: Constant easypaymentPASS already defined in /home/justhardware/public_html/wp-content/plugins/easypay-mobile-money/easypay-mobile-money.php on line 35
Notice: Constant easypaymentWC_AFFILIATE_KEY already defined in /home/justhardware/public_html/wp-content/plugins/easypay-mobile-money/easypay-mobile-money.php on line 36
Notice: Constant easypaymentWC already defined in /home/justhardware/public_html/wp-content/plugins/easypay-mobile-money/easypay-mobile-money.php on line 31
Notice: Constant easypaymentUSER already defined in /home/justhardware/public_html/wp-content/plugins/easypay-mobile-money/easypay-mobile-money.php on line 33
Notice: Constant easypaymentPASS already defined in /home/justhardware/public_html/wp-content/plugins/easypay-mobile-money/easypay-mobile-money.php on line 35
Notice: Constant easypaymentWC_AFFILIATE_KEY already defined in /home/justhardware/public_html/wp-content/plugins/easypay-mobile-money/easypay-mobile-money.php on line 36
Notice: Constant easypaymentWC already defined in /home/justhardware/public_html/wp-content/plugins/easypay-mobile-money/easypay-mobile-money.php on line 31
Notice: Constant easypaymentUSER already defined in /home/justhardware/public_html/wp-content/plugins/easypay-mobile-money/easypay-mobile-money.php on line 33
Notice: Constant easypaymentPASS already defined in /home/justhardware/public_html/wp-content/plugins/easypay-mobile-money/easypay-mobile-money.php on line 35
Notice: Constant easypaymentWC_AFFILIATE_KEY already defined in /home/justhardware/public_html/wp-content/plugins/easypay-mobile-money/easypay-mobile-money.php on line 36
What should I do ?
This was fixed in latest iteration of plugin. You can also suppress php warnings and notices to remove those messages
Is the request non blocking or ??
How do i know the status of the payment.
There is an api mmstatus or paybillstatus for this