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.
This is the B2C API
B2C Payment Processing Integration Manual
We would really appreciate feedback and suggestions.
Suggestions can be emailed to: [email protected]
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.
The base URL will be provided to you upon registration
/mobile/{channel}
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 alphanumeric[A-Z][a-z][0-9] reference generated by the merchant to identify the transaction
|
| phone | numeric string (15) | This is the mobile phone 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 phone number will be credited with
|
/pesalink| Field | Data Type(Data Length) | Description |
|---|---|---|
| amount | float | This is the amount the account will be credited with
|
| reference | alphanumeric(64) | This is a unique reference number to identify the transaction
|
| vid | alphanumeric(12) | This is the vendor ID of the merchant, ie merchant who will be using this API
|
| hash | alphanumeric(64) | This is a hash of the posted data, just to verify that this is from the vendor.
|
| sendernames | String | Name of person receiving funds(beneficiary)
|
| narration | String | Additional information
|
| bankcode | integer | Please click here to identify bank code https://www.kba.co.ke/wp-content/uploads/2022/05/Branches_list-2022.pdf
Please click here to identify bank code https://www.kba.co.ke/downloads/BankBranchesReport.pdf
|
| bankaccount | integer | Fully Qualified Bank account Number. Ensure ALL digits used in the target bank account number are quoted here
|
{
"status": 200,
"text": "QUEUED",
"reference": "DEMONEWR313EE1507797667127261164",
"timestamp": "2017-10-12 11:41:07",
"balance_as_of_now": 1840984
}
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.
it has a high time response therefore users need to be careful when using it
https://apis.ipayafrica.com/b2c/v3/pesalink/verify
| 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
|
| bankcode | integer | Please click here to identify bank code https://www.kba.co.ke/wp-content/uploads/2022/05/Branches_list-2022.pdf
|
| bankaccount | integer | Fully Qualified Bank account Number. Ensure ALL digits used in the target bank account number are quoted here
|
| hash | alphanumeric (64) | This is a hash of the posted data, just to verify that this is from the vendor.
|
{
"status": 200,
"data": {
"account_name": "xxxxxxxxxx",
"account_number": "xxxxxxxx"
},
"reference": "TESTxxxxxxxxxxxxxxxx",
"text": "SUCCESS"
}
This end point can be used to check transaction status in case 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.
|
{
"status": 200,
"text": "SUCCESS",
"ipay_reference": "DEMO3F01513739565110728933",
"mmref": "DEMO8S10HN4"
}
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, in Airtelmoney’s case this shall be the same as the ipay_reference
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
|
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);
?>
| 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
|