Getting Started

Kemru Technologies API is engineered to perform multiple complex functions through simple endpoints — from Mobile Wallet Payouts and Bank Transfers to Utility Vending across Kenyan Telcos and digital service providers.

RESTful API

Standard JSON over HTTPS. OpenAPI-compatible with clear versioning.

HMAC-SHA256

Every request is signed. Replay attacks and tampering are prevented.

Webhook Callbacks

Real-time IPN notifications on every transaction status change.

Offline Mode

Queue transactions during outages — auto-submitted on reconnect.

Reverse Transactions

Initiate reversal or credit-back on eligible completed transactions.

Verification API

Verify any transaction reference programmatically at any time.

Need help? Email apisupport@kemrut.com or use the live chat on your dashboard. New here? Jump to Authentication →

Changelog

Apr 2025

New v2.0 — UPI & B2B APIs

Added inter-institutional UPI transfer, B2B paybill endpoint, and global Offline Mode support.

Jan 2025

Update Webhook retry logic

Callbacks now retry up to 5× with exponential backoff on non-200 responses.

Oct 2024

New Faiba Bundles & Biometrics API

Added Faiba data bundle vending and biometric attendance tracking endpoints.

Jul 2024

Update SMS / OTP speed improvement

OTP delivery now under 5 seconds across all Kenyan networks.

Rate Limits

Limits apply per API key per minute. Exceeding returns HTTP 429.

Sandbox

60

req/min · 5,000/day

Starter

120

req/min · 50,000/day

Business

300

req/min · Unlimited

Enterprise

∞

Custom SLA — contact us

Never commit your API key to source control. Store it in environment variables or a secrets manager. All production endpoints require HTTPS.

Environments

Environment	Base URL	Notes
Sandbox	`http://sandbox.kemrut.com:3030`	HTTP allowed. For development only.
Production	`https://kemrut.com/api/v2`	HTTPS required. Live transactions.

Authentication

All requests require your apiKey header and a per-request HMAC-SHA256 signature.

Header	Description
`Content-Type`	Always `application/json`
`apiKey`	Generated upon registration in your merchant dashboard.

Generating the Signature

javascript

const crypto = require('crypto');
const secret = 'YOUR_SECRET_KEY';
// Concatenate fields in the documented order, then sign
const payload = amount + phone + initiatorName + initiatorCountry + channel + MerchantID;
const signature = crypto.createHmac('sha256', secret).update(payload).digest('hex');

Check Account Balance

POST

/api-link

Check your merchant wallet balance.

Field	Description
`MerchantID`	Your merchant identifier.
`signature`	HMAC-SHA256 of `MerchantID`.

User & Member APIs

Single User — GET /api-user

GET

/api-user

Retrieve a single user by access token + identifier.

json — response

[
  { "access_token": "301-565-660-353/1953" },
  { "id":"717445","firstname":"Verah","lastname":"Okoth",
    "phone":"+254739117883","email":"system@kemrut.com","country":"Kenya" }
]

All Users — GET /api-biometric

GET

/api-biometric

Returns all users for the merchant partner.

Single Member — GET /api-memberc

GET

/api-memberc

Retrieve a member by national ID, passport, or UID.

json — response

{
  "status_code":"200","id":"20170","partnerid":"19",
  "emp_name":"SAGINI OBED","phone":"+254739117883",
  "gender":"Male","title":"Student","bal":"16","SmsStatus":"Sent"
}

All Members — GET /api-biometric

GET

/api-biometric

Returns all members. Requires access token only.

Bulk Biometric Attendance — GET /api-biometric

GET

/api-biometric

Returns attendance records for all enrolled individuals.

Single Biometric Attendance — GET /api-single

GET

/api-single

Attendance record for a specific UID (student/employee).

json — request body

{ "access_token": "301-565-660-353/1953", "uid": "12345" }

Payment APIs

A. Mobile Wallet Payout

Send from your Payment Wallet to MPESA, AIRTEL MONEY, or EQUITEL subscribers.

POST

/billing/v3/mobile-payout/create

Initiate mobile wallet disbursement.

Field	Description
`MerchantID`	Your merchant identifier.
`initiatorName`	Full name. e.g. `John Doe`
`initiatorCountry`	e.g. `Kenya`
`destinationPhone`	10-digit number starting with 07.
`amount`	Amount in KES. e.g. `1500`
`channel`	`MPESA` \| `AIRTEL` \| `EQUITEL`
`signature`	HMAC-SHA256 of `amount+phone+InitiatorName+InitiatorCountry+channel+MerchantID`

json — request

POST http://sandbox.kemrut.com:3030/billing/v3/mobile-payout/create
apiKey: {api-key}   Content-Type: application/json

{
  "MerchantID": "kemrut",
  "source": { "initiatorName": "John Doe", "initiatorCountry": "Kenya" },
  "destination": { "destinationPhone": "+254739117883", "amount": "1500", "channel": "MPESA" },
  "signature": "9447d0ea436cdddd75614c212b9db6f57d79b6"
}

