Quick Start

Last updated: July 18th, 2018

iPay Developers API introduction

This is the C2B API

The IPay Integration is simple and seamless. There are two types of intergrations:-

IntegrationProcess Flow(English)API Calls(Geeklish)
1.1 Web Based Integrations

  • Customer checks out from merchant website/App/Desktop App and selects the iPay as the preferred payment method.
  • Customer is redirected to the iPay payment gateway where they will be presented with an interface containing the various payment channels.
  • The customer selects mode of payment, follows the instructions and pays.
  • If the transaction has successfully been processed and they press the [Confirm Payment] button, IPay will redirect to the merchant provided Callback URL with the respective statuses for the Processed Transaction.

  • Section 1.1 Parameters required for successful payment integration
  • Section 1.2 Making Payment Request and How to generate the hash parameter(defined in section 1.1) which signs the posted data.
  • Section. 2.1 Expected responses from callback
  • Section 2.4 The values that iPay returns explained
  • Section 2.3 Verifying the payment statuses with an IPN check
Rest API Calls

If you intend to use the iPay REST API to process card transactions, then you will have to certify that your system is PCI-DSS compliant. If you are not PCI-DSS compliant and still intend to process card transactions, then we would encourage you to use our Web-based API.

You can still use our REST API to process mobile money, mobile banking and mVisa/Masterpass (QR Code acquiring) channels.

  • Customer checks out from merchant App/website/Desktop App site and selects the iPay as the preferred payment method.
  • Customer is redirected to a custom page/view which is designed by you
  • Customer pays with the chosen payment option and the application and customer get relevant feedback responses
  • Section 1.2 The REST API initiator request Call
  • Section 1.3 The initiator request Response, with parameters for use in transact calls
  • Section 1.4  Mobile Money transact Call and Responses(processing mobile money transactions)
  • Section 1.5  Credit Card transact Call and Responses(processing Credit card transactions)

Change Log NEW

  • Update on section 1.4.1 Mobile money transact call and responses - 2016-10-12
  • Update on section 1.1 Added Autopay parameter - 2016-11-29
  • Added the Offline POS Integration - 2018-08-13

1.1 HOW and WHAT To POST/GET to the iPay gateway

(for each field, there are some characters not accepted by iPay. See Bottom of page)

