Payment Processing Integration Manual Version 1.1.

Saachi Plaza, Office Block B, Suite B6, Argwings Kodhek Road P.O Box 20790-00202 Nairobi, Kenya Tel: 0713-129 623, 0715-659 199 Website: http://www.ipayafrica.com/ E-mail: [email protected]

.:: iPay Payments Made Easy ::.

version 1.1.0

Table of Contents
1. Introduction ................................................................... 3

1.1 - Ready Virtuemart Modules 1.2 - Ready osCommerce Modules 1.3 - Ready WordPress Modules 1.4 - Custom Module Creation 1.5 - Custom POST variables required from your website 1.6 - The variables that iPay will return to your site via your Return URL 1.7 - Your Call Back / Return URL 1.8 - Additional Call Back / Return URL Security 1.9 - Merchant Account Setup: Administrative Requirements

2. Example iPay Transaction Forms

2.1 - M-PESA Transaction form 2.2 - Airtel Money Transaction form 2.3 - yuCash Transaction form

.................................................. 7

2.4 - Kenswitch Debit Card Transaction form

3. iPay Merchant Administrative Interface

3.1 How to view your transactions How to view your incomplete transactions 3.2 Handling Refunds

................................ 11

4. Sample artwork to brand your iPay Transaction pages

............. 12

.:: iPay Payments Made Easy ::.

version 1.1.0