json — response

{ "status":"Pending","status_code":"200","merchant_reference":"KT677833","transactiontxt":"Request accepted for processing!" }

B. Bank Payout

Transfer to any Kenyan bank. Signature: amount+accountNumber+phoneNumber+bankCode+InitiatorName+InitiatorCountry+MerchantID

POST

/billing/v3/bank-payout/create

Initiate bank transfer.

Bank	Code	Bank	Code
Absa Bank	101	Co-operative Bank	102
Equity Bank	103	Family Bank	104
KCB Bank Kenya	105	Standard Chartered	106
I & M Bank	108	NCBA Bank	112
Stanbic Bank	113	National Bank	133
DTB Kenya	119	Gulf African Bank	143
Bank of Africa	124	Bank of India	146

C. Payment Collection — Mobile Checkout

POST

/billing/v1/checkout/create

Trigger STK push to subscriber's device.

json — request

{
  "MerchantID":"kemrut","phoneNumber":"+254739117883",
  "amount":"1500","channel":"MPESA",
  "metadata":{"reason":"Invoice #1234"},
  "signature":"092f758dec7149cc4c4cd09e2122d10016..."
}

D. UPI — Inter-Institutional Transfer

Transfer between Saccos, Banks, and Fintechs using account codes (Bank: 101+, Fintech: 201+, Sacco: 301+).

POST

/v1/transaction/transact-link

UPI transfer between institutions.

E. B2B — Business Paybill

POST

/billing/v3/b2b/create

B2B paybill / till transfer.

json — request

{
  "MerchantID":"kemrut","channel":"BusinessPayBill","resultUrl":"https://yoursite.com/cb",
  "destination":{"shortCode":"4079491","identifier":"+254739117883","amount":"5000","remarks":"Settlement"},
  "signature":"092f758dec7149..."
}

Utility APIs

A. Airtime — Pinless

POST

/billing/v1/airtime/create

Disburse pinless airtime.

json — request

{ "MerchantID":"kemrut","phone":"+254739117883","amount":"100","telco":"SAFARICOM","initiatorPhone":"+254739117883","signature":"..." }

Bundle	Validity	Price (KES)	Product Code
100MB	1 day	10	`DAILY_DATA_100MB`
225MB	1 day	20	`DAILY_DATA_225MB`
1GB	1 day	50	`DailyData1GB`
8GB	7 days	300	`WeeklyData8GB`
30GB	30 days	1,000	`MONTHLY_DATA_30GB`
65GB	30 days	2,000	`MONTHLY_DATA_65GB`
100GB	60 days	3,000	`60_DAY_DATA_100GB`
225GB	90 days	6,000	`90_DAY_DATA_225GB`

B. Pay Bill — Utilities & TV

Kenya Power, TV Subscriptions (DSTV, GOTV, ZUKU, STARTIMES), Water Services.

POST

/billing/v1/bill/create

Pay utility bills and subscriptions.

Service	Channel Code
TV Subscription	`GOTV` \| `DSTV` \| `ZUKU` \| `STARTIMES`
Water	`NAIROBI_WTR`

C. PIN Voucher Airtime

PIN-based airtime for SAFARICOM, AIRTEL, TELKOM.

POST

/billing/v1/pin-airtime/create

Disburse PIN/voucher airtime.

SMS / OTP

Send Bulk SMS, OTPs, and custom alerts to any Kenyan mobile subscriber.

POST

/billing/v1/sms/send

Send SMS or OTP.

Field	Description
`MerchantID`	Your merchant identifier.
`phone`	10-digit number starting with 07.
`otp`	Auto-generated 4–6 digit OTP.
`signature`	HMAC-SHA256 of `phone+otp+MerchantID`

json

{ "MerchantID":"kemrut","phone":"+254739117883","otp":"4823","signature":"..." }

USSD

Handling a Session

Start ongoing responses with CON. Start final responses with END. Respond within 5 seconds. Avoid special characters.

Field	Description
`sessionId`	Unique session — persists until END.
`phoneNumber`	Subscriber's phone number.
`networkCode`	Subscriber's telco.
`serviceCode`	Your assigned USSD code e.g. `86030#`
`text`	Empty on first request; inputs concatenated with `*`.

node.js

app.post('/ussd', (req, res) => {
  const { phoneNumber, text } = req.body;
  let r = '';
  if (text === '') {
    r = 'CON Welcome to Kemru Technologies\n1. Check Balance\n2. Buy Airtime\n3. My Account';
  } else if (text === '1') {
    r = 'END Your balance is KES 1,245.00';
  } else if (text === '2') {
    r = 'CON Enter amount (KES):';
  } else {
    r = 'END Invalid selection. Please try again.';
  }
  res.set('Content-Type', 'text/plain').send(r);
});

