1.2 The REST API initiator request Call



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

//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);