API Page

 

Payment Processing Integration Manual
Version 2.0.5
Saachi Plaza, Office Block B, Suite B6, Argwings Kodhek Road
P.O Box 20790-00202 Nairobi, Kenya
Tel: 0713-129 623, 0732-797 401
Website: http://www.ipayafrica.com/
.:: iPay – Payments made Easy ::.
version 2.0.5
1
Table of Contents
0. Version Control
3
1. Introduction
4
1.1 – Ready iPay 2.0.x modules for popular Shopping Carts
1.2 – HOW and WHAT to post to the iPay gateway
1.3 – The variables that iPay returns via a Return URL or JSON or HTTP stream
1.4 – Authenticating orders on iPay via a Call Back / Return URL
1.5 – Your Call Back / Return URL
1.6 – Additional Call Back / Return URL Security
2. Example iPay Transaction Processing URL Call
8
2.1 How to post your parameters to iPay for processing
2.2 What if implementing HMAC hashing in my chosen scripting language is difficult?
2.3 How to test that your implementation is working correctly
3. iPay Merchant Account Administration Interface
11
3.1 – How to view your iPay transactions
.:: iPay – Payments made Easy ::.
version 2.0.5
2
Version Index
Date
Modification Description
1.1.8
2010 – 2013
2.0.1
13-05-2014
Complete rewrite of iPay API from version 1.1.8
Added support for mobile banking
2.0.5
25-02-2015
Added support for JSON
Added support for iPay Wallet
Added extra call back parameter [msisdn_custnum]
Added extra call back parameter [msisdn_idnum]
Updated the iPay Dashboard URL to
Added HMAC data signing function call to ease signing of data
IPN URL updated from https://ipay.intrepid.co.ke/ipn/ to
https://elipa.cd/ipn/ (refer to page 7)
.:: iPay – Payments made Easy ::.
version 2.0.5
3
1. Introduction
1.1 Ready iPay 2.0.x modules for popular Shopping Carts
Log into our website, download the relevant module for your shopping cart. Click Here to Login
1.2 HOW and WHAT To POST to the iPay gateway
**
(for each field, there are some characters not accepted by iPay. See page 4) Y = Yes
N = No O = Optional
Parameter
Data Type
Description
Channel
Name
(Data Length)
Mobile
Kenswitch
Credit Card
live
numeric (1)
LIVE or DEMO mode (1 or 0). “1” By Default (live)
Y
Y
Y
mm
numeric (1)
Display the Mobile Money Channel (on or off).
Y
Y
Y
“on” by Default (i.e. mm=1)
mb
numeric (1)
Display the Mobile Banking Channel (on or off).
Y
Y
Y
“on” by Default (i.e. mb=1)
dc
numeric (1)
Display the Debit Card Channel (on or off). “on” by
Y
Y
Y
Default (i.e. dc=1)
cc
numeric (1)
Display the Credit Card Channel (on or off). “on”
Y
Y
Y
by Default (i.e. cc=1)
mer
alphanumeric
Merchant Name
Y
Y
Y
oid
alphanumeric (12)
Order ID
Y
Y
Y
inv
alphanumeric (15)
Invoice Number (Set to Order ID value above if NULL)
Y
Y
Y
ttl
numeric (15)
Total amount (DO NOT PASS any commas as a
thousands separator). e.g. ttl=1234.00 and NOT
Y
Y
Y
ttl=1,234.00
tel
alphanumeric (15)
Customer Telephone number
Y
Y
Y
eml
alphanumeric (30)
Customer Email Address
Y
Y
Y
vid
alphanumeric (12)
Vendor ID assigned by iPay. SET IN LOWER CASE
Y
Y
Y
cur
alphanumeric (3)
Currency Type (USD or KES) * KES By Default
N
N
Y
p1
alphanumeric (15)
Optional field. allows sending & receiving your custom
O
O
O
parameters
p2
alphanumeric (15)
Optional field. allows sending & receiving your custom
O
O
O
parameters
p3
alphanumeric (15)
Optional field. allows sending & receiving your custom
O
O
O
parameters
p4
alphanumeric (15)
Optional field. allows sending & receiving your custom
O
O
O
parameters
cbk
alphanumeric (100)
Holds the value of the URL on your server that iPay
Y
Y
Y
will communicate / call back to.
cst
numeric (1)
The customer email notification flag of value 1 or 0.
(Set to “1” By Default to allow customer to receive
Y
Y
Y
txn notifications from iPay for online txns)
crl
numeric (1)
Name of the cURL flag input field (1 character). The
value is 2, 1 or 0 to specify that you want to pick call
O
O
O
back values as a data stream. (Set to “0” By Default)
hsh
alphanumeric (64)
The computed iPay Hash Code
Y
Y
Y
.:: iPay – Payments made Easy ::.
version 2.0.5
4
The following characters are NOT ALLOWED as part of your incoming parameters:
;
:
~
`
!
%
^
*
>
<
The variables you need to pick via the call back URL and returned through a GET call are:
status, id and ivm, and special browser-dependent variables qwh, afd, poi, uyt, ifd, agt. These variables are very
important especially when you need to re-validate the transaction as shown on page 6
The extra variables p1, p2, p3 and p4 are used by you if you want to pass certain variables into the iPay 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.3 The variables that iPay returns via a Return URL or JSON or HTTP stream :
(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 iPay 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)
.:: iPay – Payments made Easy ::.
version 2.0.5
5
1.4 Authenticating orders on iPay via a Call Back / Return URL
To do this set the crl parameter in your iPay gateway call to 0 (crl = 0)
** We at iPay would need you to provide the Call Back or Return URL. This is the URL/page to which iPay will send the
parameters mentioned in page 4. Refer to the “cbk” parameter on page 4 and page 9
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/ipay.php .
Therefore the iPay return URL from a transaction then would look like this:
We would recommend that you set up this call back URL in such a way that once iPay 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 page 4 of this manual.
* Please also see Section 1.7 (Additional Call Back / Return URL Security) below for an even more effective and
recommended payment notification security check that you should implement.
1.5 Authenticating orders on iPay using a HTTP stream on Call Back (suitable for mobile apps)
To do this set the crl parameter in your iPay gateway call to 1 (crl = 1)
The following parameters are returned as a HTTP stream of characters that you need catch and extract.
txncd;qwh;afd;poi;uyt;ifd;agt;id;status;ivm;mc;p1;p2;p3;p4;msisdn_id;msisdn_idnum;msisdn_custnum
The meanings of these parameter have been explained on page 5.
1.6 Authenticating orders on iPay using JSON on Call Back (suitable for mobile apps)
To do this set the crl parameter in your iPay gateway call to 2 (crl = 2)
The following parameters are returned as a JSON stream of characters that you need catch and extract.
{“txncd”:”TEST”,”qwh”:”123″,”afd”:”456″,”poi”:”789″,”uyt”:”098″,”ifd”:”765″,”agt”:””,”id”:”1″,status:”aei7p7yr
x4ae34″,ivm:”1″,mc:”200.00″,p1:”PARAM1″,p2:””,p3:””,p4:””,msisdn_id:”jOHN
DOE”,msisdn_idnum:”254700123456″,msisdn_custnum:”254700123456”}
The meanings of these parameter have been explained on page 5.
===================================================================
Please still implement Section 1.7 (Additional Call Back / Return URL Security) for extra security.
Also please note that if you are using the cURL library, then you can ignore Section 1.4 above.
** NOTE **: It is advisable to make sure that you can authenticate the incoming server address using your
scripting language as an added security measure.
===================================================================
.:: iPay – Payments made Easy ::.
version 2.0.5
6
1.7 Additional Call Back / Return URL Security
We have added a new security feature that would check ALL incoming transactions BEFORE they are run by your
shopping cart software. Please add this code (or similar) to your Call Back URL page.
<?php
$val = “”;
//assigned iPay 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‘];
$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 iPay-
assigned Vendor ID.
//this is the correct iPay status code corresponding to this transaction.
//Use it to validate your incoming transaction; not the one supplied in the incoming url
$status;
//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, such as:-
ASP
ASP.NET
JSP
Perl
Python
Ruby on Rails
Cold Fusion
.:: iPay – Payments made Easy ::.
version 2.0.5
7
2. Example iPay Transaction Processing URL Call
2.1 How to post your parameters to iPay for processing
Generating the unique Hash Signature ID
We need to generate the hash signature id that is to be sent to the iPay 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. ** If you are having trouble implementing this function, see Section 2.2 below. **
Here is a PHP example below:
There are two important parameters that are required by this function.
1. The secret and private key – $hashkey – this key is generated by you. Please also send it to us for registration
in your iPay account.
2. The string to be hashed – $datastring – this string is composed of ALL the parameters you are passing to iPay
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.
$datastring = $live.$mm.$mb.$dc.$cc.$mer.$oid.$inv.$ttl.$tel.$eml.$vid.$cur.$p1.$p2.$p3.$p4.$cbk.$cst.$crl;
/*************************************************************************************************************************/
$hashkey = “yoursecuritykey”; //Supply to us during iPay 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
/*************************************************************************************************************************/
2.2 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:
POST parameter names and data examples
Please note that the data string MUST be in the same order as shown in Section 2.1 above.
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 iPay payment system for verification as shown
on page 9.
.:: iPay – Payments made Easy ::.
version 2.0.5
8
** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** **
** 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 iPay gateway URL
parameter [cbk]
** Please DO NOT hash the URL-encoded value of your Call Back URL.
** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** **
The code below, when embedded on a scripting page, will call the iPay 2.0.x Payment interface onto your
website.
If your Vendor ID ($vendor_ref) is not yet registered with iPay, then you will get an error stating this and
showing you how to go about how to remedy this.
You can embed the <IFRAME> in a <DIV> tag to style the <IFRAME> according to your design needs.
<div class=”” id=””>
live=$demo&mer=$merchant&oid=$order_id&inv=$invoice&ttl=$total&tel=$phone1&eml=$email&vid=$vendor_
ref&p1=$p1&p2=$p2&p3=$p3&p4=$p4&crl=0&cbk=$callbk&cst=$custemail&cur=$curr&hsh=$hashid”
height=”” /></frame>
</div>
A sample URL is shown below with dummy values and the transaction attempt set to DEMO mode (live=0):
<div class=”” id=””>
Ltd&oid=123&inv=123&ttl=500&tel=0722123456&[email protected]&vid=test&p1=&p2=&p3=&p4=&crl=0&cbk
</div>
A sample URL is shown below with dummy values and the transaction attempt set to LIVE mode (live=1):
<div class=”” id=””>
Ltd&oid=123&inv=123&ttl=500&tel=0722123456&[email protected]&vid=test&p1=&p2=&p3=&p4=&crl=0&cbk
</div>
.:: iPay – Payments made Easy ::.
version 2.0.5
9
2.3 How to test that your implementation is working correctly
When the iPay 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 pages 4 and 9.
Once your testing is complete, then set the the live parameter to “1” and you are ready to go. (See pages 4 and 9)
Mobile money / Mobile Banking Channel
Code Value
iPay API Status
Cash Value
AB22CD333
successful
determined by you
AB44CD555
user underpaid
determined by you
AB66CD777
user overpaid
determined by you
AB88CD999
used transaction
determined by you
AB11CD222
failed/pending
determined by you
Credit Card Channel
Credit Card Number
iPay API Status
Card Details, Cash Value and Expiry Date
4444444444444444
successful
determined by you
3333333333333333
failed
determined by you
.:: iPay – Payments made Easy ::.
version 2.0.5
10
3. iPay Merchant Administrative Interface
3.1 How to view your iPay 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 iPay 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.ipayafrica.com/
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 iPay account to target recipients (via M-PESA 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
.:: iPay – Payments made Easy ::.
version 2.0.5
11