Quick Start

Last updated: July 18th, 2019

1 B2B API

This is the B2B API

  • Quick summary
  • Version 1.0.0

1.1 What is this repository for?

B2B Payment Processing Integration Manual

1.2 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

1.3 Contribution guidelines

We would really appreciate feedback and suggestions. Issues, and suggestions can be emailed to [email protected]

1.4 Who do I talk to in case of any query?

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

1.6 Endpoints

Base URL

https://apis.ipayafrica.com/b2b/v1/

2 Getting Started

2.1 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

2.2 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 ASCII 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); //
                                            ?>
                                            

2.3 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 Data Type(Data Length) Description
vid alphanumeric (12)
This is the vendor ID of the merchant, ie merchant who will be using this API
reference alphanumeric(64)
This is a unique reference generated by the merchant to identify the transaction
account alphanumeric(12)
This is the iPay Vendor ID / Paybill / Till number receiving the funds.
hash alphanumeric(64)
This is a hash of the posted data, just to verify that this is from the vendor.
amount float
This is the amount the account will be credited with
narration string
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 alphanumeric (3)
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.

2.4 Transaction Status

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

POST  transaction/status


Field Data Type(Data Length) Description
vid alphanumeric(12)
This is the vendor ID of the merchant, ie merchant who will be using this API
reference alphanumeric(64)
This is a unique reference generated by the merchant to identify the transaction
hash alphanumeric (64)
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"
                                            }
                                            

2.6 Available channels

  • mpesapaybill
  • mpesatill
  • ipay

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

2.8 Status Codes
Status Code Error Message Cause/Reason
400 transaction reference exists
Non unique reference number
400 [param] missing
One of the payload params missing
400 hash mismatch
Generated hash does not match request params.
400 Not allowed
Use of unregistered ip address
400 amount available is not enough 43993.93 please fund your iPay bulkpay Account
Insufficient funds in your bulkpay.
403 too many requests to the same phone within specified period
More 3 transactions to one mobile money account per 24hrs
503/504 internal server error
Internal Server Error