Y = Yes N = No O = Optional
Parameter Name Data Type(Data Length) Description Channel
MobileKenswitchCredit Card
livenumeric(1)LIVE or DEMO mode (1 or 0). “1” By Default (live)YYY
mpesa numeric(1)Display Mpesa Mobile Money Channel (on or off). “on” by Default (i.e. mpesa=1)OOO
bonga numeric(1)Display Safaricom's Bonga Points Channel (on or off). “on” by Default (i.e. bonga=1)OOO
airtel numeric(1)Display Airtel Mobile Money Channel (on or off). “on” by Default (i.e. airtel=1)OOO
equitynumeric(1)Display the Equity EazzyPay Channel (on or off). “on” by Default (i.e. equity=1)OOO
mobilebankingnumeric(1)Display the Mobile Banking Channel (on or off). “off” by Default (i.e. mobilebanking=0)OOO
debitcardnumeric(1)Display the Debit Card Channel (on or off). “off” by Default (i.e. debitcard=0)OOO
creditcardnumeric(1)Display the Credit Card Channel (on or off). “off” by Default (i.e. creditcard=1)OOO
mkoporahisinumeric(1)Display Mkopo Rahisi Channel (on or off). “off” by Default(i.e. mkoporahisi=0)OOO
saidanumeric(1)Display Saida Channel (on or off). “off” by Default (i.e. saida=0)OOO
autopay NEWnumeric(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 iPay will send data to your server using GET request and the IPN should be run to verify this data.OOO
oidalphanumeric (34) Order ID YYY
invalphanumeric (15)Invoice Number (Set to Order ID value above if NULL)YYY
ttlnumeric (15) Total amount (DO NOT PASS any commas as a thousands separator). e.g. ttl=1234.00 and NOT ttl=1,234.00YYY
tel alphanumeric (15)Customer Telephone numberYYY
eml alphanumeric (30) Customer Email AddressYYY
vid alphanumeric (12)Vendor ID assigned by iPay. SET IN LOWER CASE YYY
curralphanumeric (3) Currency Type (USD or KES) * KES By Default NNY
p1 alphanumeric (15)Optional field. allows sending & receiving your custom parametersOOO
p2alphanumeric (15) Optional field. allows sending & receiving your custom parametersOOO
p3alphanumeric (15) Optional field. allows sending & receiving your customOOO
p4alphanumeric (15) Optional field. allows sending & receiving your custom parameters OOO
cbkalphanumeric (100)This parameter holds the value of the URL on your server to which iPay 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.
  • crl=0 for http/https call back
  • crl=1 for a data stream of comma separated values
  • crl=2 for a json data stream.
YYY
lbkalphanumeric (100)In the event that the client cannot check out successfully, iPay 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. OOO
cstnumeric (1)The customer email notification flag of value 1 or 0. (Set to “1” By Default to allow customer to receive txn notifications from iPay for online txns)YYY
crl numeric (1)Name of the cURL flag input field (1 character).
  • crl=0 for http/https call back
  • crl=1 for a data stream of comma separated values
  • crl=2 for a json data stream.
(Set to “0” By Default)
OOO
hsh alphanumeric (64)The computed iPay Hash CodeYYY

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 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.2 How to post your parameters to iPay for processing

URL

https://payments.ipayafrica.com/v3/ke

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.

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.

<?php
$datastring =  $live.$order_id.$invoice.$total.$phone.$email.$vid.$curr.$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;
/**********************************************************************************************************/
?>
If you are having trouble implementing this function, see Section 2.5 below.

Sample POST Formwith (PHP)


    <php?
    /*
    This is a sample PHP script of how you would ideally integrate with iPay Payments Gateway and also handling the 
    callback from iPay and doing the IPN check

    ----------------------------------------------------------------------------------------------------
                ************(A.) INTEGRATING WITH iPAY ***********************************************
    ----------------------------------------------------------------------------------------------------
    */
    //Data needed by iPay a fair share of it obtained from the user from a form e.g email, number etc...
    $fields = array("live"=> "0",
                    "oid"=> "112",
                    "inv"=> "112020102292999",
                    "ttl"=> "900",
                    "tel"=> "256712375678",
                    "eml"=> "[email protected]",
                    "vid"=> "demo",
                    "curr"=> "KES",
                    "p1"=> "airtel",
                    "p2"=> "020102292999",
                    "p3"=> "",
                    "p4"=> "900",
                    "cbk"=> $_SERVER["HTTP_HOST"].$_SERVER["REQUEST_URI"],
                    "cst"=> "1",
                    "crl"=> "2"
                    );
    /*
    ----------------------------------------------------------------------------------------------------
    ************(b.) GENERATING THE HASH PARAMETER FROM THE DATASTRING *********************************
    ----------------------------------------------------------------------------------------------------

    The datastring IS concatenated from the data above
    */
    $datastring =  $fields['live'].$fields['oid'].$fields['inv'].$fields['ttl'].$fields['tel'].$fields['eml'].$fields['vid'].$fields['curr'].$fields['p1'].$fields['p2'].$fields['p3'].$fields['p4'].$fields['cbk'].$fields['cst'].$fields['crl'];
    $hashkey ="demo";//use "demo" for testing where vid also is set to "demo"

    /********************************************************************************************************
    * Generating the HashString sample
    */
    $generated_hash = hash_hmac('sha1',$datastring , $hashkey);

    ?>

    
    
  

 
       
<?php foreach ($fields as $key => $value) { echo $key; echo ' :
'; } ?> hsh: 

################################################################################################################################

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://ipayafrica.com/hashid/
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 section 1.1.

iPay – Payments made Easy :: version 3.0
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 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 iPay, then you will get an error stating this and showing you how to go about how to remedy this.

1.1 HOW and WHAT To POST/GET to the IPay gateway

(for each field, there are some characters not accepted by IPay. See Bottom of page)

Parameter Name Data Type(Data Length) Description Channel
MobileCredi Card
livenumeric(1)LIVE or DEMO mode (1 or 0). “1” By Default (live)YY
fname numeric(12)Card Holder's first nameNY
lnamealphanumeric(12)Card Holder's last nameNY
cardnonumeric string(16)The 16 digit card number NY
cvvnumeric string(5)The 3 or 4 digit Card Verification NumberNY
Monthnumeric string(2)Expiry Month e.g. 01, 12, 09NY
Yearnumeric string(2)Expiry Year e.g. 22, 19NY
cust_addressalphanumeric(25)Customer's Card Billing AddressNY
cust_postCodealphanumeric(10)Customer's Card Billing Postal Code NY
cust_cityalphanumeric(15)Customer's City where Card was issuedNY
cust_stateProvalphanumeric(15)Customer's State / Province where Card was issuedNY
cust_countryalphanumeric(12)Customer's State / Province where Card was issuedNY
oidalphanumeric (34) Order ID YY
invalphanumeric (15)Invoice Number (Set to Order ID value above if NULL)YY
amountnumeric (15) Total amount (DO NOT PASS any commas as a thousands separator). e.g. ttl=1234.00 and NOT ttl=1,234.00YY
tel alphanumeric (15)Customer Telephone number. if no phone number is used.PAD a default numberYY
eml alphanumeric (30) Customer Email AddressYY
vid alphanumeric (12)Vendor ID assigned by IPay. SET IN LOWER CASE YY
curralphanumeric (3) Currency Type (USD or KES) * KES By Default YY
autopay NEWnumeric(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 iPay will send data to your server using GET request and the IPN should be run to verify this data.OO
p1 alphanumeric (15) allows sending & receiving your custom parametersYY
p2alphanumeric (15) allows sending & receiving your custom parametersYY
p3alphanumeric (15) allows sending & receiving your customYY
p4alphanumeric (15) allows sending & receiving your custom parameters YY
cbkalphanumeric (100)This parameter holds the value of the URL on your server to which iPay will send back payment processing data to. YY
cstnumeric (1)The customer email notification flag of value 1 or 0. (Set to “1” By Default to allow customer to receive txn notifications from IPay for online txns)YY
crl numeric (1)Name of the cURL flag input field (1 character).
  • crl=0 for http/https call back
  • crl=1 for a data stream of comma separated values
  • crl=2 for a json data stream.
(Set to “0” By Default)
YY
hash alphanumeric (64)The computed IPay Hash CodeYY

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.

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.2 The REST API initiator request Call

URL


    https://apis.ipayafrica.com/payments/v2/transact

The Request is an initiator for a yet to be paid transaction i.e. it registers the transaction on IPay which requires payment. It Returns a few parameters which will be used for the transact calls which process the payment once the user has paid.

There are two transact calls after the initiator request call they are for the two channels Mobile Money and Credit Card

The parameters needed for this are as follows:

Parameter Name Data Type(Data Length) Description Channel
MobileCredi Card
livenumeric(1)LIVE or DEMO mode (1 or 0). “1” By Default (live)YY
oidalphanumeric (34) Order ID YY
invalphanumeric (15)Invoice Number (Set to Order ID value above if NULL)YY
amountnumeric (15) Total amount (DO NOT PASS any commas as a thousands separator). e.g. ttl=1234.00 and NOT ttl=1,234.00YY
tel alphanumeric (15)Customer Telephone number. if no phone number is used.PAD a default numberYY
eml alphanumeric (30) Customer Email AddressYY
vid alphanumeric (12)Vendor ID assigned by IPay. SET IN LOWER CASE YY
curralphanumeric (3) Currency Type (USD or KES) * KES By Default YY
p1 alphanumeric (15) allows sending & receiving your custom parametersYY
p2alphanumeric (15) allows sending & receiving your custom parametersYY
p3alphanumeric (15) allows sending & receiving your customYY
p4alphanumeric (15) allows sending & receiving your custom parameters YY
cbkalphanumeric (100)This parameter holds the value of the URL on your server to which iPay will send back payment processing data to. YY
cstnumeric (1)The customer email notification flag of value 1 or 0. (Set to “1” By Default to allow customer to receive txn notifications from IPay for online txns)YY
crl numeric (1)Name of the cURL flag input field (1 character).
  • crl=0 for http/https call back
  • crl=1 for a data stream of comma separated values
  • crl=2 for a json data stream.
(Set to “0” By Default)
YY
hash alphanumeric (64)The computed IPay Hash CodeYY

The REST API has atleast 2 calls the first inorder to get the sid on the response as shown in Section 1.3 below. then Depending on what you are transacting (Card | Mobile Money) you will make a secondary call.

For information on Mobile Money secondary Calls Go to : 1.4.1 Mobile Money Transact Call and Responses

For information on Card secondary Calls Go to: 1.4.2 Credit Card Transact Call and Responses

Inorder to post to iPay for Payment processing, We need to sign the Data with a hash signature this is to be sent as the data in the hash parameter indicated in the table above. We are using the hash_hmac function found in PHP in this example to digitally sign the transaction data.

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.

  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.
<?php
//check hash
$key "SECretKey";//use "demo" for testing where vid also is set to "demo"
$datastring $live.$oid.$inv.$amount.$tel.$eml.$vid.$curr.$p1.$p2.$p3.$p4.$cst.$cbk;
/*********************************************************************************************************/

$generated_hash hash_hmac('sha256',$datastring $key);
/**********************************************************************************************************/
?>

1.3 REST API Initiator request Response

The REST API returns an initial response for processing which you will use to POST to iPay to finalise the transactions On successful posting the API should return the following response


{
"header_status": 200,
"status": 1,
"data": {
"sid": "87491e89-a997-401f-8816-3422fa0219b9",
"oid":"001",
"amount":"200",
"account":"GA257298",
"payment_channels": [
  {
    "name": "MPESA",
    "paybill": "510800"
  },
  {
    "name": "AIRTEL",
    "paybill": "510800"
  }
]
},
"hash":"75bc1fa140b731be4829b887d2b8d62f038c741b9672c743eba226a9e2f2858a"
}
To validate the response hash The hash is generated by concatenation of the account, amount, oid, sid, mpesa, paybill, airtel, airtel_paybill.
<?php
    $sign_datastring 
$account.$amount.$oid.$sid.$mpesa.$paybill.$airtel.$airtel_paybill;
    
with the above example the string will be

    
//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");
    
/**********************************************************************************************************/
?>

1.4.1 Mobile Money Transact Call and Response

For the REST API POST to this URL:

https://apis.ipayafrica.com/payments/v2/transact/mobilemoney

The Parameters to post are:
vidalphanumeric (12) The iPay Merchant vendor id
sidalphanumeric (64) The sid from the initiator request responses
hashalphanumeric (64) Generated signature of the data based on a secret key shared between iPay and you(our MErchant)

The hash is generated by the concatenation of the sid 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.4.

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");?>

1.4.2 Credit Card Transact Call and Reponses

For Card the url Endpoint is:


                                               https://apis.ipayafrica.com/payments/v2/transact/cc
                                            
The following parameters are required for this POST.
ParameterData type (length)Description
vidalphanumeric (12) The iPay Merchant vendor id
curralphanumeric (3) currency in KES, USD
cvvnumeric string (5) The unique 3-4 digit Card Verification Number provided at the back of the card
cardnonumeric string(16) The 16 digit Card Number,
monthnumeric string(2)Expiry Month
yearnumeric string(2)Expiry Year
cust_addressalphanumeric(25)Customer's Card Billing Address
cust_postcodealphanumeric(10)Customer's Card Billing Postal Code
cust_cityalphanumeric(15)Customer's City where Card was issued
cust_stateprovalphanumeric(15)Customer's State / Province where Card was issued
cust_countryalphanumeric(12)Customer's State / Province where Card was issued
sidalphanumeric (64) The sid from the initiator request responses
fnamealphanumeric (12)Card Holder's Firstname
lnamealphanumeric (12)Card Holder's Last Name
hashalphanumeric (64)The hash string used to validate the data, please note below the datastring required
tokenizenumeric (1)When this parameter is passed, indicates that iPay should tokenize the card.
recurringnumeric (1)When this parameter is passed, it checks if the tokenized parameter was set. If correctly passed, iPay will return the card token on callback.

Generating the Hash String

The hash string is used for signing the data, it uses the same shared secret key between the Merchant and iPay. The hash is generated as follows:


<?php
//check hash
$key "SECretKey";//use "demo" for testing where vid also is set to "demo"
$datastring $sid.$vid.$cardno.$cvv.$month.$year.$cust_address.$cust_city.$cust_Country.$postcode.$stateprov.$fname.$lname;
/*********************************************************************************************************/

$generated_hash hash_hmac('sha256',$datastring $key);
/**********************************************************************************************************/
?>

Expected Response on Successfull card transaction


{"txncd":"1111111122","qwh":"1000988633","afd":"827071654","poi":"1211883119","uyt":"1431931896",
"ifd":"548464895","agt":"","id":"oid","status":"bdi6p2yy76etrs","ivm":"oid","mc":"100",
"p1":"","p2":"","p3":"","p4":"","msisdn_id":"John Doe","msisdn_idnum":"123456",
"msisdn_custnum":"123456","channel":"Credit_Card","card_mask":"444444xxxxxx4444"}

1.4.3 Trigger SIM Toolkit (STK PUSH)

URL


https://apis.ipayafrica.com/payments/v2/transact/push/mpesa

The Request is an initiator for an STK push yet to be paid transaction i.e. it Triggers the wallet user's SIM ToolKit for authorization of payment on their handset.

This is only available for MPESA.

The parameters needed for this are as follows:

Parameter Name Data Type(Data Length) Description Channel(MPESA)
phone numeric string (15) The Phone Number of the registered mobile wallet User Y
sid alphanumeric (64) The sid from the initiator request responses Y
vid alphanumeric(12) The iPay Merchant vendor id Y
hash alphanumeric(64) A digital signature hash of the data for verification. Y

The hash is generated from a datastring which is a concatenation of the parameters: phone,sid and vid it is a HMAC with the sha256 hashing algorithm. Sample PHP script of the same is show below:


<?php
//your SECRET KEY 
$key "SECretKey";//use "demo" for testing where vid also is set to "demo"
$datastring $phone.$vid.$sid;
/*********************************************************************************************************/

$generated_hash hash_hmac('sha256',$datastring $key);
/**********************************************************************************************************/
?>

Response

The following is a sample response on Triggering this route.

The following is a sample response on Triggering this route.


    {
      "header_status":"200", 
      "status":1,
      "text":"A Payment request has been sent to the MPESA number 2547XXXXXXXX"
    }

1.4.4 Recurring Billing

The endpoint is:

https://apis.ipayafrica.com/payments/v2/transact/cc/recurring

The parameters needed for this are as follows:

Parameter Name Data Type(Data Length) Description Channel(MPESA)
sid alphanumeric (64) The sid from the initiator request responses Y
vid alphanumeric(12) The iPay Merchant vendor id Y
email alphanumeric(30) Customer Email Address Y
cardid alphanumeric(64) The tokenized card id that is sent on email Y
phone alphanumeric(15) Customer Telephone number. if no phone number is used.PAD a default number Y
hash alphanumeric(64) A digital signature hash of the data for verification. Y

The hash is generated from a datastring which is a concatenation of the parameters: sid, vid, email, cardid and phone 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 $sid.$vid.$cardid.$phone.$email;
/*********************************************************************************************************/

$generated_hash hash_hmac('sha256',$datastring $key);
/**********************************************************************************************************/
?>

Response

Expected Response on Successfull card transaction.


{"txncd":"1111111122","qwh":"1000988633","afd":"827071654","poi":"1211883119","uyt":"1431931896",
"ifd":"548464895","agt":"","id":"oid","status":"bdi6p2yy76etrs","ivm":"oid","mc":"100",
"p1":"","p2":"","p3":"","p4":"","msisdn_id":"John Doe","msisdn_idnum":"123456",
"msisdn_custnum":"123456","channel":"Credit_Card"}

1.5 Refund

The endpoint is:

https://apis.ipayafrica.com/payments/v2/transaction/refund

The 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
if you do not have funds or available in your c2b account, your b2c account ( bulkpay ) will be considered if neither is present then the refund will fail.

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

////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
1.1 Initiate POS Transactions

M-Pesa URL

https://apis.ipayafrica.com/payments/v2/transact/manualpush/mpesa

Equitel URL

https://apis.ipayafrica.com/payments/v2/transact/manualpush/equitel

The Request is an initiator for an STK push yet to be paid transaction i.e. it Triggers the wallet user's SIM ToolKit for authorization of payment on their handset.

This is only available for MPESA and Equitel. For other channels the users will have to go to their SIM Toolkit and use the Paybill provided e.g 510800 and then use a sub-account as the account.

The parameters needed for this are as follows:

Parameter Name Data Type(Data Length) Description Channel(MPESA)
phone numeric string (15) The Phone Number of the registered mobile wallet User Y
vid alphanumeric(12) The iPay Merchant vendor id Y
amount numeric (15) The amount to be paid by the client. Y
account alphanumeric(12) Sub-account provided by iPay. Y

The hash is generated from a datastring which is a concatenation of the parameters: phone,vid,amount and account. 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 $phone.$vid.$amount.$account;
/*********************************************************************************************************/

$generated_hash hash_hmac('sha256',$datastring $key);
/**********************************************************************************************************/
?>

Response

The following is a sample response on Triggering this route.


{
  "header_status":"200", 
  "status":1,
  "text":"A Payment request has been sent to the MPESA number 2547XXXXXXXX"
}

1.2 Processing the POS Callback

We will push data to a HTTP(S) URL that you designate to us.

Please provide the following:

  • A private hashing key of your choice (max of 8 alphanumeric characters)
  • A HTTP(S) URL that will receive the data from our end

We will post the following data to you in JSON format:

Fields Parameter Name Data Format / Type Data State
Transaction Amount amount String Dynamic
Mobile Money Provider channel String Dynamic
Hash Signature hash String Dynamic
Customer Telephone Number msisdn String Dynamic
Customer Names names String Dynamic
Transaction Time Stamp tstamp yyyy-mm-dd hh:mm:ss Dynamic
Transaction Code txnid String Dynamic
Account Details vendorid String Static

We will then hash the parameters with your iPay Security key using SHA256 algorithm. Please note that the data string to be hashed will be set up as an ASCII string. The parameters names and their values should be set in alphabetical order when hashing.


amount=234.00&channel=MPESA&msisdn=254700000000&names=Peter 
Kamau&tstamp=2012-12-31 23:59:59&txnid=DX12RT123&vendorid=TESTDATA

We are using the hash_hmac function to digitally sign the transaction. Please use the equivalent HMAC function in your programming language. Here is a PHP example below:


$hashkey = "youripaysecuritykey"; //Please supply us with this parameter

$datastring ="amount=234.00&channel=MPESA&msisdn=254712345678&names=Peter
Kamau&tstamp=2012-12-31 23:59:59&txnid=DX12RT123&vendorid=TESTDATA";

We will then send this hash together with the transaction parameters for you to replicate the hash test (via the HMAC function and the SAME KEY). Based on the result, you can then either accept the data or reject it.

We will send the data in JSON format via HTTP POST as follows:


{
"amount":"234.00",
"channel":"MPESA",
"msisdn":"254712345678",
"names":"Peter Kamau",
"tstamp":"2012-12-31 23:59:59",
"txnid":"DX12RT123",
"vendorid":"TESTDATA",
"hash":"y9857b460p5b133a32f36309665b8f2e6fad221d"
}

We expect your server to respond with the following JSON responses for iPay to know that the data was correctly received and validated by your system.

For Successful receipts:


{
"status":"1",
"id":"DX12RT123",
"message":"Success"
}

For Failed receipts:


{
"status":"0",
"id":"DX12RT123",
"message":"Failed"
}

For Duplicate receipts:


{
"status":"2",
"id":"DX12RT123",
"message":"Duplicate"
}

1.1 How to get the library into your project

1.1.1 For gradle

Step 1. Add JitPack repository to your build file
In your root build.gradle at the end of repositories add jitpack as shown bellow:

        
    allprojects {
            repositories {
                ...
                maven { url 'https://jitpack.io' }
            }
    }

Step 2. Add the dependency and sync your project

        
    dependencies {
        ...
        implementation 'com.github.iPaykenya:iPay-easy-way:0.0.3'
    }

1.1.2 For maven

Step 1. Add JitPack repository to your build file

   
    <repositories>
        <repository>
            <id>jitpack.io</id>
            <url>https://jitpack.io</url>
        </repository>
    </repositories>

Step 2. Add the dependency and sync your project


    <dependency>
        <groupId>com.github.iPaykenya</groupId>
        <artifactId>iPay-easy-way</artifactId>
        <version>0.0.3</version>
    </dependency>

1.2 How to use the library

NOTE: the transaction response will be sent to the call back url you provide. To process the call back data check on section 2
Assign the following variables with their corresponding values as shown below:

String live             = "0";
String vid              = "demo";
String cbk              = "http://example.com/cbk.php";
String security_key     = "demo";
String amount           = "10";
String p1               = "value1";
String p2               = "value2";
String p3               = "value3";
String p4               = "value4";
String curr             = "KES"; //or USD
String phone_number     = "0700000000";
String email            = "[email protected]";

Instantiate a Channels fragment and use it to pass the above parameters to your library in order to load the iPay Payment Interface.


    FragmentManager fragmentManager = getSupportFragmentManager();
    FragmentTransaction fragmentTransaction = fragmentManager.beginTransaction();
    Channel fragment1 = new Channel();
    Bundle data = new Bundle();
    data.putString("live", live);
    data.putString("vid", vid);
    data.putString("cbk", cbk);
    data.putString("key", security_key);
    data.putString("amount", amount);
    data.putString("p1", p1);
    data.putString("p2", p2);
    data.putString("p3", p3);
    data.putString("p4", p4);
    data.putString("currency", curr);
    data.putString("phone", phone_number);
    data.putString("email", email);
    fragment1.setArguments(data);
    fragmentTransaction.add(R.id.layouta, fragment1, "fragment");
    fragmentTransaction.commit();

finally import the following:
 import com.libs.ipay.ipayLibrary.Channel;

2.2 Merchant-defined HTTP Call back response / 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 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/ipay.php.

Therefore the iPay 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 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 Section 1.1 of this manual.

Please also see Section 2.3 (Additional Call Back / Return URL Security) below for an even more effective and

recommended payment notification security check that you should implement.

2.3 Payment Verification

You can verify the payment status of each transaction on callback. This code (or similar) Demonstrates how.


<?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"];

$ipnurl "https://www.ipayafrica.com/ipn/?vendor=".$val."&id=".$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 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)

//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 IPay on callback to the Callback url(cbk) supplied,
they are described in Section 2.4 The variables that iPay returns

2.4 The variables that iPay 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 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.

(j) card_mask: It will return the card mask of the client e.g "card_mask":"444444xxxxxx4444".

(k) 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 Testing your implementation

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 Section 1.1.

Once your testing is complete, then set the the live parameter to “1” and you are ready to go. see 1.1.

Mobile Money Channel

MPESA, Airtelmoney
There are no Test Values for this just ensure that the Live parameter is "0" for Demo as indicated above

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
2.6 iPay Interface

Once successfully intergrated to the iPay Gateway you should see an interface like so :

ipay interface

The Above example represents when a user has clicked on the Mpesa tab

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