1.2 Processing the POS Callback

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

Please provide the following:

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