1. Introduction 1.1 Ready Virtuemart Modules We have ready Virtuemart Shopping Cart Modules (HTTP://www.virtuemart.net/) should you be using this shopping cart. You can download them by clicking here 1.2 Ready osCommerce Modules We have ready osCommerce Shopping Cart Modules (HTTP://www.oscommerce.com/) should you be using this shopping cart. You can download them by clicking here 1.3 Ready Word Press Modules We have ready Word Press Shopping Cart Modules (HTTP://www.wordpress.org/) should you be using this shopping cart. You can download them by clicking here 1.4 Custom Module Creation In the event that you don't need these prepared modules, we would need you to POST/GET the following parameters to our system: 1.5 Custom POST variables required from your website (examples shown on pages 7 - 10) For the M-PESA code validation input form 1. order_id (alphanumeric) - hidden field (12 characters) 2. email (alphanumeric) - hidden field (30 characters) 3. phone1 (alphanumeric) - hidden field (15 characters) 4. invoice (alphanumeric) - hidden field (15 characters) 5. vendor_ref (alphanumeric) - The unique vendor reference number assigned to you by iPay (5 characters) 6. total (numeric) - this is the total cash amount that needs to be paid (7 characters) 7. p1 (alphanumeric) - this is an optional field to allow you to send/receive custom parameters (10 chars) 8. p2 (alphanumeric) - this is an optional field to allow you to send/receive custom parameters (10 chars) 9. p3 (alphanumeric) - this is an optional field to allow you to send/receive custom parameters (10 chars) 10. p4 (alphanumeric) - this is an optional field to allow you to send/receive custom parameters (10 chars) 11. mpesa (alphanumeric) - name of the M-PESA code input field (10 characters) For the Airtel Money code validation input form * The variables numbered 1 to 10 for M-PESA above, also apply. 11. zap (alphanumeric) - name of the AIRTEL MONEY code input field (15 characters) For the yuCash code validation input form * The variables numbered 1 to 10 for M-PESA above, also apply. 11. yu (alphanumeric) - name of the yuCash code input field (15 characters) These are all posted to https://ipay.intrepid.co.ke/incoming/ ** (please note that the LAST trailing slash (/) in the above URL is IMPORTANT) ** For the Kenswitch option form (see the example on page 10) * The variables numbered 1 to 10 for M-PESA above, also apply. These are posted to https://ipay.intrepid.co.ke/ksw/ ** (please note that the LAST trailing slash (/) in the above URL is IMPORTANT) **
.:: iPay Payments Made Easy ::. version 1.1.0 3

** For each e-commerce merchant site you configure, we expect you to provide the call back URL where the iPay system will return execution to your site for your further order processing. ** ** This URL will then catch the following variables and their values, which are to be sent back to your website from the iPay verification system. (See page 5 of this document). 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 5. 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.6 The variables that iPay will return to your site via your Return URL: (a) The status variable has the following possible values:fe2707etr5s4wq = Failed transaction. Not all parameters have been fulfilled. A notification of this transaction has been sent to the website owner. 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: The code you are attempting to pass has been used already. A notification of this transaction has been sent to the website owner. 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 as well for you to process if you need to. (d) qwh, afd, poi, uyt, ifd, agt special 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. This 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. ** Please note that the most important variables are (a) - (c) and (e)
.:: iPay Payments Made Easy ::. version 1.1.0 4

** NOTE **: It would be advisable to make sure that you can authenticate the incoming server address using your scripting language as an added security measure. Once your clients are signed on, we can assist you with this aspect should the need arise. If you are using the website referrer to authenticate the incoming iPay transaction verification then, there is a bug we have noticed with IE 6 8 and are offering a workaround here. IE does not send the referrer at all. But on request we can give you a workaround for this challenge. 1.7 Your Call Back / Return URL We at iPay would need you to kindly provide us with your Call Back or Return URL. This is the URL/page to which the iPay system will send the parameters mentioned in page 4. 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 iPay return URL from a transaction then would look like this: www.mystore.co.ke/ipay.php? id=23&status=aei7p7yrx4ae34&ivm=23234&qwh=34565&afd=23545&poi=345654&uyt=45678&ifd=123456& agt=324566&mc=350&p1=&p2=&p3=&p4= 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.

1.8 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 $fp = fopen(https://ipay.intrepid.co.ke/ipn/? vendor=[val]&id=[val1]&ivm=[val2]&qwh=[val3]&afd=[val4]&poi=[val5]&uyt=[val6]&ifd=[val7], 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.... ?>

.:: iPay Payments Made Easy ::.

version 1.1.0

1.9 Merchant Account Setup: Administrative Requirements 1. We would need to sign a contractual agreement with your merchant(s). We would need the following documents to complete the contract:

Business Entity Name Business Registration Number Physical Address Postal Address Telephone and Email Details of at least 2 Director(s) Physical Address(es) Postal Address Telephone and Email A copy of business registration certificate A copy of the National ID / Passport of the director(s) / business owner(s)

2. iPay account set up is FREE of charge.

3. The iPay transaction commission rate is charged as follows: (a) For transactions through M-PESA, Airtel Money, yuCash: KSh Value Range Per Transaction
Less than or Equal to 4,000 4,001 20,000 Greater than 20,000

iPay Commission Rate

3.50% 3.25% 3.00%

(b) For transactions through Kenswitch: KSh Value Range Per Transaction
All transactions through iPay's Kenswitch Gateway

iPay Commission Rate

3.80%

4. For a more detailed explanation, please download the sample iPay contract document: click here to download the sample contract

.:: iPay Payments Made Easy ::.

version 1.1.0

2. Example iPay Transaction Processing Forms

2.1 M-PESA Transaction Form: <form action="https://ipay.intrepid.co.ke/incoming/" method="POST"> <input type="hidden" name="order_id" value="<?php echo $order_id; ?>" /> <input type="hidden" name="invoice" value="<?php echo $invoice; ?>" /> <input type="hidden" name="total" value="<?php echo $total; ?>" /> <input type="hidden" name="phone1" value="<?php echo $phone1; ?>" /> <input type="hidden" name="phone2" value="<?php echo $phone2; ?>" /> <input type="hidden" name="email" value="<?php echo $email; ?>" /> <input type="hidden" name="vendor_ref" value="<?php echo $vendor_ref; ?>" /> <br /><br /> Go to the M-PESA Menu on your phone. <br /><br /> Select <b>Pay Bill</b> Option. <br /><br /> Enter the following business number: <b>510800</b>. <br /><br /> Enter <?php echo $vendor_ref;?> as the Account Number. <br /><br /> Enter the total amount (KSh. <?php echo $total;?>). <br /><br /> Enter your PIN and then send the money. <br /><br /> You will receive a transaction confirmation SMS from M-PESA. <br /><br /> Enter the returned M-PESA Transaction ID <b>only</b> here below: <br /><br /> <input type="text" name="mpesa" value="" /> <br /><br /> <input type="submit" value="pay merchant" />&nbsp;&nbsp;|&nbsp;&nbsp;<input type="reset" value="reset" /> <br /><br /> transaction processing powered by <a href='HTTP://iwww.payafrica.com/' target='_blank' title='Payments made Easy'><img src="<?php echo $ipay_payment_image;?>" border="1" height="24" width="55"></a> <br /><br /> </form>

.:: iPay Payments Made Easy ::.

version 1.1.0

2.2 Airtel Money Transaction Form: <form action="https://ipay.intrepid.co.ke/incoming/" method="POST"> <input type="hidden" name="order_id" value="<?php echo $order_id; ?>" /> <input type="hidden" name="invoice" value="<?php echo $invoice; ?>" /> <input type="hidden" name="total" value="<?php echo $total; ?>" /> <input type="hidden" name="phone1" value="<?php echo $phone1; ?>" /> <input type="hidden" name="phone2" value="<?php echo $phone2; ?>" /> <input type="hidden" name="email" value="<?php echo $email; ?>" /> <input type="hidden" name="vendor_ref" value="<?php echo $vendor_ref; ?>" /> <br /><br /> Go to the Airtel Money Menu on your phone. <br /><br /> Select <b>To Make Payments</b>. <br /><br /> Select <b>Pay Bill</b> Option. <br /><br /> Select <b>Others</b>. <br /><br /> Enter the Business name <b>IPAY</b>. <br /><br /> Enter the total amount (KSh. <?php echo $total;?>) <br /><br /> Enter your PIN. <br /><br /> Enter <?php echo $vendor_ref;?> as the Reference and then send the money. <br /><br /> You will receive a transaction confirmation SMS from Airtel Money. <br /><br /> Enter the returned Airtel Money Transaction ID <b>only</b> here below: <br /><br /> <input type="text" name="zap" value="" /> <br /><br /> <input type="submit" value="pay merchant" />&nbsp;&nbsp;|&nbsp;&nbsp;<input type="reset" value="reset" /> <br /><br /> transaction processing powered by <a href='HTTP://iwww.payafrica.com/' target='_blank' title='Payments made Easy'><img src="<?php echo $ipay_payment_image;?>" border="1" height="24" width="55"></a> <br /><br /> </form>

.:: iPay Payments Made Easy ::.

version 1.1.0

2.3 yuCash Transaction Form: <form action="https://ipay.intrepid.co.ke/incoming/" method="POST"> <input type="hidden" name="order_id" value="<?php echo $order_id; ?>" /> <input type="hidden" name="invoice" value="<?php echo $invoice; ?>" /> <input type="hidden" name="total" value="<?php echo $total; ?>" /> <input type="hidden" name="phone1" value="<?php echo $phone1; ?>" /> <input type="hidden" name="phone2" value="<?php echo $phone2; ?>" /> <input type="hidden" name="email" value="<?php echo $email; ?>" /> <input type="hidden" name="vendor_ref" value="<?php echo $vendor_ref; ?>" /> <br /><br /> Go to the yuCash Menu on your phone. <br /><br /> Select <b>Send Money</b> Option. <br /><br /> Enter <b>102020</b> as the business number . <br /><br /> Enter the total amount (KSh. <?php echo $total;?>) <br /><br /> Enter <?php echo $vendor_ref;?> as the Message . <br /><br /> Enter your PIN and then send the money. <br /><br /> You will receive a transaction confirmation SMS from yuCash. <br /><br /> Enter the returned yuCash Transaction ID <b>only</b> here below: <br /><br /> <input type="text" name="yu" value="" /> <br /><br /> <input type="submit" value="pay merchant" />&nbsp;&nbsp;|&nbsp;&nbsp;<input type="reset" value="reset" /> <br /><br /> transaction processing powered by <a href='http://iwww.payafrica.com/' target='_blank' title='Payments made Easy'><img src="<?php echo $ipay_payment_image;?>" border="1" height="24" width="55"></a> <br /><br /> </form>

.:: iPay Payments Made Easy ::.

version 1.1.0

2.4 Kenswitch Payment Gateway Transaction Button: <form action="https://ipay.intrepid.co.ke/ksw/" method="POST"> <input type="hidden" name="merchant" value="Merchant Name Here" /> <input type="hidden" name="order_id" value="<?php echo $order_id; ?>" /> <input type="hidden" name="invoice" value="<?php echo $invoice; ?>" /> <input type="hidden" name="total" value="<?php echo $total; ?>" /> <input type="hidden" name="phone1" value="<?php echo $phone1; ?>" /> <input type="hidden" name="phone2" value="<?php echo $phone2; ?>" /> <input type="hidden" name="email" value="<?php echo $email; ?>" /> <input type="hidden" name="vendor_ref" value="<?php echo $vendor_ref; ?>" /> <br /><br /> Dear <?php echo $customer_name; ?>, you will now be directed to the secure Kenswitch gateway to complete your payment using your Kenswitch Debit Card or via Kenswitch Mobile. <br /><br /> Your Order ID for this purchase is: <?php echo $order_id; ?>. <br /><br /> The transaction amount is KSh. <?php echo $total; ?>. <br /><br /> Please click on the pay merchant button below to complete your payment. <br /> Upon completion of payment, you will be automatically redirected back to this website. <br /><br /> <center><input type="submit" value="pay merchant" /></center> <br /><br /> transaction processing powered by <a href='http://iwww.payafrica.com/' target='_blank' title='Payments made Easy'><img src="<?php echo $ipay_payment_image;?>" border="1" height="24" width="55"></a> <br /><br /> </form>

.:: iPay Payments Made Easy ::.

version 1.1.0

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 off our website for purposes of reconciliation. This interface is available from the following URL: https://www.ipayafrica.com/merchant/ You can also view screen shots of the interface from the following URL: You can do the following:

View successful and unsuccessful transactions View incomplete transactions, where the user sent money but did not use it View Refunded transactions Initiate refunds for transactions that you feel require this service. Generate your own statements in Excel and PDF formats

Screen shots of this administration system are available at the following URL: http://ipaydemo.intrepid.co.ke/download/admin/iPay_Admin_Screenshots.pdf 3.2 Handling Refunds: If you have multiple refunds to carry out, you can push them through our refund gateway. The parameters we would need are as follows: Parameter Name txn_code order_id tel_num merchant_id Parameter Value The Transaction Code. The order id it was attached to. (optional) Telephone number the transaction originated from The iPay assigned vendor_ref number assigned on page 4

You can use the GET or POST method and send these parameters to the following gateway. https://ipay.intrepid.co.ke/refunds/ For each request, an email will be sent to your merchant's email address, registered on our system, for them to finalise the bulk refund request.
.:: iPay Payments Made Easy ::. version 1.1.0 11

4. Sample artwork to brand your iPay Transaction pages:

You can obtain the M-PESA, Airtel Money, yuCash, Kenswitch and iPay artwork logos to use on your website home page and shopping cart's online iPay forms by clicking here

.:: iPay Payments Made Easy ::.

version 1.1.0

12