Quick Start
eLipa Developers API introduction
This is the C2B API
The eLipa Integration is simple and seamless. There are two types of intergrations:-
| Integration | Process Flow(English) | API Calls(Geeklish) |
|---|---|---|
| 1.1 Web Based Integrations |
|
|
Change LogNEW
- Update on section 1.4.1 Mobile money transact call and responses - 2020 March 3
1.1.1 HOW and WHAT To POST/GET to the eLipa gateway testing
(for each field, there are some characters not accepted by eLipa. See Bottom of page)
Y = Yes N = No O = Optional| Parameter Name | Data Type(Data Length) | Description | Channel | ||
|---|---|---|---|---|---|
| Mobile | Credit Card | ||||
| live | numeric(1) | LIVE or DEMO mode (1 or 0). “1” By Default (live) | Y | Y | |
| mtn | numeric(1) | Display MTN Mobile Money Channel (on or off). “on” by Default (i.e. mtn=1) | O | O | |
| airtel | numeric(1) | Display Airtel Mobile Money Channel (on or off). “on” by Default (i.e. airtel=1) | O | O | |
| autopay | numeric(1) | Push Data (on or off). “off” by Default (i.e. autopay=0) Set this parameter to 1 if you want iPay to silently trigger the callback. The CONFIRM button on the checkout page will not be present for mobile money and mobile banking NOTE Valid Callback Parameter must be provided. when this parameter is set eLipa will send data to your server using GET request and the IPN should be run to verify this data. | O | O | |
| oid | alphanumeric (34) | Order ID | Y | Y | |
| inv | alphanumeric (15) | Invoice Number (Set to Order ID value above if NULL) | Y | Y | |
| ttl | numeric (15) | Total amount (DO NOT PASS any commas as a thousands separator). e.g. ttl=1234.00 and NOT ttl=1,234.00 | Y | Y | |
| tel | alphanumeric (15) | Customer Telephone number | Y | Y | |
| eml | alphanumeric (30) | Customer Email Address | Y | Y | |
| vid | alphanumeric (12) | Vendor ID assigned by eLipa. SET IN LOWER CASE | Y | Y | |
| curr | alphanumeric (3) | Currency Type (USD or UGX) * UGX By Default | Y | Y | |
| p1 | alphanumeric (15) | Required field but can be left empty. It is for allowing the sending & receiving your custom parameters if need be for your applications usecase. | Y | y | |
| p2 | alphanumeric (15) | Required field but can be left empty. It is for allowing the sending & receiving your custom parameters if need be for your applications usecase. | Y | y | |
| p3 | alphanumeric (15) | Required field but can be left empty. It is for allowing the sending & receiving your custom parameters if need be for your applications usecase. | Y | y | |
| p4 | alphanumeric (15) | Required field but can be left empty. It is for allowing the sending & receiving your custom parameters if need be for your applications usecase. | Y | y | |
| cbk | alphanumeric (100) | This parameter holds the value of the URL on your server to which eLipa
will send back payment processing data to.
Please note that the call back URL parameter is ONLY required if the cURL parameter (crl) is set to zero (0), meaning that you want a browser redirect back to your website.
| Y | Y | |
| lbk | alphanumeric (100) | In the event that the client cannot check out successfully, eLipa will return the customer to our gateway. This parameter holds the value of the URL on your server to which the customer will be able to voluntarily use to link back to your website. If there is no value provided, then by default, (if this link is clicked) the customer will be redirected back to the previous page on your website. | O | O | |
| cst | numeric (1) | The customer email notification flag of value 1 or 0. (Set to “1” By Default to allow customer to receive txn notifications from eLipa for online txns) | Y | Y | |
| crl | numeric (1) | Name of the cURL flag input field (1 character).
|
O | O | |
| hsh | alphanumeric (64) | The computed eLipa Hash Code | Y | Y | |
The following characters are NOT ALLOWED as part of your incoming parameters:
The variables p1, p2, p3 and p4 are used by you if you want to pass certain variables into the eLipa system and receive them back intact on your end for your own personal reasons. They are not processed in any way. The mc variable is used to notify you of the actual mobile money transferred by the user.
1.1.2 How to post your parameters to eLipa for processing
1.2 How to post your parameters to eLipa for processing
URL
https://payments.elipa.co.ug/v3/ug We need to generate the hash signature id that is to be sent to the eLipa system for authentication against the transaction values that are also to be received on the same URL call.
We are using the hash_hmac function in PHP to digitally sign the transaction data.
Depending on the programming language of your choice, please feel free to use it or the equivalent HMAC function in your programming language.
Here is a PHP example below: There are two important parameters that are required by this function.
- The secret and private key - $hashkey - this key is generated by you. Please also send it to us for registration in your eLipa account.
- The string to be hashed - $datastring - this string is composed of ALL the parameters you are passing to eLipa in the following CONCATENATED format. The order of the transaction variables is VERY IMPORTANT and MUST be followed. There are NO SPACES between the different values below.
<?php
$datastring = $live.$order_id.$invoice.$total.$phone.$email.$vid.$curr.$p1.$p2.$p3.$p4.$cbk.$cst.$crl;
/**********************************************************************************************************/
$hashkey = "yoursecuritykey"; //Supply to us during eLipa account registration;
$datastring; //This is a string generated from the data to be posted (see above)
$hashid = hash_hmac("sha1", $datastring, $hashkey); //Set hashing algorithm to SHA1;
/**********************************************************************************************************/
?>
Sample POST Formwith (PHP)
Sample POST Formwith (PHP)
<php?
<form method="post" action="https://payments.elipa.co.ug/v3/ug">
live:<input name="live" type="text" value="<?php echo $live;?>" >
oid:<input name="oid" type="text" value="<?php echo $order_id;?>" >
inv:<input name="inv" type="text" value="<?php echo $invoice;?>" >
ttl:<input name="ttl" type="text" value="<?php echo $total;?>" >
tel:<input name="tel" type="text" value="<?php echo $phone1;?>" >
eml:<input name="eml" type="text" value="<?php echo $email;?>" >
vid:<input name="vid" type="text" value="<?php echo $vid;?>" >
curr:<input name="curr" type="text" value="<?php echo $curr;?>" >
p1: <input name="p1" type="text" value="<?php echo $p1;?>" >
p2: <input name="p2" type="text" value="<?php echo $p2;?>" >
p3: <input name="p3" type="text" value="<?php echo $p3;?>" >
p4: <input name="p4" type="text" value="<?php echo $p4;?>" >
cbk: <input name="cbk" type="text" value="<?php echo $cbk;?>" >
cbk: <input name="lbk" type="text" value="<?php echo $lbk;?>" >
cst:<input name="cst" type="text" value="<?php echo $cst;?>" >
crl:<input name="crl" type="text" value="<?php echo $crl;?>" >
lbk:<input name="lbk" type="text" value="<?php echo $cbk;?>" >
<input name="hsh" type="text" value="<?php echo $hashid;?>" >
<button type="submit"> Lipa </button>
</form>
1.1.3 What if implementing HMAC hashing in my chosen scripting language is difficult?
If your programming language does not have an easy-to-use implementation of the HMAC function, as PHP does, then you can POST your Data string, Secret Key and Merchant Vendor ID to the following URL, using the cURL library or its equivalent:
URL
https://www.elipa.co.ug/hashid/
vendor = demo
data = 11111Demo [email protected]
key = yoursecuritykey
The HTTP Stream returned is the hashid that you should pick and use. If the HTTP Stream returns the string “invalid”, then one or more of your parameters is not correct. This hashid is then supplied as one of the parameters to be sent to the eLipa payment system for verification as shown on section 1.1.
Please URL-encode your Call Back URL AFTER you hash the data string.
This URL-encoded call back value is the one that you should post in the eLipa gateway URL parameter [cbk]
Please DO NOT hash the URL-encoded value of your Call Back URL.
The hmac algorithm used here is SHA1 it is not for use with the other hashing algorithms
If your Vendor ID ($vendor_ref) is not yet registered with eLipa, then you will get an error stating this and showing you how to go about how to remedy this.
1.1.4 Refund
The endpoint is:https://apis.elipa.co.ug/payments/v2/transaction/refundThe parameters needed for this are as follows:
| Parameter Name | Data Type(Data Length) | Description | Required |
|---|---|---|---|
| code | alphanumeric (64) | The transaction code to be refunded | Y |
| vid | alphanumeric(12) | The iPay Merchant vendor id | Y |
| hash | alphanumeric(64) | A digital signature hash of the data for verification. | Y |
| amount | float | this amount should be equal to or less that the transaction amount in order to do a partial refund ( this is only available for card transactions ) | O |
The hash is generated from a datastring which is a http string key value pair of the parameters: code, vid in alphabetical order it is a HMAC with the sha256 hashing algorithm. Sample PHP script of the same is show below:
<?php
//your SECRET KEY
$key = "SECretKey";
$datastring = "code=code&vid=vid";
/*********************************************************************************************************/
$generated_hash = hash_hmac('sha256',$datastring , $key);
/**********************************************************************************************************/
?>
Response
Expected Response on Successfull card transaction.
status 200 is success any other should be treated as a failure
{
"status": 200,
"c2bfunds": "1100.00",
"b2cfunds": "8164.00",
"amount": "50.00",
"code": "1539630706A",
"text": "Refund done",
"email_response": "Mail sent succesfully"
}
2.1 Merchant-defined HTTP Call back response / Return URL
To do this set the crl parameter in your eLipa gateway call to 0 (crl = 0)
We at eLipa would need you to provide the Call Back or Return URL. This is the URL/page to which eLipa will send the
parameters mentioned in Section 1.1. Refer to the “cbk” parameter on Section 1.1
These variables will be sent back to your website via your return URL, using the GET method.
An example of your website URL would be www.mystore.co.ke.
Thus, you may have set your Call Back or Return URL as www.mystore.co.ke/elipa.php.
Therefore the eLipa return URL from a transaction then would look like this:www.mystore.co.ke/returnpage.php?
id=23&txncd=we243ty234&status=aei7p7yrx4ae34&ivm=23234&qwh=34565&afd=23545&poi=345654&uyt=4567
8&ifd=123456&agt=324566&mc=350&p1=customevalue1&p2= customevalue1 &p3= customevalue1 &p4= custome
value1 &msisdn_id=firstname+lastname&msisdn_idnum=254710000000
We would recommend that you set up this call back URL in such a way that once eLipa calls back to your website, this Call back URL page then redirects to another page, as a security measure, once it has finished processing based on the return URL parameters mentioned in Section 1.1 of this manual.
2.2 Payment Verification
You can verify the payment status of each transaction on callback. This code (or similar) Demonstrates how.
<?php
$val = ""; //assigned eLipa Vendor ID... hard code it here.
/*
these values below are picked from the incoming URL and assigned to variables that we
will use in our security check URL
*/
$val1 = $_GET["id"];
$val2 = $_GET["ivm"];
$val3 = $_GET["qwh"];
$val4 = $_GET["afd"];
$val5 = $_GET["poi"];
$val6 = $_GET["uyt"];
$val7 = $_GET["ifd"];
$ipnurl = "https://payments.elipa.co.ug/v3/ug/ipn?vendor=".$val1."&ivm=".
$val2."&qwh=".$val3."&afd=".$val4."&poi=".$val5."&uyt=".$val6."&ifd=".$val7;
$fp = fopen($ipnurl, "rb");
$status = stream_get_contents($fp, -1, -1);
fclose($fp);
//the value of the parameter “vendor”, in the url being opened above, is your eLipa assigned
Vendor ID.
//this is the correct eLipa status code corresponding to this transaction.
//Use it to validate your incoming transaction(not the one supplied in the incoming url)
//continue your shopping cart update routine code here below....
//then redirect to to the customer notification page here...
?>
This IPN solution can be implemented in other web application development languages as well
The variables described above are returned by eLipa on callback to the Callback url(cbk) supplied,
they are described in Section 2.3 The variables that eLipa returns
2.3 Search/Query for a Transaction
Incase you want to search and verify that indeed a transaction has been paid for the following endpoint can be used to search for the transaction on IPay
https://apis.elipa.co.ug/payments/v2/transaction/search
The parameters to post are:
| vid | alphanumeric (12) | The iPay Merchant vendor id |
| hash | alphanumeric (64) | Generated signature of the data based on a secret key shared between iPay and you(our MErchant) |
| oid | alphanumeric (64) | Order Id |
The hash is generated by the concatenation of the oid and the vid(it is used to sign data in such a way that we can verifiy you are indeed one of the authorized partners)
<?php
$key = 'SECretKey';
$datastring = $oid.$vid;
$generated_hash = hash_hmac('sha256',$datastring , $key); ?>
The following parameters are returned as a JSON on successful POST.
{ "header_status": 200,
"status": 1,
"text": "payment record found",
"data": {
"vid": "demo",
"session_id": "852a63b08ac98b1750498rfd7c547c8d",
"oid": "34b674",
"transaction_amount": "200.00",
"transaction_code": "TXNCODE",
"telephone": "2547XXXXXXXX",
"firstname": "JOHN",
"lastname": "DOE",
"paid_at": "2016-05-14 16:13:50",
"payment_mode": "MPESA"
},
"hash": "d29ac43a8b89673cc85ce206351832d3a0c4a462dd0fde56c17445e94f6ad958"
}
The meanings of these parameters have been explained in Section 2.3
On unsuccessful POST possibly due to wrong session_id post an error in the manner below is returned
{
"header_status": 404,
"status": 0,
"text": "no record found"
}
To validate the hash string
<?php
$sign_datastring = $oid.$vid.$transaction_code.$firstname.$lastname.$paid_at.$payment_mode.$sid;
//The above string is a concatenation of the order, transaction_code, telephone, frstname, lastname,paid_at, payment_mode and SID
//This datastring is signed with the same algorithm and the same security key used in the create api ie
hash_hmac("sha256", $sign_datastring, "key");?>
2.4 The variables that eLipa returns on Callback :
(a) The status variable has the following possible values:-
fe2707etr5s4wq = Failed transaction. Not all parameters fulfilled. A notification of this transaction sent to the merchant.
aei7p7yrx4ae34 = Success: The transaction is valid. Therefore you can update this transaction.
bdi6p2yy76etrs = Pending: Incoming Mobile Money Transaction Not found. Please try again in 5 minutes.
cr5i3pgy9867e1 = Used: This code has been used already. A notification of this transaction sent to the merchant.
dtfi4p7yty45wq = Less: The amount that you have sent via mobile money is LESS than what was required to validate
this transaction.eq3i7p5yt7645e = More: The amount that you have sent via mobile money is MORE than what was required to validate this transaction. (Up to the merchant to decide what to do with this transaction; whether to pass it or not)
(b) id for you to authenticate the order id again and map it to the order transaction again.
(c) ivm the invoice number is returned as an MD5 hash for you to process if you need to.
(d) qwh, afd, poi, uyt, ifd, agt special, unique browser-specific identifier variables returned from the eLipa system.
(e) mc this is the amount of money that was sent via the mobile money transfer by the user. This comes as an integer and without the thousands (,) separator. You can use to authenticate against the amount that the user has checked out.
(f) p1, p2, p3, p4: these are four CUSTOM parameters that allow you to simply pass your own parameters into our system and catch them once again on your end. They are (alphanumeric) in nature; thus you can pass text, numbers or a combination of these.
(g) txncd: This refers to the transaction code that the user entered (in the case of mobile money), or that was system generated (in the case of Kenswitch and VISA/Mastercard transactions).
(h) msisdn_id: This refers to the names of the payer as registered by their mobile money / banking system.
(i) msisdn_idnum: This refers to the telephone number of the payer as registered by their mobile money / banking system. They are returned for your convenience.
(i) msisdn_custnum: This refers to the client telephone number you posted into our system together with the order details in page 3 above. They are returned for your convenience. ** Please note that the most important variables are (a) – (c), (e) and (g)
2.5 How to test that your implementation is working correctly
When the eLipa interface loads correctly, the following dummy codes below can be used on the different channels: The dummy data below will work ONLY IF you have set the live parameter to “0”.see Section 1.1.1.
Once your testing is complete, then set the the live parameter to “1” and you are ready to go. see Section 1.1.1
Mobile Money Channel
| MTN |
|---|
| There are no Test Values for this just ensure that the Live parameter is "0" for Demo as indicated above |
2.6 The eLipa Interface
Once successfully intergrated to the eLipa Gateway you should see an interface like so :
The Above example represents when a user has clicked on the MTN tab
3.1 How to view your eLipa transactions:
We expect you to develop a website for your merchant with a shopping cart that allows the merchant to quickly get real time reports on sales and orders that have occurred on their website once eLipa communicates back to your website.
However, we have also developed an easy-to-use administrative interface that allows the merchant to quickly track their own transactions for purposes of reconciliation.
This interface is available from the following URL: https://dashboard.elipa.co.ug/ You can do the following:
- View successful and unsuccessful transactions
- Create additional system users
- View unused transactions, where the user sent money but did not use it
- Initiate refunds for transactions that you feel require this action.
- View refunded transactions
- Export transaction activity statements or reports in Excel and PDF formats
- Generate trend analysis graphs
- Send money from your eLipa account to target recipients (via MTN or Airtel Money)
- Generate e-Invoices for sending via email to your clients requesting them to pay you
- Manage the e-invoices that you generate above