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

Open Mobile Money API for MTN and Airtel 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 or Airtel 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. 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.

Enable Mobile Money API for Airtel and MTN Uganda

 

Enable Mobile Money API for Airtel and MTN Uganda
Enable Mobile Money API for Airtel and MTN 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
Create Mobile Money API account

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 PINS. Once successful we shall call back your website with valid postfields about the transaction (IPN url).

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.

Min (UGX) Max (UGX) charge
500 5000 500
5001 30000 880
30001 60000 1210
60001 125000 1925
125001 250000 3575
250001 500000 5775
500001 1000000 10450
1000001 2000000 19800
2000001 4000000 35200

Mobile Money Payout Charges

All Easypay payout to mobile numbers incur a UGX 1,000 charge.

 

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 Mobile Money & Airtel supported.

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

Payload
{
"username": "your client Id",
"password": "your secret",
"action":"mmdeposit",
"amount":500,
"phone":"mobile money phone number",
"reference":"1",
"reason":"Payment for book"
}
  • Amount – The amount.
  • 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":"Your balance will be updated shortly after you approve the PAYLEO\/TrueAfrican screen. You may have to exit app to see the PAYLEO screen. Withdraw Response: Request received for processing."
}

Failure Result

{“success”:0,”errormsg”:”Invalid Amount.”}

mmpayout

This method is used to send mobile money from the easypay account to the mobile money phone number. MTN & Airtel Money supported.

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

Payload

{
"username": "your client id",
"password": "your secret",
"action":"mmpayout",
"amount":1000,
"phone":"phone number"
}

  • Amount – The amount in your default currency

Success Result

{
"success":1,
"data":"Mobile Money Payout. Phone: 2567xxxxxxxx Amount: UGX 35,090 Service Charge: UGX 1,000 TransferCode:144889",
"txid":529377,
"trueafricanId":"11711"
}

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

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

Mobile Money Incoming Sample in php

// PHP CODE

<?php
//Testing Mobile money incoming
$url = 'https://www.easypay.co.ug/api/';
$payload = array( 'username' => 'clientId',
'password' => 'secret',
'action' => 'mmdeposit',
'amount' => 500,
'phone'=>'075XXXXXXX',
'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 Outgoing Sample in php

// PHP CODE

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

Related Articles

7 Comments

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

Leave A Comment?

Enter Captcha Here : *

Reload Image