Quick Start

Last updated: July 18th, 2018

B2B API

This is the B2B API

  • Quick summary
  • Version 1.0.0

What is this repository for?

B2B Payment Processing Integration Manual

How do I get set up?

  • Ensure that you have a merchant account with iPay.
  • Ensure your account has been set up to allow transactions
  • Ensure that you have a security key
  • Ensure that you have been provided with a base URL

Contribution guidelines

We would really appreciate feedback and suggestions. Issues, and suggestions can be emailed to technical [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 hope to improve the API over time. The changes won’t always be backward compatible, so we’re going to use versioning. There is currently no rate limit.

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

Getting Started

Funding Your B2B Account from your iPay Merchant income

currently not available

One can fund their B2B account by transferring funds directly from their account income ( transactions done using iPay ) to their B2B funds.

Note

This end point is currently unavailable

How to generate the hash value to sign the B2B payment request

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

An example is shown below:


                                            <?php
                                                $datastring = "key1=".$value1."&key2=".$value2
                                                /*************************************************************************************************/
                                                $hashkey = "yoursecuritykey"; //Supplied during iPay account registration;
                                                $datastring; //This is a string generated from the data to be posted (see above)
                                                $hashid = hash_hmac("sha256", $datastring, $hashkey); //
                                            ?>
                                            

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
POST  external/send/{channel}

or
POST  internal/send/{channel}


for mpesa channels use external/send since they are external to iPay ecosystem but to send within iPay merchants use internal/send

{channel} available channels mpesapaybill mpesatill ipay

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
account
This is the account 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 account will be credited with
narration
This is the account/narration of the transaction, it is mosty required in the mpesapaybill, if posted in the other requests it will be ignored
curr
This is the currency of the funds


Example of a successful response

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

Note

The transaction is queued in our system for processing. The callback url 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 incase one does not receive the callback

POST  transaction/status




Example of a successful response

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

Available channels

  • mpesapaybill
  • mpesatill
  • ipay

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