Kemru Technologies API merchant service is engineered to create simple APIs that perform multiple complex functions. From a single payment APIs that make payments to mobile wallets, banks and cards to single Utility Vending that allows Bill Payments across multiple Telco’s and multiple digital service providers.
Note
Sandbox Endpoint http://sandbox.kemrut.com
MERCHANT
Building great products. We abstract all the complexity and present easy-to-integrate APIs for you.
AUTHENTICATION AND AUTHORIZATION
Standard Request Bodies
The standard request headers needed when authenticating with the API across all requests are:
| FIELD | DESCRIPTION |
|---|---|
| Content-Type | The content type of the payload: application/json |
| apiKey | This Key is generated upon registration. |
API ACCOUNT
i. Check Account Balance
Cash Management solutions & systems for your bank
Request Parameters
In addition to the Standard request headers, the body of the request should contain the following fields:
Equipping your customers with the next generation of cash management systems.
Body Parameters:
| FIELD | DESCRIPTION |
|---|---|
| MerchantID | This identifies the Merchant making use of the Payment and Billing platform. |
| signature | A HMAC SHA-256 signature to proof that the request is coming from the Merchant. Build a string of
concatenated values of the request fields with the following order: MerchantID The resulting string is then signed with the Key Provided upon registration. |
User and Member Details
i. Check Account Details
To check user details, you need to enter the user's unique identifier (e.g., username, phone number, or email) and access token. Check all users' details; you need to enter the access token.
The member details will be a bit different from those of users. You need to enter the member's unique identifier (e.g., national identity number or passport number) and an access token.
Request Parameters
In addition to the Standard request headers, the body of the request should contain the following fields:
Equipping your customers with the next generation of cash management systems. Check all members details; you need to enter the access token.
Body Parameters:
| FIELD | DESCRIPTION |
|---|---|
| Access Token | This identifies the merchant's details and identity or partner ID. |
| Username | This is to identify either a user or a member by a unique identifier, e.g., email, username, national identity number, or phone number |
GET http:/kemrut.com/api-user
Host: {GatewayBaseURL}
Content-Type: application/json
Sample Body:
Sample Response:
{
"access_token": "301-565-660-353/1953"
}
[
{
"id": "717445",
"firstname": "Verah",
"lastname": "Okoth",
"phone": "+254739117883",
"email": "system@kemrut.com",
"country": "Kenya"
}
]
| FIELD | DESCRIPTION |
|---|---|
| Access Point | This identifies the Merchant partner ID |
GET http:/kemrut.com/api-biometric
Host: {GatewayBaseURL}
Content-Type: application/json
Sample Body:
Sample Response:
{
"access_token": "301-565-660-353/1953"
}
[
{
"id": "717445",
"firstname": "Verah",
"lastname": "Okoth",
"phone": "+254739117883",
"email": "system@kemrut.com",
"country": "Kenya"
},
{
"id": "717446",
"firstname": "John",
"lastname": "Doe",
"phone": "+2547391178837",
"email": "1system@kemrut.com",
"country": "Kenya"
}
]
| FIELD | DESCRIPTION |
|---|---|
| Access Point | This identifies the Merchant partner ID |
| UID | This is the the Student or Employee identity. |
| Sample Response | This is the Merchant json respomse returned after a request has been requested |
GET http:/kemrut.com/api-memberc
Host: {GatewayBaseURL}
Content-Type: application/json
Sample Body:
Sample Response:
{
"access_token": "301-565-660-353/1953"
}
[
{
"status_code": "200",{
"id": "20170",
"partnerid": "19",
"sid": "1",
"account": "191",
"type": "O",
"check_time": "3/31/2024 12:21:20 PM",
"emp_name": "SAGINI OBED",
"phone": "+254739117883",
"date": "3/31/2024 12:21:20 PM",
"status": "1",
"date_added": "2024-03-31 12:28:46",
"bal": "16",
"gender": "Male",
"sn": "6160052169871",
"com_id": "0",
"names": "pending..",
"ins": "0",
"ind": "0",
"ind1": "0",
"fee": "0",
"kcpe": null,
"upi": null,
"user": null,
"deskTop": null,
"form": "0",
"stream": "0",
"SmsTrackingId": "0",
"SmsStatus": "Sent",
"title": "Student"
}
]
GET http:/kemrut.com/api-single
Host: {GatewayBaseURL}
Content-Type: application/json
Sample Body:
Sample Response:
{
"access_token": "301-565-660-353/1953",
"uid": "12345"
}
[
{
"status_code": "200",{
"id": "20170",
"partnerid": "19",
"sid": "1",
"account": "191",
"type": "O",
"check_time": "3/31/2024 12:21:20 PM",
"emp_name": "SAGINI OBED",
"phone": "+254739117883",
"date": "3/31/2024 12:21:20 PM",
"status": "1",
"date_added": "2024-03-31 12:28:46",
"bal": "16",
"gender": "Male",
"sn": "6160052169871",
"com_id": "0",
"names": "pending..",
"ins": "0",
"ind": "0",
"ind1": "0",
"fee": "0",
"kcpe": null,
"upi": null,
"user": null,
"deskTop": null,
"form": "0",
"stream": "0",
"SmsTrackingId": "0",
"SmsStatus": "Sent",
"title": "Student"
}
]
| FIELD | DESCRIPTION |
|---|---|
| Access Point | This identifies the Merchant partner ID |
| UID | This is the the Student or Employee identity. |
| Sample Response | This is the Merchant json respomse returned after a request has been requested |
GET http:/kemrut.com/api-biometric
Host: {GatewayBaseURL}
Content-Type: application/json
Sample Body:
Sample Response:
{
"access_token": "301-565-660-353/1953"
}
[
{
"status_code": "200",{
"id": "20170",
"partnerid": "19",
"sid": "1",
"account": "191",
"type": "O",
"check_time": "3/31/2024 12:21:20 PM",
"emp_name": "SAGINI OBED",
"phone": "+254739117883",
"date": "3/31/2024 12:21:20 PM",
"status": "1",
"date_added": "2024-03-31 12:28:46",
"bal": "16",
"gender": "Male",
"sn": "6160052169871",
"com_id": "0",
"names": "pending..",
"ins": "0",
"ind": "0",
"ind1": "0",
"fee": "0",
"kcpe": null,
"upi": null,
"user": null,
"deskTop": null,
"form": "0",
"stream": "0",
"SmsTrackingId": "0",
"SmsStatus": "Sent",
"title": "Student"
}
]
GET http:/kemrut.com/api-single
Host: {GatewayBaseURL}
Content-Type: application/json
Sample Body:
Sample Response:
{
"access_token": "301-565-660-353/1953",
"uid": "12345"
}
[
{
"status_code": "200",{
"id": "20170",
"partnerid": "19",
"sid": "1",
"account": "191",
"type": "O",
"check_time": "3/31/2024 12:21:20 PM",
"emp_name": "SAGINI OBED",
"phone": "+254739117883",
"date": "3/31/2024 12:21:20 PM",
"status": "1",
"date_added": "2024-03-31 12:28:46",
"bal": "16",
"gender": "Male",
"sn": "6160052169871",
"com_id": "0",
"names": "pending..",
"ins": "0",
"ind": "0",
"ind1": "0",
"fee": "0",
"kcpe": null,
"upi": null,
"user": null,
"deskTop": null,
"form": "0",
"stream": "0",
"SmsTrackingId": "0",
"SmsStatus": "Sent",
"title": "Student"
}
]
| FIELD | DESCRIPTION |
|---|---|
| Access Point | This identifies the Merchant partner ID |
| UID | This is the the Student or Employee identity. |
| Sample Response | This is the Merchant json respomse returned after a request has been requested |
Example Request:
POST https://developer.kemrut.com/api-link
Host: {GatewayBaseURL}
Access Token: {access_token}
Content-Type: application/json
Sample Body:
{
"access_token": "2573-237-532-529/8145"
}
Note
For possible errors and solutions, refer to the Error section.
ii. Check Transaction Status.
This is a quick way to check whether the status of the Pending transaction.
Request Parameters
Register URL API works hand in hand with Customer to Business (C2B) APIs and allows receiving members details in your db. This API enables you to register the callback URLs via which you shall receive notifications for payments to the pay bill/till number.
URL Requirements Use publicly available (Internet-accessible) IP addresses or domain names. All Production URLs must be HTTPS, on Sandbox you're allowed to simulate using HTTP. Avoid using keywords such as kemrut, exe, exec, cmd, SQL, query, or any of their variants in either upper or lower cases in your URLs. Do not use public URL testers e.g. ngrok, mockbin, or requestbin, especially on production, they are also usually blocked by the API. Use your own application URLs and do not make them public or share them with any of your peers.
On the sandbox, you are free to register your URLs multiple times or even overwrite the existing ones. In the production environment, this is a one-time API call that registers your validation and confirmation URLs to have them changed you can delete them on the URL management tab under self-service and re-register using register URL API, you can also email us at apisupport@kemrut.com for assistance. As you set up the default value, the words “Cancelled/Completed” must be in sentence case and well-spelled.
How to Create a Subdomain for my Domain It is not always necessary to register a new domain name if you already have one and you are interested to have a separate site apart from the main one. Rather than registering a new domain name, you can always create a subdomain using a domain you already own, for example blog.domain.tld or forum.domain.tld (assuming you already hold domain.tld). You can also add multiple levels of subdomains, for instance info.blog.domain.tld. Subdomains are extensions of your domain name that you can forward to URLs or point to IP addresses instead of purchasing additional domains. Usually, they are used for segmentation or verification of different services associated with a domain name. You are welcome to follow the video guide or check out the text instructions provided below.
Add a CNAME (virtual.kemrut.com) record to your domain's DNS records You might need to add a CNAME record to your domain host to either verify your domain or reset your administrator password. Your domain host is typically where you purchased your domain name (like GoDaddy, Enom, or Name.com). You may also need to add a CNAME record to your domain host if you are in the process of mapping your system with our system. add (virtual.kemrut.com)
| FIELD | DESCRIPTION |
|---|---|
| MerchantID | The content type of the payload: application/json |
| transactionRef | This is the Merchant reference returned after a request has been posted on the payment and Billing platform. |
| signature | A HMAC SHA-256 signature to proof that the request is coming from the Merchant. Build a string of
concatenated values of the request fields with the following order: MerchantID+ transactionRef The resulting string is then signed with the Key Provided upon registration. |
Example Request:
POST http:/kemrut.com/api-business
Host: {GatewayBaseURL}
Content-Type: application/json
Sample Body:
{
"name":"Kemru Technologies",
"contact":"+254739117883",
"link":"developer.kemrut.com",
"email":"system@kemrut.com"
}
Sample Response:
[
{
"status_code":"200",
"status_desk":"success"
},
{
"message": "Kemru Technologies created successfully"
}
]
Confirm and Verify Business Name
As a developer, you are constantly looking for ways to improve your skills,
stay up to date with the latest technologies, and discover new tools that can help you build better applications.
You can retrieve Company details using either an email address, phone number, or link.
Example Request:
GET http:/kemrut.com/api-confirm
Host: {GatewayBaseURL}
Content-Type: application/json
Sample Body:
{
"search":"system@kemrut.com"
}
Sample Response:
[
{
"status_code": "200",
"status_desc": "Success"
},
{
"Merchant_Details": {
"id": "1",
"name": "Antenk Auto Tech",
"email": "system@kemrut.com",
"link": "virtual.kemrut.com"
}
}
]
GET http:/kemrut.com/api-biometric
Host: {GatewayBaseURL}
Content-Type: application/json
Sample Body:
Sample Response:
{
"access_token": "301-565-660-353/1953"
}
[
{
"status_code": "200",{
"id": "20170",
"partnerid": "19",
"sid": "1",
"account": "191",
"type": "O",
"check_time": "3/31/2024 12:21:20 PM",
"emp_name": "SAGINI OBED",
"phone": "+254739117883",
"date": "3/31/2024 12:21:20 PM",
"status": "1",
"date_added": "2024-03-31 12:28:46",
"bal": "16",
"gender": "Male",
"sn": "6160052169871",
"com_id": "0",
"names": "pending..",
"ins": "0",
"ind": "0",
"ind1": "0",
"fee": "0",
"kcpe": null,
"upi": null,
"user": null,
"deskTop": null,
"form": "0",
"stream": "0",
"SmsTrackingId": "0",
"SmsStatus": "Sent",
"title": "Student"
}
]
GET http:/kemrut.com/api-single
Host: {GatewayBaseURL}
Content-Type: application/json
Sample Body:
Sample Response:
{
"access_token": "301-565-660-353/1953",
"uid": "12345"
}
[
{
"status_code": "200",{
"id": "20170",
"partnerid": "19",
"sid": "1",
"account": "191",
"type": "O",
"check_time": "3/31/2024 12:21:20 PM",
"emp_name": "SAGINI OBED",
"phone": "+254739117883",
"date": "3/31/2024 12:21:20 PM",
"status": "1",
"date_added": "2024-03-31 12:28:46",
"bal": "16",
"gender": "Male",
"sn": "6160052169871",
"com_id": "0",
"names": "pending..",
"ins": "0",
"ind": "0",
"ind1": "0",
"fee": "0",
"kcpe": null,
"upi": null,
"user": null,
"deskTop": null,
"form": "0",
"stream": "0",
"SmsTrackingId": "0",
"SmsStatus": "Sent",
"title": "Student"
}
]
FIELD
DESCRIPTION
Access Point
This identifies the Merchant partner ID
UID
This is the the Student or Employee identity.
Sample Response
This is the Merchant json respomse returned after a request has been requested
iii. Telco Check.
This is a quick way to check the Telco.
Request Parameters
In addition to the Standard request headers, the body of the request should contain the following fields:
Body Parameters:
FIELD
DESCRIPTION
MerchantID
This identifies the Merchant doing Telco Check
Prefix
This is the Merchant reference returned after a request has been posted.
signature
A HMAC SHA-256 signature to proof that the request is coming from the Merchant.
Example:
"MerchantID": "",
"prefix": "722",
"signature": "" //sign only the merchant ID, similar to check balance API
Note
For possible errors and solutions, refer to the Error section.
PAYMENT API
Payment Collection, Bank & Mobile Wallet Payout.
A. MOBILE WALLET PAYOUT API
This API allows you to send payments from your Payment Wallet to mobile subscribers with the following Mobile Wallet Channels
available in Kenya.
- MPESA
- AIRTEL MONEY
- EQUITEL
Request Parameters
In addition to the Standard request headers, the body of the request should contain the following fields:
Body Parameters
FIELD
DESCRIPTION
MerchantID
The content type of the payload: application/json
initiatorName
The First and Last Name of the Initiator in one string. ie. John Doe
initiatorCountry
The country the initiator is currently based in. ie. Germany
destinationPhone
Phone Number of the Recipient beginning with 07. Must be 10 Digits. Eg Kemru Technologies
amount
Amount that the recipient is expected to receive. ie 1500
channel
The channel the payment will be made from. It can either be the following: MPESA, AIRTEL, EQUITEL
signature
A HMAC SHA-256 signature to proof that the request is coming from the Merchant. Build a string of
concatenated values of the request fields. In this case, use the following order:
amount+phone+InitiatorName+InitiatorCountry+channel+MerchantID
Example Concatenated String:
1500 +254739117883 John DoeGermanyMPESAkemrut
The resulting string is then signed with the Security Key
provided/generated upon registration.
Sample Signature generated from the above Concatenated String:
9447d0ea436cdddd756132c46136a1ecf6d511263669014c212b9db6f57d79b6
Example Request:
POST http://sandbox.kemrut.com:3030/billing/v3/mobile-payout/create HTTP/1.1
Host: {GatewayBaseURL}
apiKey: {api-key}
Content-Type: application/json
{
"MerchantID":"kemrut",
"source":
{
"initiatorName":"John Doe",
"initiatorCountry": "Germany"
},
"destination":
{
"destinationPhone":"+254739117883",
"amount": "1500",
"channel":"MPESA"
},
"signature":"9447d0ea436cdddd75614c212b9db6f57d79b6"
}
Sample Response
{
"status": "Pending",
"status_code": "200",
"merchant_reference": "KT677833",
"transactiontxt": "Request accepted for processing!"
}
Note
For possible errors and solutions, refer to the Error section.
Once the request has been posted, we shall send an IPN/Callback to the registered URL with the format below.
Example Success IPN/Callback
{
"category": "MobilePayout",
"source": "+254739117883",
"destination": "+254739117883",
"MerchantID": "89",
"details":{
"biller_Receipt": "WSA2639191930300",
"Telco Reference": "RA1388393",
"CustomerName": ""
},
"requestMetadata": {},
"status": "Success",
"status_code": "0000",
"message": "Your request has been processed successfully.",
"transactionDate": "23-09-2023 11.20am",
"transactionRef": "KYA1234219488",
"Amount": "100"
}
B. BANK PAYOUT API
This API allows transfer of funds from your Payment wallet to Bank accounts within Kenya.
Request Parameters
In addition to the Standard request headers, the body of the request should contain the following fields:
Body Parameters
FIELD
DESCRIPTION
MerchantID
This identifies the Merchant making use of the Payment and Billing platform.
initiatorName
The First and Last Name of the Initiator in one string. ie John Doe
initiatorCountry
The country the initiator is currently based in. ie. Germany
name
The First and Last Name of the associated with the Bank Account in one string. eg Harry Kessy
accountNumber
Bank Account Number. eg 2042581154
phoneNumber
Phone Number of the Recipient beginning with 07. Must be 10 Digits. Eg +254739117883
amount
Amount that the recipient is expected to receive. ie 1500
bankCode
3-Digit code for the Bank, well listed in the Bank Codes Section below. eg 101
signature
A HMAC SHA-256 signature to proof that the request is coming from the Merchant. Build a string of
concatenated values of the request fields. In this case, use the following order:
amount+accountNumber+phoneNumber+bankCode+InitiatorName+InitiatorCountry+MerchantID
Example Concatenated String:
15002042581154+254739117883101John DoeGermanykemrut
The resulting string is then signed with the Security Key
provided/generated upon registration.
Sample Signature generated from the above Concatenated String:
9447d0ea436cdddd756132c46136a1ecf6d511263669014c212b9db6f57d79b6
Bank Codes
Bank Name
Kemru Technologies Code
Absa Bank
101
Co-operative Bank
102
Equity Bank(K)
103
Family Bank
104
KCB Bank Kenya (K)
105
Standard Chartered Bank (K)
106
ABC Bank
107
I & M Bank (K)
108
HF Group
109
Ecobank (K)
110
Habib Bank A.G. Zurich
111
NCBA Bank(K)
112
Stanbic Bank
113
Sidian Bank
114
Rafiki Microfinance Bank
115
Spire Bank
116
First Community Bank
117
Access Bank (K)
118
Diamond Trust Bank (K)
119
DIB Kenya Bank
120
Development Bank
121
Citibank N.A.
122
Bank of Baroda (K)
123
Bank of Africa (K)
124
Faulu Micro-Finance Bank
125
Credit Bank
126
Choice Microfinance Bank
127
Consolidated Bank
128
Caritas Microfinance Bank
129
Kenya Women Microfinance Bank
130
Mayfair Bank
131
Kingdom Bank
132
National Bank of Kenya
133
Middle East Bank (K)
134
Paramount Universal Bank
135
Prime Bank
136
Postbank
137
SBM Bank (K)
138
Victoria Commercial bank
139
UBA Kenya Bank
140
Salaam Microfinance Bank
141
M Oriental Bank (K)
142
Gulf African Bank
143
Guaranty Trust Bank (K)
144
Guardian Bank
145
Bank of India(K)
146
Example Request:
POST http://sandbox.kemrut.com:3030/billing/v3/bank-payout/create HTTP/1.1
Host: {GatewayBaseURL}
apiKey: {api-key}
Content-Type: application/json
{
"MerchantID":"kemrut",
"source":
{
"initiatorName":"John Doe",
"initiatorCountry": "Germany"
},
"destination":
{
"name":"Harry Kessy",
"accountNumber":"2042581154",
"phoneNumber":"+254739117883",
"amount": "1500",
"bankCode":"101"
},
"signature":"d1c574dfa94e43f77f6d0c18d48c809466a8fde21fa6886ba2480d4952871d8f"
}
Sample Response
{
"status": "Pending",
"status_code": "200",
"merchant_reference": "KYAAPI677833",
"transactiontxt": "Request accepted for processing!"
}
Note
For possible errors and solutions, refer to the Error section.
Once the request has been posted, we shall send an IPN/Callback to the registered URL
C. PAYMENT COLLECTION API
i. Mobile Checkout
Mobile checkout API allows you to initiate a Consumer to Business transaction on a Mobile subscriber’s device. Once initiated, the Subscriber will only need to authorize the payment.
Request Parameters
In addition to the Standard request headers, the body of the request should contain the following fields:
Body Parameters
FIELD
DESCRIPTION
MerchantID
This identifies the Merchant making use of the Payment and Billing platform.
phoneNumber
Phone Number of the Recipient beginning with 07. Must be 10 Digits. Eg +254739117883
amount
Amount that the recipient is expected to receive. ie 1500
channel
The channel the payment will be made from. It can either be the following: MPESA, AIRTEL, EQUITEL
metadata
A map of any metadata you would like us to associate with the request. You can use this field to
pass Account details, Payment reasons, or any other details that will assist to process the payment.
-It will be included in the Instant Payment Notification once the subscriber completes the mobile
checkout request.
signature
A HMAC SHA-256 signature to proof that the request is coming from the Merchant. Build a string of
concatenated values of the request fields. In this case, use the following order:
amount+phoneNumber+channel+MerchantID
Example Concatenated String:
1500<>MPESAkemrut
The resulting string is then signed with the Security Key
provided/generated upon registration.
Sample Signature generated from the above Concatenated String:
9447d0ea436cdddd756132c46136a1ecf6d511263669014c212b9db6f57d79b6
Example Request:
POST http://sandbox.kemrut.com:3030/billing/v1/checkout/create HTTP/1.1
Host: {GatewayBaseURL}
apiKey: {api-key}
Content-Type: application/json
{
"MerchantID":"kemrut",
"phoneNumber":"+254739117883",
"amount": "1500",
"channel": "MPESA",
"metadata":{
"abc":"balloon",
},
"signature":"092f758dec7149cc4c4cd09e2122d10016d0e2f8e2aed5d0b8a0615982ed1428"
}
Sample Response
{
"status": "Pending",
"status_code": "200",
"merchant_reference": "KYAAPI677833",
"transactiontxt": "Request accepted for processing!"
}
Note
For possible errors and solutions, refer to the Error section.
Once the request has been posted, we shall send an IPN/Callback to the registered URL with the below format.
Example Success IPN/Callback
{
"category": "MpesaPayment",
"source": "+254739117883",
"Phone": "+254739117883",
"MerchantID": "kemrut",
"details":{
"one": "Biller Receipt No: RA124646488" ,
"two": "kemrut Reference: KYA193838833S"
},
"Status": "Success",
"status_code": "0000",
"message": "Your request has been processed successfully.",
"Posted_Time": "23-09-2023 11.20am",
"transactionRef": "KYA193838833S",
"Amount": "100"
}
D. UPI
This endpoint facilitates seamless money transfers between Saccos, banks, and fintech platforms, enabling secure and efficient transactions among various financial entities
Request Parameters
In addition to the Standard request headers, the body of the request should contain the following fields:
Body Parameters
FIELD
DESCRIPTION
sender_party
(Sender Account Number) - The account number of the sender.
recipient_party
(Recipient Account Number) - The account number of the recipient.
sender_channel
(Sender Account Code) - The code associated with the sender's account.
recipient_channel
(Recipient Account Code) - The code associated with the recipient's account.
sender_curr
The currency of the sender's account.
recipient_curr
The currency of the recipient's account.
amount
The amount to be transferred.
description
A brief description of the transaction.
Example Request:
POST http://sandbox.kemrut.com:3030/v1/transaction/transact-link
Host: {GatewayBaseURL}
apiKey: {api-key}
Content-Type: application/json
{
"data":{
"sender_party": "*****0001",
"recipient_party": "*****0002",:
"sender_channel": "112",
"recipient_channel": "103",
"sender_curr": "KSH",
"recipient_curr": "KSH",
"amount": "10",
"description": "Test"
}
}
Sample Response
{
"statuscode": 200,
"ref": "KUPI638346AB84",
"status": "Transfer of Ksh.1 from *****0001 to *****0002 is being processed. Kindly await confirmation message."
}
Account Codes
Prefix
Example
Bank
101
Fintech
201
Sacco
301
Note
For possible errors and solutions, refer to the Error section.
Once the request has been posted, we shall send an IPN/Callback to the registered URL with the format below.
E. B2B
i. Create B2B Transaction
This endpoint allows you to create a business-to-business (B2B) transaction for billing purposes.
Request Headers
apiKey: Your API Key
Request Parameters
In addition to the Standard request headers, the body of the request should contain the following fields:
Body Parameters
FIELD
DESCRIPTION
MerchantID
This identifies the Merchant making use of the Payment and Billing platform.
channel
The channel through which the transaction is being processed.
resultUrl
The URL to which the transaction result will be sent asynchronously.
destination
The details of the destination account for the transaction.
shortCode
The destination shortcode.
identifier
The destination account number.
amount
The amount of the transaction.
remarks
Any remarks or notes for the transaction.
signature
A HMAC SHA-256 signature to proof that the request is coming from the Merchant. Build a string of
concatenated values of the request fields. In this case, use the following order:
MerchantID + channel + shortCode + identifier + amount
Sample Signature generated from the above Concatenated String:
9447d0ea436cdddd756132c46136a1ecf6d511263669014c212b9db6f57d79b6
Example Request:
POST http://sandbox.kemrut.com:3030/billing/v3/b2b/create HTTP/1.1
Host: {GatewayBaseURL}
apiKey: {api-key}
Content-Type: application/json
{
"MerchantID":"kemrut",
"channel":"BusinessPayBill",
"resultUrl": "",
"destination":{
"shortCode":"4079491",
"identifier":"+254739117883",
"amount":"5",
"remarks":"Testing",
},
"signature":"092f758dec7149cc4c4cd09e2122d10016d0e2f8e2aed5d0b8a0615982ed1428"
}
Sample Response
{
"status": "Success",
"status_code": "1100",
"merchant_reference": "KYAAPI677833",
"transactiontxt": "Request accepted for processing!"
}
Note
For possible errors and solutions, refer to the Error section.
Once the request has been posted, we shall send an IPN/Callback to the registered URL with the below format.
UTILITY API
Vend Utility services through your Platform.
A. AIRTIME API
This API allows the disbursement of Pinless Airtime from your Payment Wallet to Mobile subscribers with the following
networks.
- SAFARICOM
- AIRTEL
- TELKOM
- EQUITEL
- FAIBA
- FAIBA BUNDLES
Request Parameters
In addition to the Standard request headers, the body of the request should contain the following fields:
Body Parameters
FIELD
DESCRIPTION
MerchantID
This identifies the Merchant making use of the Payment and Billing platform.
phone
Phone Number of the Recipient beginning with 07. Must be 10 Digits. Eg +254739117883
amount
Amount that the recipient is expected to receive. ie 1500
productCode
The package selected for FAIBA BUNDLES.Refer Faiba bundle packages below. ie DAILY_DATA_225MB
telco
The channel the payment will be made from. It can either be the following:
SAFARICOM, AIRTEL, EQUITEL, TELKOM, FAIBA, FAIBA_B
initiatorPhone
This is the initiator’s Phone number attached along the transaction for record purposes.
signature
A HMAC SHA-256 signature to proof that the request is coming from the Merchant. Build a string of
concatenated values of the request fields. In this case, use the following order:
amount+phone+telco+initiatorPhone+MerchantID
Example Concatenated String:
1500+254739117883SAFARICOM+254739117883kemrut
The resulting string is then signed with the Security Key
provided/generated upon registration.
Sample Signature generated from the above Concatenated String:
092f758dec7149cc4c4cd09e2122d10016d0e2f8e2aed5d0b8a0615982ed1428
Example Request:
POST http://sandbox.+254739117883:3030/billing/v1/airtime/create HTTP/1.1
Host: {GatewayBaseURL}
apiKey: {api-key}
Content-Type: application/json
{
"MerchantID":"kemrut",
"phone":"+254739117883",
"amount": "1500",
"telco": "SAFARICOM",
"initiatorPhone": "+254739117883",
"signature":"092f758dec7149cc4c4cd09e2122d10016d0e2f8e2aed5d0b8a0615982ed1428"
}
Sample Response
{
"status": "Success",
"status_code": "0000",
"merchant_reference": "KYAAPI677833",
"transactiontxt": "Your request has been posted successfully!"
}
Note
For possible errors and solutions, refer to the Error section.
Once the request has been posted, we shall send an IPN/Callback to the registered URL
Bundle
Validity
price
Product Code
Autorenewal codes
100MB
1 day
10.00
DAILY_DATA_100MB
DAILY_DATA_AUTO_100MB
225MB
1 day
20.00
DAILY_DATA_225MB
DAILY_DATA_AUTO_225MB
1GB
1 day
50.00
DailyData1GB
N/A
2.5GB
3 day
100.00
3_DAYS_DATA_2.5GB
N/A
8GB
7 day
300.00
WeeklyData8GB
N/A
15GB
10 days
500.00
10_DAY_DATA_15GB
N/A
30GB
30 days
1,000.00
MONTHLY_DATA_30GB
MONTHLY_DATA_AUTO_30GB
65GB
30 days
2,000.00
MONTHLY_DATA_65GB
MONTHLY_DATA_AUTO_65GB
100GB
60 days
3,000.00
60_DAY_DATA_100GB
60_DAY_DATA_AUTO_100GB
140GB
60 days
4,000.00
60_DAY_DATA_140GB
60_DAY_DATA_AUTO_140GB
225GB
90 days
6,000.00
90_DAY_DATA_225GB
90_DAY_DATA_AUTO_225GB
Plan
Minutes
SMS
Data (GB)
Validity
Price
Product Code
Chui
300
100
5
30 days
500.00
CHUI_DATA_5GB
Kifaru
500
100
7
30 days
700.00
KIFARU_DATA_7GB
Ndovu
700
100
10
30 days
1,000.00
NDOVU_DATA_10GB
Simba
1,500
100
20
30 days
2,000.00
SIMBA_DATA_20GB
B. PAY BILL API
This API allows supports the following Service Providers:
- Kenya Power (Both Prepaid and Postpaid)
- Tv Subscriptions (DSTV, GOTV, ZUKU, STARTIMES)
- Water Service.
Request Parameters
In addition to the Standard request headers, the body of the request should contain the following fields:
Body Parameters
FIELD
DESCRIPTION
MerchantID
This identifies the Merchant making use of the Payment and Billing platform.
account
Account Number. Eg 0123456789
amount
Amount that the recipient is expected to receive. ie 1500
telco
The destination telco. The channels codes are attached below.
initiatorPhone
This is the initiator’s Phone number attached along the transaction for record purposes.
signature
A HMAC SHA-256 signature to proof that the request is coming from the Merchant. Build a string of
concatenated values of the request fields. In this case, use the following order:
amount+account+telco+initiatorPhone+MerchantID
Example Concatenated String:
1500012345678DSTV0715330000kemrut
The resulting string is then signed with the Security Key
provided/generated upon registration.
Sample Signature generated from the above Concatenated String:
092f758dec7149cc4c4cd09e2122d10016d0e2f8e2aed5d0b8a0615982ed1428
Example Request:
POST http://sandbox.kemrut.com:3030/billing/v1/bill/create HTTP/1.1
Host: {GatewayBaseURL}
apiKey: {api-key}
Content-Type: application/json
{
"MerchantID":"kemrut",
"phone":"+254739117883",
"amount": "1500",
"telco": "DSTV",
"initiatorPhone": "+254739117883",
"signature":"092f758dec7149cc4c4cd09e2122d10016d0e2f8e2aed5d0b8a0615982ed1428"
}
Sample Response
{
"status": "Success",
"status_code": "0000",
"transactionId": "KYAAPI677833",
"transactiontxt": "Your request has been posted successfully!"
}
Note
For possible errors and solutions, refer to the Error section.
Once the request has been posted, we shall send an IPN/Callback to the registered URL
DESTINATION CHANNEL CODES
TELCO
CHANNEL CODE
Tv Subscription
GOTV | DSTV | ZUKU | STARTIMES
Water Service
NAIROBI_WTR
C. VOUCHER/PIN AIRTIME API
This API allows the disbursement of Pin/voucher Airtime from your Payment Wallet to
Mobile subscribers with the following networks.
- SAFARICOM
- AIRTEL
- TELKOM
Request Parameters
In addition to the Standard request headers, the body of the request should contain the following fields:
Body Parameters
FIELD
DESCRIPTION
MerchantID
This identifies the Merchant making use of the Payment and Billing platform.
phone
Phone Number of the Recipient beginning with 07. Must be 10 Digits. Eg +254739117883
amount
Amount that the recipient is expected to receive. ie 1500
telco
The destination telco. It can either be the following:SAFARICOM, AIRTEL, TELKOM
initiatorPhone
This is the initiator’s Phone number attached along the transaction for record purposes.
signature
A HMAC SHA-256 signature to proof that the request is coming from the Merchant. Build a string of
concatenated values of the request fields. In this case, use the following order:
amount+phone+telco+initiatorPhone+MerchantID
Example Concatenated String:
1500+254739117883SAFARICOM+2547391178830kemrut
The resulting string is then signed with the Security Key
provided/generated upon registration.
Sample Signature generated from the above Concatenated String:
092f758dec7149cc4c4cd09e2122d10016d0e2f8e2aed5d0b8a0615982ed1428
Example Request:
POST http://sandbox.kemrut:3030/billing/v1/pin-airtime/create HTTP/1.1
Host: : {GatewayBaseURL}
apiKey: {api-key}
Content-Type: application/json
{
"MerchantID":"kemrut",
"phone":"+254739117883",
"amount": "1500",
"telco": "SAFARICOM",
"initiatorPhone": "+254739117883",
"signature":"092f758dec7149cc4c4cd09e2122d10016d0e2f8e2aed5d0b8a0615982ed1428"
}
Sample Response Success
{
"status": "Success",
"status_code": "0000",
"transactionId": "KYAAPI677833",
"transactiontxt": "Your request has been posted successfully!"
}
Note
For possible errors and solutions, refer to the Error section.
Once the request has been posted, we shall send an IPN/Callback to the registered URL
SMS
This API enables you to send Bulk SMS messages, OTPs, and SMS services from your platform to mobile subscribers. It supports the following features:
- Bulk SMS delivery to multiple recipients
- One-Time Password (OTP) generation and delivery
- Customizable SMS services
Integrate this API to seamlessly incorporate SMS functionalities into your application or service.
Request Parameters
In addition to the Standard request headers, the body of the request should contain the following fields:
Body Parameters
FIELD
DESCRIPTION
MerchantID
This identifies the Merchant making use of the Payment and Billing platform.
phone
Phone Number of the Recipient beginning with 07. Must be 10 Digits. Eg +254739117883
otp
Auto-generated 4-digit code. Eg 4343
signature
A HMAC SHA-256 signature to proof that the request is coming from the Merchant. Build a string of
concatenated values of the request fields. In this case, use the following order:
phone+otp+MerchantID
Example Concatenated String:
+254739117883kemrut
The resulting string is then signed with the Security Key
provided/generated upon registration.
Sample Signature generated from the above Concatenated String:
092f758dec7149cc4c4cd09e2122d10016d0e2f8e2aed5d0b8a0615982ed1428
USSD
i. Handling a session
Handling a ussd session made to your Kemru Technologies service code is as easy as implementing a script on your web server that handles
A few things to note about USSD:
- This USSD system operates on a session-based model. Each request we send will include a session ID, which will persist until the session is finished.
- It's important to inform the Mobile Service Provider about the session's status.If the session is ongoing, please initiate your response with "CON." On the other hand, if this is the final response for the session, start your response with "END."
- If our script returns an HTTP error response (status code 40X) or an improperly formatted response that doesn't start with "CON" or "END," we will gracefully terminate the USSD session.
- To ensure smooth access to your USSD services, avoid using special characters in your USSD menu, as telecom companies may have difficulty rendering such content, potentially causing disruptions.
Request Parameters
In addition to the Standard request headers, the body of the request should contain the following fields:
Body Parameters:
FIELD
DESCRIPTION
sessionId
A unique value generated when the session starts and sent every time a mobile subscriber response has been received.
phoneNumber
A unique value generated when the session starts and sent every time a mobile subscriber response has been received.
networkCode
The telco of the phoneNumber interacting with your ussd application.
serviceCode
This is the USSD code assigned to your application
text
This shows the user input. It is an empty string in the first notification of a session. After that, it concatenates all the user input within the session with a * until the session ends.
Example Callback URL Response:
{
"sessionId":"8003850",
"serviceCode":"*860*30#",
"phoneNumber": "+254739117883",
"text": "*30*30*1",
}
Handling Session
"if (text == '')"
{
//this is the first request
//Note for the first request the text string will always be blank.
//Note how we start the response with CON
"response = `CON What would you like to check
1. My account
2. My phone number";
} "if (text == '*30*30*1')"{
// Business logic for first level response
"response = `CON Choose account information you want to view
1. Account number";
} "if (text == '*30*30*2')"{
// Business logic for first level response
// This is a terminal request. Note how we start the response with END
"response = `END Your phone number is ${phoneNumber}";
} "if (text == '*30*30*2')"{
// This is a second level response where the user selected 1 in the first instance
"const accountNumber = 'Kya234242'";
// This is a terminal request. Note how we start the response with END
" response" = "END Your account number is ${accountNumber}";
}
// Echo the response back to the API
" res.set('Content-Type: text/plain')";
" res.send(response)";
Note
For possible errors and solutions, refer to the Error section.
Once the request has been posted, we shall send an IPN/Callback to the registered URL
INSTANT PAYMENT NOTIFICATION
A notification is information sent to your application whenever we need to let you know that something/change has
occurred. For instance, when a payment has been initiated, the request is pending. Once the payment is fully
executed, we immediately send you the details of the transaction as POST variables to the callback URL you set on
your Application for a given product.
The Callback URL can be registered in two ways:
- Through API settings on the kemrut Merchant Dashboard.
- Through the API endpoint.
Note
Once the endpoint is registered, no further changes can be made using this endpoint. In case one needs the
callback changed, engage our Support team for assistance.
Callback URL Registration.
This request enables the registration of the Callback URL
Request Parameters
In addition to the Standard request headers, the body of the request should contain the following fields:
DESTINATION CHANNEL CODES
FIELD
DESCRIPTION
MerchantID
In addition to the Standard request headers, the body of the request should contain the following
fields:
callbackURL
HTTPS callback URL
signature
A HMAC SHA-256 signature to proof that the request is coming from the Merchant. Build a string of
concatenated values of the request fields with the following order: MerchantID The resulting string
is then signed with the Key Provided upon registration.
Example Request:
POST http://sandbox.kemrut.com.io:3030/billing/v1/callback-url/create HTTP/1.1
Host: : {GatewayBaseURL}
apiKey: {api-key}
Content-Type: application/json
{
"MerchantID":"kemrut",
“callbackURL”:”https://website.com/callback”,
"signature":"d1c574dfa94e43f77f6d0c18d48c809466a8fde21fa6886ba2480d4952871d8f"
}
Sample Response
{
"status": "Success",
"status_code": "0000",
"transactionId": "KYAAPI677833",
"transactiontxt": "Callback Updated!"
}
Note
For possible errors and solutions, refer to the Error section.
Once the request has been posted, we shall send an IPN/Callback to the registered URL
Once you receive the IPN, you will be expected to send back a JSON response that confirms that you have received the
IPN. Ensure to respond with status 200 and the below JSON body.
{
“status”:success”
}
APPENDIX
Errors and Possible solutions
Standard Errors across the platform.
CODE
DESCRIPTION
0000
Request processed sucessfully.
1100
Transaction created and pending processing.
1101
Invalid Merchant ID.
1102
Authentication failed.
1103
Forbidden access
1104
Signature Mismatch.
1105
Payment services unavailable.
1106
Airtime Service unavailable.
1107
Insufficient float balance.
1108
Missing parameter.
1109
Parameter validation error.
1201
Invalid Bank Code
5000
Unexpected error has occurred.
6001
Cannot register the URL
6002
Invalid URL format.
7001
Transaction not found.
8001
Invalid account number format.
8002
Invalid phone number format.
8003
Invalid Telco.
8004
Invalid amount format.
8005
Amount limit exceeded.
8006
Duplicate transmission.
9001
Invalid phone number format.
9002
Invalid transaction channel.
9003
Invalid amount format.
9004
Amount limit exceeded.
9005
Duplicate transmission