1.2.6 Trigger SIM Toolkit (USSD)

URL

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

The parameters needed for this are as follows:

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 "demoCHANGED" for testing where vid 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.

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

1.2.7 Recurring Billing

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

The parameters needed for this are as follows:

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.2.8 Refund

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

The parameters needed for this are as follows:

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.3.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:

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.4.2 How to use the library

String live             = "0";
String vid              = "demo";
String cbk              = "http://example.com/cbk.php";
String security_key     = "demoCHANGED";
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();

 import com.ipay.iPaycheckout.PaymentActivity;

1.4.3 iPay Android Interface

The android interface will resemble the image shown below:

2.2 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

2.3 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 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)

(l) vat: this is the vat applied for the transaction

(m) commission: this is the commission charged for the transaction

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

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

Mobile Money Channel

CreditCard Channel

2.5 iPay Interface

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

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