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

Due to abuse, we shall be retiring this API on 1st June 2021

 

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 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

 

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.
 

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.

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"
}
  • 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”}

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

{
"username": "your client id",
"password": "your secret",
"action":"validatemomo",
"phone":"phone number"
}
  • action – Leave this as-is is validatemomo.
  • Phone – Phone number including country code e.g for uganda 25677XXXXXXX.

Success Result

{"success":1,"data":{"realName":"NAME HERE","realNetworkName":"AIRTEL"}}

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

{
"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

72 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

      1. Tumusiime Ezra

        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

  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

        1. Easypay Moderator

          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

  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

  5. Paul

    Is it possible to integrate the api in an android application?

    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

        1. Easypay Moderator

          Use ragnarok server to work with xammp

        2. Easypay Moderator

          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

      2. Edgar

        Hello I am developing an application and want to embed your API. But I want you to explain what percentage of commission I get per transaction.? When my merchant users make transactions on the app. Is it possible. Because you take, I take and also the end user takes as well as the vendor say MTN, Airtel etc. When you say 3% of the transaction amount do you take all or it’s what we share. And if that’s what we share , what ratio do you apply.

        Again I want know, my developer wants to know the API s I am going to use, and he is developing a website, an app both Android and iOS. Is there a way I can get an API without a website and the urls? Because we want to have our templates modified and even to know how the API might affect the modifications.

        Thanks.
        You can give me a call or whatsp me 0756175497

  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

      Currently you cannot. To get your own you need to integrate with telcos directly

    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

  17. raphael mwiiru

    hello how can i embed easy pay on my website to accept donations?

    1. Easypay Moderator

      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

  18. Clerence

    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.

  19. Clerence

    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.

  21. Godwin Kangwanzi

    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……….”

  22. Lyazi Derrick

    is it possible to withdraw my profits from my account using VISA or Master cards say i have traveled

    1. Easypay Moderator

      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.

  23. Clerence

    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

    1. Praise Nangobi

      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

  24. Clerence

    In case of extra assistance with the API and IPN, which place in Uganda can i visit to find a Easy pay assistant.

    1. Praise Nangobi

      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.

    1. Easypay Moderator

      We have no specific extension or plugin but with the right knowledge, you can implement our barebones api in anything that is connected

  28. clerence

    hello i wanted to ask that when working with the api do we need to first create an html form.

  29. clerence

    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.

  30. clerence

    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.

  31. aggrey

    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?

    1. Easypay Moderator

      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

  32. Yatoure

    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.

  33. Nuwa

    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

  34. Mweru Bilton

    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 ?

    1. Easypay Moderator

      This was fixed in latest iteration of plugin. You can also suppress php warnings and notices to remove those messages

    1. Easypay Moderator

      There is an api mmstatus or paybillstatus for this

  36. Drupal

    Do you have a Drupal plugin or is on in the works? I am a Drupal developer and I need to use easypay on a Drupal website. I will most likely write it myself if one is not already available. I would be willing to make my code public if compensated.

  37. Kabazzi Fahad

    good evening , am not understand the meaning of the code below in particular “php://input”
    $post = file_get_contents(‘php://input’);

    please explain to me

  38. kabazzi fahad

    $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
    ?>

    am not understanding this code $post = file_get_contents(‘php://input’)
    i want to get all the truck all the transactions

  39. Hammad Rasheed

    mmdeposit gives TARGET_AUTHORIZATION_ERROR for MTN. Could you please help me?

  40. Drake

    How can i check if balance is sufficient to initiate payment ????

Leave A Comment?

Enter Captcha Here : *

Reload Image