Quick Start

Last updated: July 18th, 2018

B2C API

This is the B2C API

  • Quick summary
  • Version 3.0.0

What is this repository for?

B2C Payment Processing Integration Manual

How do I get set up?

  • Ensure that you have an active merchant account with iPay.
  • Ensure that you have a valid security key
  • Ensure your account has been set up to allow B2C transactions
  • Ensure that you have been provided with a base URL. This is provided to you by iPay after vetting
  • Ensure that you have provided us with your callback URl. See Callback URL

Contribution guidelines

We would really appreciate feedback and suggestions.
Suggestions can be emailed to: support [at] ipayafrica [dot] com

Who do I talk to in case of any query?

  • For general issues, email support [at] ipayafrica [dot] com
  • For technical issues, email technical [at] ipayafrica [dot] com
  • Or send us a Skype request at ipaysupport

URI and Versioning

We are continuously improving our APIs. Some changes won’t always be backward compatible, so we’re going to use versioning. There is currently no rate limit on all incoming requests from your vetted iPay Vendor ID. For versioning purposes, only removal of a non-optional field or alteration of an existing field will be considered incompatible changes. You should gracefully handle additional fields you do not expect.

Endpoints

The base URL will be provided to you upon registration

Getting Started

Sending Money

  • Ensure that the account exists otherwise the transfer will fail
  • Ensure that the the channel is correct. See Available channels
  • Ensure that the merchant account has funds otherwise the transfer will fail


Mobile Money
POST
mobile/{channel}
{channel} available channels mpesa,elipa,airtelmoney

Below are the parameters to be posted to the end point

Field Description
vid
This is the vendor ID of the merchant, ie merchant who will be using this API
reference
This is a unique reference generated by the merchant to identify the transaction
phone
This is the mobile phone number receiving the funds.
hash
This is a hash of the posted data, just to verify that this is from the vendor.
amount
This is the amount the phone number will be credited with


Pesalink
POST
/pesalink
Field Description
amount
This is the amount the account will be credited with
reference
This is a unique reference number to identify the transaction
vid
This is the vendor ID of the merchant, ie merchant who will be using this API
hash
This is a hash of the posted data, just to verify that this is from the vendor.
sendernames
Name of person sending funds
narration
Additional information
bank Code
Please click here to identify bank code https://www.kba.co.ke/downloads/BankBranchesReport.pdf
bankaccount
Fully Qualified Bank account Number. Ensure ALL digits used in the target bank account number are quoted here


Example of a successful response

                                        {
                                                "status": 200,
                                                "text": "QUEUED",
                                                "reference": "DEMONEWR313EE1507797667127261164",
                                                "timestamp": "2017-10-12 11:41:07",
                                                "balance_as_of_now": 1840984
                                        }
                                        

Note

The transaction is queued in our system for processing. The callback url you provided will be triggered and the transaction status will be part of the callback data.

Transaction Status

This end point can be used to check transaction status in case one does not receive the callback

POST  transaction/status
Field Description
vid
This is the vendor ID of the merchant, ie merchant who will be using this API
reference
This is a unique reference generated by the merchant to identify the transaction
hash
This is a hash of the posted data, just to verify that this is from the vendor.
Example of a successful response

                                            {
                                                    "status": 200,
                                                    "text": "SUCCESS",
                                                    "ipay_reference": "DEMO3F01513739565110728933",
                                                    "mmref": "DEMO8S10HN4"
                                            }
                                            

Callback URL

when a transaction has been processed, iPay will respond to the provided callback url with GET parameters added to it. Ensure that your callback is able to receive GET data Below are the parameters to be expected

Field Description
ipay_reference
This is the transaction reference that was generated for the transaction
merchant_reference
This is the unique reference posted by the merchant when using the send money call
status
This is the status of the transaction. SUCCESS indicates SUCCESS
hash
This is a hash of the posted data, just to verify that this is from the vendor.
mmref
This is the transaction reference from the operator in the case of MPESA, eLipa, in Airtelmoney’s case this shall be the same as the ipay_reference

Available channels

  • mpesa
  • elipa
  • airtelmoney
  • pesalink

How to generate and validate the hash value used to sign the request

The hash is a data string of the parameter name and the values in an ASCII order from small to large sort. If the value is null, then the signature may not be involved. The HMAC hashing algorithm currently being used is SHA256. An example is shown below:


                                            <?php
                                                    $datastring = "key1=".$value1."&key2=".$value2
                                                    //(the key / parameter names above should be in alphabetical order. Your data string should **NOT** be urlencoded)
                                                    //*************************************************************************************************/
                                                    $hashkey = "yoursecuritykey"; //Provided by and supplied by iPay during account registration;
                                                    $datastring; //This is a string generated from the data to be posted (see above)
                                                    $hashid = hash_hmac("sha256", $datastring, $hashkey);
                                            ?>