What's New
The most recent releases across the ProTax API platform — features, fixes, and improvements.
UPI Inter-Institutional Transfer
New POST /v1/transaction/transact-link endpoint for transfers between Banks (101+), Fintechs (201+), and Saccos (301+).
B2B Paybill API
Added POST /billing/v3/b2b/create supporting BusinessPayBill and BusinessBuyGoods channel types with HMAC-SHA256 signature verification.
Offline Mode flag
Any request body now accepts "offline_mode": true to queue the transaction during KRA/network outages.
Webhook retry logic
IPN callbacks now retry up to 5× with exponential backoff: 1 min → 5 min → 15 min → 1 hr → 6 hr.
Telco Check signature validation
Fixed edge case where prefix values starting with 01x were rejected with error 1104.
API base URL updated to v2
Production base URL changed from /api/v1 to /api/v2. v1 is deprecated and will be removed in July 2025. See Migration Guide.
Signature algorithm upgrade
All endpoints now require HMAC-SHA256 signatures. MD5-based signatures from v1 are no longer accepted.
Transaction Verification endpoint
New GET /transactions/{ref}/verify for programmatic confirmation of any transaction reference.
TLS 1.0 and 1.1 disabled
Only TLS 1.2+ is now accepted on all production endpoints. Sandbox continues to allow TLS 1.1 until June 2025.
Rate limit headers
All responses now include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.
Full Changelog
Every release across all versions of the ProTax API.
UPI Inter-Institutional Transfer
Banks, Fintechs, and Saccos can now transact via a unified /transact-link endpoint.
B2B Paybill API
Business-to-business payment via paybill or till number.
Offline Mode flag
Queue transactions automatically during outages.
IPN retry logic
5-attempt exponential backoff for failed callback deliveries.
Telco Check 01x prefix bug
Fixed false 1104 signature error on Safaricom 011x numbers.
Bank payout timeout handling
Requests no longer silently dropped when downstream bank times out.
API base URL → v2
All endpoints moved to /api/v2. v1 deprecated July 2025.
HMAC-SHA256 signatures required
MD5 signatures no longer accepted.
Transaction Verification endpoint
GET /transactions/{ref}/verify
TLS 1.0/1.1 disabled
Production endpoints now require TLS 1.2+.
Rate limit headers
All responses include X-RateLimit-* headers.
Webhook event subscriptions
Subscribe to payment.success, payment.failed, airtime.delivered, and more.
Faiba Bundle Packages API
Full data bundle vending for Faiba with 11 product codes including DAILY_DATA_225MB through 90_DAY_DATA_225GB.
Biometric Attendance API
Bulk (/api-biometric) and single (/api-single) attendance record endpoints for schools and enterprises.
Member management endpoints
/api-memberc and /api-members for partner-level member data access.
EQUITEL payout channel
Fixed intermittent 1105 error on Equitel mobile payout requests.
SMS / OTP delivery speed
OTP delivery now under 5 seconds across all Kenyan networks via new routing layer.
Bulk SMS endpoint
Send to multiple recipients in a single API call. Max 1,000 numbers per request.
DSTV subscription amount rounding
Fixed KES fractions causing 8004 on DSTV Compact and Compact Plus packages.
API key rotation
Dashboard now supports zero-downtime key rotation — generate a new key while the old one remains valid for 24 hours.
STARTIMES pay bill support
Added STARTIMES as a valid channel code in the Pay Bill API.
Bank payout processing time
Average bank transfer time reduced from 4–6 hours to under 90 minutes.
Duplicate transmission false positives
Fixed 8006 being incorrectly returned for sequential (non-duplicate) requests within 500ms.
Callback URL registration API
Register IPN endpoints programmatically via POST /billing/v1/callback-url/create.
Business verification endpoint
GET /api-confirm — look up any registered business by email, phone, or link.
IP allowlisting
Enterprise accounts can now restrict API access to specific IP ranges from the Dashboard.
NAIROBI_WTR water billing
Added Nairobi City Water & Sewerage Company as a supported Pay Bill channel.
USSD session stability
Session persistence improved — reduced dropped sessions on Airtel and Telkom networks.
MD5 signature support
MD5-based request signatures are deprecated and will be removed in v2.0 (Jan 2025). Migrate to HMAC-SHA256.
Initial public release
Mobile Wallet Payout, Bank Payout, Payment Collection, Airtime, Pay Bill, PIN Voucher, SMS, and USSD APIs.
Sandbox environment
Full sandbox at http://sandbox. mirroring all production endpoints.
46 Kenyan banks supported
Bank Payout covers all CBK-licensed commercial banks, microfinance institutions, and mortgage financiers.
Breaking Changes
A consolidated list of every breaking change across all API versions, with migration notes.
⚠️ Breaking changes require action in your integration. Check which versions you are on and follow the relevant migration steps.
v2.0 — January 2025
Base URL changed to /api/v2
Old: https:///api/v1/...
New: https:///api/v2/...
v1 is deprecated and will be removed 1 July 2025.
MD5 signatures removed — HMAC-SHA256 required
All requests must include a valid HMAC-SHA256 signature field. Requests with MD5 signatures return 1104 Signature Mismatch.
🔧 Migration
Replace: md5($payload . $secret)
With: hash_hmac('sha256', $payload, $secret)
Deprecations
Features and endpoints that are deprecated and scheduled for removal.
🚨 Deprecated features will be removed on their scheduled dates. Update your integration before the removal date to avoid service disruption.
Scheduled for removal
/api/v1 endpoints
Deprecated since v2.0 (Jan 2025). Removal date: 1 July 2025. Migrate to /api/v2. See Migration Guide.
MD5-based request signatures
Removed in v2.0 (Jan 2025). HMAC-SHA256 is now the only accepted signature algorithm.
transactiontxt field in responses
Deprecated since v1.9. Will be removed in v2.2. Use message instead.
v2.1 — April 2025
UPI transfers, B2B payments, offline mode, and webhook improvements.
UPI Inter-Institutional Transfer
Enables seamless KES transfers between Banks, Fintechs, and Saccos via POST /v1/transaction/transact-link. Sender and recipient channels are identified by numeric codes (Banks 101+, Fintechs 201+, Saccos 301+).
B2B Paybill API
New POST /billing/v3/b2b/create endpoint. Supports BusinessPayBill channel. Signature: MerchantID + channel + shortCode + identifier + amount.
Offline Mode
Pass "offline_mode": true in any request body to queue the transaction in case of network or downstream outage. The transaction is auto-retried on reconnection.
IPN retry with exponential backoff
Callbacks that fail now retry at 1 min, 5 min, 15 min, 1 hr, and 6 hr intervals instead of fixed 5-minute intervals.
Faiba bundle product codes
Added CHUI_DATA_5GB, KIFARU_DATA_7GB, NDOVU_DATA_10GB, and SIMBA_DATA_20GB combo plans including minutes and SMS.
Telco Check 01x prefix
Phone numbers starting with 011x (Safaricom) were being rejected with error 1104 — now resolved.
Bank payout silent timeout
Resolved issue where bank payout requests could silently time out and not trigger a callback. All timeouts now return 1105 and trigger the failure callback.
v2.0 — January 2025
Major release with breaking changes. HMAC-SHA256 required. New base URL. Transaction verification.
⚠️ This release contains breaking changes. See the Migration Guide before upgrading.
API base URL → /api/v2
v1 deprecated, removal date: 1 July 2025.
HMAC-SHA256 signatures required
MD5 no longer accepted. All integrations must use hash_hmac('sha256', $payload, $secret).
Transaction Verification API
GET /transactions/{ref}/verify — verify any transaction reference programmatically.
Webhook event subscriptions
payment.success, payment.failed, payment.reversed, checkout.initiated, airtime.delivered, sms.delivered.
TLS 1.0/1.1 disabled on production
Requires TLS 1.2+ on all live API calls.
Rate limit response headers
X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset now returned on every response.
v1.9 — October 2024
Faiba bundles, biometric attendance, and member management APIs.
Faiba Bundle Packages
11 data bundle product codes including daily, weekly, 3-day, monthly, 60-day, and 90-day packages.
Biometric Attendance API
Bulk and single biometric record retrieval for schools and enterprise HR systems.
Member management endpoints
/api-memberc (single) and /api-members (bulk) with UID-based lookup.
EQUITEL payout intermittent errors
Resolved 1105 false-positive on valid EQUITEL payout requests.
transactiontxt response field
Use message instead. transactiontxt will be removed in v2.2.
v1.8 — July 2024
Faster OTP delivery, bulk SMS, and API key rotation.
OTP delivery under 5 seconds
New routing layer cuts SMS delivery to under 5s across Safaricom, Airtel, and Telkom.
Bulk SMS endpoint
Up to 1,000 recipients per request.
DSTV amount rounding error
Fixed 8004 on DSTV Compact/Compact Plus package amounts.
Zero-downtime API key rotation
New key is valid immediately; old key stays active for 24 hours to allow gradual rollover.
v1.7 — April 2024
STARTIMES Pay Bill
Added as a supported channel in the Pay Bill API.
Bank transfer processing time
Reduced from 4–6 hours to under 90 minutes.
Duplicate transmission false positives
Sequential requests within 500ms no longer trigger 8006.
v1.6 — January 2024
Callback URL registration API
Register and update IPN endpoints programmatically.
Business verification endpoint
Look up any registered merchant by email, phone, or link via GET /api-confirm.
IP allowlisting for enterprise accounts
Restrict API access to specific IP ranges from the merchant Dashboard.
v1.5 — October 2023
NAIROBI_WTR water billing
Nairobi City Water & Sewerage Company added as Pay Bill channel.
USSD session stability
Reduced session drops on Airtel and Telkom networks.
MD5 signatures
Will be removed in v2.0. Migrate to HMAC-SHA256 now.
v1.0 — July 2023
Initial public release of the ProTax API platform.
Mobile Wallet Payout
MPESA, AIRTEL MONEY, and EQUITEL payouts from your payment wallet.
Bank Payout
46 Kenyan banks supported via a single endpoint.
Payment Collection (STK Push)
Mobile checkout for MPESA, AIRTEL, and EQUITEL.
Airtime API
Pinless airtime for SAFARICOM, AIRTEL, TELKOM, EQUITEL, and FAIBA.
Pay Bill API
Kenya Power, DSTV, GOTV, and ZUKU TV subscriptions.
PIN Voucher Airtime
Voucher-based airtime for SAFARICOM, AIRTEL, and TELKOM.
SMS / OTP API
Bulk SMS and OTP delivery.
USSD Framework
Session-based USSD with CON/END response handling.
Sandbox environment
Full sandbox mirroring all production endpoints at http://sandbox..
Migration Guide
Step-by-step instructions for upgrading between major API versions.
v1 → v2 Migration
⚠️ v1 is deprecated. Removal date: 1 July 2025.
1. Update the base URL
🔧 Change required
Old: https:///api/v1/
New: https:///api/v2/
2. Update signature generation
🔧 Change required in all languages
PHP — Before: md5($payload . $secret)
PHP — After: hash_hmac('sha256', $payload, $secret)
Node.js — Before: crypto.createHash('md5').update(payload+secret).digest('hex')
Node.js — After: crypto.createHmac('sha256', secret).update(payload).digest('hex')
Python — Before: hashlib.md5((payload+secret).encode()).hexdigest()
Python — After: hmac.new(secret.encode(), payload.encode(), hashlib.sha256).hexdigest()
3. Update TLS configuration
Ensure your HTTP client supports TLS 1.2 or higher. Most modern libraries (curl 7.52+, Node 12+, Python 3.6+) support this by default.
4. Handle new response headers
v2 responses include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. These are optional to consume but should not cause errors if your client receives unexpected headers.
5. Replace deprecated fields
🔧 Response field change
Old: transactiontxt
New: message
Both are returned in v1.9–v2.1. transactiontxt will be removed in v2.2.
✅ Once you've made these changes, your integration is fully v2 compatible. Test in the sandbox first before switching production keys.
Versioning Policy
How ProTax manages API versions, deprecations, and backwards compatibility.
Version types
- Major versions (e.g. v1 → v2) — contain breaking changes. Minimum 6 months notice before deprecation, minimum 12 months before removal.
- Minor versions (e.g. v2.0 → v2.1) — new features, fully backwards compatible. No action required.
- Patch versions — bug fixes and security patches. Fully backwards compatible.
Deprecation process
- Deprecated features are announced in the changelog and via email to registered developers.
- Deprecated endpoints continue to work until the removal date.
- The
DeprecationandSunsetresponse headers are added to deprecated endpoints.
Support windows
| Version | Released | Deprecated | Removal |
|---|---|---|---|
| v2 (current) | Jan 2025 | — | — |
| v1 | Jul 2023 | Jan 2025 | 1 Jul 2025 |