eTIMS integration: OSCU or VSCU, and what changes in your system

If your invoices come out of your own software, KRA’s eTIMS has to live inside that software. Re-keying sales into the eTIMS portal works for a few invoices a day. It does not work for a water company’s billing run or a school’s fee invoices, and it fails quietly the week someone is on leave.

Here is how KRA’s system-to-system integration works, how to choose between its two units, and what your system will need that it probably does not have yet.

Why it matters now

Under the Finance Act 2023, from January 2024 expenses not supported by an eTIMS invoice can be disallowed for income tax, with some exemptions. From January 2026, KRA validates the income and expenses in tax returns against eTIMS data.

Two consequences follow. Your sales invoices need to be in eTIMS for your customers to claim them. And the purchases you claim need eTIMS invoices from your suppliers. How the rules apply to your business is a question for your tax adviser; this note is about the engineering.

The routes into eTIMS

KRA offers several ways to issue eTIMS invoices:

• The online portal, for issuing invoices by hand.
• eTIMS Lite, which KRA designed for small and micro taxpayers not registered for VAT, on the web through eCitizen, by USSD on *222#, or through the mobile app.
• System-to-system integration, which connects your invoicing or ERP system to eTIMS through an API.

If you invoice from your own software at any real volume, the third route is the one that removes the double entry.

OSCU or VSCU

System-to-system integration runs through one of two units. In KRA’s words:

• OSCU (Online Sales Control Unit) is suitable for taxpayers whose invoicing is always online.
• VSCU (Virtual Sales Control Unit) is suitable for taxpayers undertaking bulk invoicing, including those who are not always online.

The practical question is how your invoices are produced. A web application issuing invoices one at a time, always connected, fits OSCU. A billing run that produces hundreds or thousands of invoices at once, or a system at a site with unreliable connectivity, points to VSCU.

Self-integration or a verified integrator

KRA allows both. A business can self-integrate, which means its own system goes through development, testing, vetting and certification. Or it can use a solution from a KRA-verified third-party integrator, which KRA lists on its website.

An off-the-shelf connector is the fast route when your accounting or ERP package already has one that fits. Self-integration suits a business whose invoicing lives in custom software, or whose billing does not fit the shape the connector expects.

How the process runs

KRA publishes the OSCU and VSCU specifications, a technical specification for the trader invoicing system, and a sandbox test environment. The work runs in this order:

1. Register for sandbox access and pick the unit.
2. Build the integration against the specification.
3. Test it in the sandbox until every invoice type and correction your business issues passes.
4. Go through KRA’s testing, vetting and certification.
5. Only then issue live invoices through the integrated system.

Budget for step 3 properly. The sandbox is where you discover which of your invoice types the integration did not account for.

What changes in your system

Integration is rarely just an API call bolted on at the end. Expect changes like these:

• Data you may not capture yet. Customer KRA PINs where required, and item and unit details in the form eTIMS expects, held against your products and services rather than typed per invoice.
• The invoice flow. An invoice is not final until it has its eTIMS record, and the details KRA returns need to be stored and printed on the invoice.
• Credit notes, not edits. A wrong invoice is corrected with a credit note against the original. Editing an issued invoice leaves your records and KRA’s disagreeing.
• Failure handling. When KRA or your connection is unavailable, invoices queue and retry, every one has a visible status, and a retry can never issue the same invoice twice.
• Reconciliation. The invoice, its KRA record and the payment that settles it should stay connected, so month end is one check, not three. The note on reconciling M-Pesa payments covers the payment side.

Before you start

Have these ready and the integration goes faster:

• How many invoices you issue, and whether they go out one at a time or in runs.
• Every invoice type you issue, including credit notes and any zero-rated or exempt items.
• Where customer and product data lives today, and how clean it is.
• Who in the business will own eTIMS errors when they happen.

If your invoicing system needs connecting and no connector fits, eTIMS integration work starts with a written plan: which unit, what changes in your invoicing flow, and what certification will need from you.