eTIMS Integration in Kenya: OSCU vs VSCU Checklist

eTIMS integration in Kenya is not simply a matter of sending an invoice to an API. The business system must create the right invoice data, follow the correct sales and adjustment workflows, cope with connectivity and validation failures, preserve a reliable audit trail, and reconcile what the business recorded with what reached the Kenya Revenue Authority (KRA).

KRA provides system-to-system integration for businesses that already use an invoicing, ERP, point-of-sale, or other business system. Its current guidance identifies two routes: the Online Sales Control Unit (OSCU) and the Virtual Sales Control Unit (VSCU). Choosing between them is an architecture decision tied to how your invoicing actually works.

When system-to-system integration is the right conversation

KRA offers several eTIMS solutions, including online, client, Lite, and system-to-system options. A direct integration is most relevant when a business already has a system that creates invoices and needs that system to connect to eTIMS without requiring staff to re-enter every transaction in a separate interface.

That does not mean every business needs an API project. First confirm the appropriate eTIMS solution through current KRA guidance. If direct integration is justified, define which system remains the operational source of truth, when an invoice becomes final, how the eTIMS response is stored, and how users resolve rejected, delayed, duplicated, cancelled, credited, or corrected transactions.

OSCU vs VSCU: the practical difference

This comparison is an implementation starting point, not a substitute for KRA's current OSCU and VSCU specifications. Confirm the applicable route, registration process, test requirements, interfaces and operational rules with KRA before committing to production architecture.

10-step eTIMS system-to-system implementation checklist

1. Confirm the taxpayer and transaction scope

Document the legal entity, KRA PIN, branches, invoice types, buyer information, goods or services, tax treatments, currencies, stock implications, credit notes, debit notes, cancellations and exceptional transactions. Kenya's Tax Procedures Act section 23A and the 2024 Electronic Tax Invoice Regulations set the legal foundation, but your actual obligations depend on the business and transaction context.

Have the taxpayer confirm the current requirements directly with KRA or a qualified tax adviser. A software team should translate an approved compliance position into system behaviour; it should not invent the tax position.

2. Choose self-integration or a verified third-party integrator

KRA states that a taxpayer with the necessary capacity can initiate self-integration, or the taxpayer can use a KRA-verified third-party integrator. The development, testing, vetting and certification process applies to the relevant integration route.

Rx Code Labs does not present itself as a KRA-certified integrator. We can help analyse an existing system, map workflows, prepare technical requirements, build business-system components, support testing, and coordinate with the taxpayer and an appropriately verified integrator where required. Always confirm a provider's current verification status through KRA.

3. Complete eTIMS registration and sandbox onboarding

KRA's onboarding guidance says a taxpayer should register for eTIMS and provide information about the nature of the business before installing or using an eTIMS solution. For system-to-system work, follow the current KRA portal instructions, required documentation, sandbox sign-up guide and applicable OSCU or VSCU specification.

Record who owns the taxpayer portal access, sandbox application, test credentials, production credentials, device or system registration, KRA correspondence, approvals and renewal or change procedures. These should not live only in one developer's inbox.

4. Define the invoice data contract

The 2024 Regulations require electronic tax invoices to contain prescribed information, including supplier PIN, issue date and time, serial number, buyer PIN where applicable, gross and tax amounts, item codes, descriptions, quantities, units of measure, tax rates, unique identifiers and a QR code. Section 23A of the Tax Procedures Act also specifies invoice information.

Map every required field to the source inside your ERP, POS, ecommerce platform or custom system. Identify missing data, invalid formats, inconsistent item codes, optional fields, rounding rules and ownership for corrections before building the connector. Data quality discovered during sandbox testing should become an operational cleanup task, not a hard-coded workaround.

5. Map the complete sales lifecycle

Do not design only the successful sale. Map quotation or order creation, invoice approval, transmission, response storage, receipt delivery, stock movement, payment, credit and debit notes, cancellation rules, refunds, rejected invoices and corrections. The Regulations require credit and debit notes to reference the original invoice.

If your payment flow uses M-PESA, keep payment confirmation and tax invoicing as connected but distinct processes. Our M-PESA integration guide explains the callback and reconciliation controls needed around the payment side.

6. Design for the chosen connectivity model

For OSCU, design what happens when the supposedly always-online environment experiences a timeout, service interruption or ambiguous result. The user must be able to see whether an invoice is pending, accepted, rejected or requires investigation without submitting duplicates.

For VSCU, define durable local recording, sequencing, batch preparation, connectivity recovery, transmission state and reconciliation according to the official specification. A queued transaction needs a unique identity and a traceable state transition from creation to final outcome.

7. Protect credentials and integration operations

Keep credentials and keys outside source code, restrict production access, separate sandbox and production configuration, rotate secrets when required, log administrative changes and redact sensitive values from application logs. Define who can retry, cancel, correct or resubmit a transaction and retain an audit trail of those actions.

Monitoring should detect sustained failures, growing queues, authentication problems, unexpected rejection patterns and reconciliation gaps without exposing taxpayer or customer information in alerts.

8. Test business scenarios, not only endpoints

Use the KRA sandbox and official test process. Build acceptance cases for valid invoices, missing buyer PIN where relevant, invalid item or tax data, duplicate submission attempts, network timeout, delayed response, credit note, debit note, cancelled order, branch or device differences, batch recovery and a production-like daily reconciliation.

Keep test evidence: input case, expected result, actual result, KRA response, defect, correction and retest approval. A single successful request does not establish production readiness.

9. Build daily reconciliation and support queues

Operations teams need a report that compares business-system invoices with eTIMS outcomes. It should identify accepted, pending, rejected, corrected and unresolved records, preserve the original transaction reference, and show who owns the next action.

Agree on cut-off times, ageing rules, escalation, evidence retention and sign-off. A hidden technical log is not a usable reconciliation process. Rx Code Labs' dashboard and workflow automation service covers the broader discipline of turning system events into actionable operational queues.

10. Plan controlled launch and change management

Use a documented production-readiness review covering approved scope, taxpayer onboarding, KRA testing or verification, credentials, data migration, user roles, monitoring, support, rollback or continuity procedures, reconciliation and training. Start with a controlled transaction set where practical, observe results, then expand.

KRA specifications and tax rules can change. Assign an owner to monitor official updates, assess their effect, test changes and deploy them safely. If the integration sits inside a broader ERP replacement or custom platform, review the discovery and lifecycle factors in our custom software cost guide for Kenya.

A sensible system boundary

A production design normally separates business rules from the external connector. The business application validates the order and invoice, a controlled integration component communicates through the approved route, and a durable transaction record stores the request identity, current state, response and reconciliation status. Users work from explicit states rather than guessing from a loading spinner.

That boundary makes it easier to test tax-invoice integration independently from checkout, inventory, accounting or customer communication while keeping the full transaction traceable. Rx Code Labs provides custom software development and web and mobile application development for organizations that need their operational system prepared for dependable integrations.

Frequently asked questions

Important: This article provides general technical planning information, not tax or legal advice. Confirm current requirements, specifications, verification status and taxpayer obligations directly with KRA and, where appropriate, a qualified tax or legal adviser.

Authoritative sources used

• Kenya Revenue Authority: eTIMS system-to-system integration
• Kenya Revenue Authority: eTIMS overview and current guidance
• Kenya Revenue Authority: how to onboard on eTIMS
• Kenya Revenue Authority: types of eTIMS solutions
• Kenya Law: Tax Procedures (Electronic Tax Invoice) Regulations, 2024
• Kenya Law: Tax Procedures Act, including section 23A