Under Section 23A of Kenya's Tax Procedures Act, every registered business operating in Kenya — whether an online store, a SaaS provider, a specialized clinic, or an industrial distributor — is required to issue electronic tax invoices validated in real-time through the Kenya Revenue Authority's eTIMS (Electronic Tax Invoice Management System). Furthermore, since early 2024, corporate buyers in Kenya cannot claim any business expense as a tax-deductible deduction unless backed by a valid, machine-readable eTIMS invoice.
If your e-commerce website or web application issues traditional PDF receipts or standard WooCommerce invoices without real-time KRA signing, your corporate clients will take their business elsewhere, and your company faces severe audit penalties. Here is how a production-grade System-to-System eTIMS integration works, the architectural differences between OSCU and VSCU, and the step-by-step technical implementation.
OSCU vs. VSCU: choosing your integration architecture
When connecting your website, ERP, or point-of-sale system directly to KRA's servers via API, the tax authority requires you to choose between two architectural conduits: OSCU and VSCU. The primary difference is where the fiscal signing takes place and how your system handles network latency:
| Architectural Factor | OSCU (Online Sales Control Unit) | VSCU (Virtual Sales Control Unit) |
|---|---|---|
| Hosting Location | KRA's central cloud infrastructure (etims-api.kra.go.ke) | Local or private cloud server running KRA's Java daemon (etims-vscu.jar) |
| Best Fit For | Cloud e-commerce storefronts, web applications, SaaS platforms | High-volume wholesale ERPs, multi-branch supermarkets, local POS setups |
| Internet Dependency | Requires continuous 100% internet connectivity during checkout | Signs receipts locally; queues and syncs batches to KRA asynchronously |
| Infrastructure Overhead | Zero local server management; direct HTTPS REST calls | You must keep the Java background service running on local port 8088 |
For modern web applications and online stores, OSCU is the preferred modern choice because it requires no physical server hardware. However, your checkout architecture must be engineered to handle occasional KRA API latency without abandoning the customer.
An e-commerce receipt without an eTIMS QR code and fiscal signature is not an invoice under Kenyan law. It is just an unverified slip.
The four technical steps of a live integration
A production-grade eTIMS system-to-system integration moves through four distinct operational phases:
- 1. Portal onboarding and sandbox credentials: Submit a system-to-system onboarding request through the eTIMS taxpayer portal (
etims.kra.go.ke) with your business KRA PIN and Tax Compliance Certificate (TCC). KRA assigns sandbox credentials, test branch identifiers (bhfId), and technical API documentation. - 2. Device initialization handshake: Before submitting any sales, your backend calls the initialization endpoint (such as
/selectInitOsdcInfo) passing your Taxpayer PIN, Branch ID, and Device Serial Number. KRA's system returns unique communication security keys (cmcKey) used to sign all subsequent payload transmissions. - 3. Master data code mapping: KRA requires standardized classification. Your product catalog must map directly to KRA's standard Item Classification Codes, Packaging Codes, and Unit of Measure dictionaries (e.g. pieces, kilograms, liters). If a customer purchases a product with an unmapped category code, KRA's validation will reject the entire payload.
- 4. Real-time sales invoice submission: When an order is completed, your backend formats the sales payload conforming to KRA's JSON schema (tax rates, VAT 16%, zero-rated items, discounts, buyer PIN, and line items). The API signs the invoice and returns a Fiscal Receipt Number, a Digital Signature Hash, and a Verification QR Code URL.
E-commerce checkout UX: handling B2B vs. B2C buyers
A common e-commerce pitfall is forcing walk-in consumers to provide their KRA PIN. Your checkout form should accommodate both customer profiles seamlessly:
- Retail B2C consumers: Individual walk-in shoppers typically do not need tax deductions. The eTIMS payload is submitted using a standard consumer profile, allowing fast mobile checkout via M-Pesa STK Push.
- Corporate B2B purchasers: Provide an optional toggle: *“Require a tax invoice for corporate deduction?”* with a field for their 11-character corporate KRA PIN (e.g.
P051XXXXXXX). Validate the PIN format in real-time before initiating payment. - Embedded QR Code receipts: Automatically render the KRA verification QR code directly onto the order confirmation screen and inside the downloadable PDF invoice sent via email.
Credit Notes and Order Cancellations
eTIMS compliance does not stop at sales. If a customer cancels an order or returns damaged goods, you cannot simply issue a database refund. Your system must trigger an eTIMS Credit Note API call referencing the original fiscal invoice number to adjust your declared VAT liability with KRA.
Direct custom integration vs. certified middleware
Building an OSCU API wrapper from scratch gives you total control, zero recurring third-party subscriptions, and zero vendor lock-in. However, it requires experienced software engineers who understand cryptographic payload signing and error handling. For businesses seeking turnkey solutions, certified local middleware platforms (such as DigiTax or Risiti) provide pre-built connectors for WooCommerce and Shopify in exchange for monthly subscription fees.
At Devaltech, we engineer native, direct-to-KRA system-to-system integrations for custom Next.js web applications, retail point-of-sale platforms, and e-commerce stores — without recurring middleman software fees. Read more about our Scale application tier or book a consultation to review your eTIMS compliance roadmap.