Callback (IPN)

A POST is sent to your registered URL whenever a transaction status changes.

Callback URLs are registered once per environment. To update, contact apisupport@kemrut.com.

POST

/billing/v1/callback-url/create

Register your IPN endpoint.

json — register

{ "MerchantID":"kemrut","callbackURL":"https://yoursite.com/ipn","signature":"d1c574dfa94e43f..." }

IPN Payload

json — incoming IPN

{
  "category":"MobilePayout","source":"+254739117883","destination":"+254739117883",
  "MerchantID":"89",
  "details":{"biller_Receipt":"WSA2639191930300","Telco_Reference":"RA1388393"},
  "status":"Success","status_code":"0000",
  "message":"Your request has been processed successfully.",
  "transactionDate":"2025-04-11 11:20AM","transactionRef":"KYA1234219488","Amount":"1500"
}

Respond with HTTP 200 and body {"status":"success"} within 10 seconds. Failed deliveries are retried 5× with exponential backoff.

Webhooks

Subscribe to specific events for granular, push-based notifications.

Event	Triggered when
`payment.success`	Transaction fully processed and confirmed.
`payment.failed`	Transaction failed after all retries.
`payment.reversed`	A reversal completed successfully.
`checkout.initiated`	STK push sent to subscriber's device.
`airtime.delivered`	Airtime credited to recipient.
`sms.delivered`	SMS/OTP confirmed delivered by network.

Each webhook includes an X-Kemru Technologies-Signature header. Verify it with your webhook secret to prevent spoofing.

Offline Mode

Submit transactions during outages. They are queued and auto-submitted when connectivity is restored.

Feature	Online Mode	Offline Mode
Requires internet	Yes	No — queued
Response time	~1–3 seconds	On reconnection
Provisional receipt	—	Yes
Rejection feedback	Immediate	Deferred via callback

Enable by adding "offline_mode": true to any request body, or toggle globally in your Merchant Dashboard.

Transaction Verification

Verify any transaction reference via API, merchant portal, or programmatic lookup.

GET

/transactions/{ref}/verify

Check transaction status and authenticity.

Status Reference

Success Processing Pending Retry Failed Queued (Offline)

Business Registration

URL requirements: Production URLs must be HTTPS. Avoid exec, cmd, sql in URLs. No public tunnels (ngrok, requestbin). Add CNAME virtual.kemrut.com to your DNS for subdomain mapping.

json — register & confirm

// Register
POST /api-business
{ "name":"Kemru Technologies","contact":"+254739117883","link":"developer.kemrut.com","email":"system@kemrut.com" }

// Confirm/lookup
GET /api-confirm
{ "search":"system@kemrut.com" }

Telco Check

POST

/api-telco-check

Identify the telco for a given phone prefix.

json

{ "MerchantID": "", "prefix": "722", "signature": "" }

Error Codes

HTTP	Meaning
`200`	Success
`400`	Bad Request — invalid payload or missing fields
`401`	Unauthorized — missing or invalid apiKey
`403`	Forbidden — key lacks permission
`429`	Rate limit exceeded
`500`	Internal server error

Platform Codes

Code	Description
`0000`	Request processed successfully.
`1100`	Transaction created — 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 — contact support with transaction ref.
`6001`	Cannot register URL.
`6002`	Invalid URL format.
`7001`	Transaction not found.
`8002`	Invalid phone number format.
`8003`	Invalid Telco.
`8004`	Invalid amount format.
`8005`	Amount limit exceeded.
`8006`	Duplicate transmission.
`9002`	Invalid transaction channel.
`9004`	Amount limit exceeded.
`9005`	Duplicate transmission.

Welcome back

Sandbox Environment

Getting Started

RESTful API

HMAC-SHA256

Webhook Callbacks

Offline Mode

Reverse Transactions

Verification API

Changelog

New v2.0 — UPI & B2B APIs

Update Webhook retry logic

New Faiba Bundles & Biometrics API

Update SMS / OTP speed improvement

Rate Limits

Environments

Authentication

Generating the Signature

Check Account Balance

User & Member APIs

Single User — GET /api-user

All Users — GET /api-biometric

Single Member — GET /api-memberc

All Members — GET /api-biometric

Bulk Biometric Attendance — GET /api-biometric

Single Biometric Attendance — GET /api-single

Payment APIs

A. Mobile Wallet Payout

B. Bank Payout

C. Payment Collection — Mobile Checkout

D. UPI — Inter-Institutional Transfer

E. B2B — Business Paybill

Utility APIs

A. Airtime — Pinless

B. Pay Bill — Utilities & TV

C. PIN Voucher Airtime

SMS / OTP

USSD

Handling a Session

Callback (IPN)

IPN Payload

Webhooks

Offline Mode

Transaction Verification

Status Reference

Business Registration

Telco Check

Error Codes

Platform Codes