Integrating your own system with eTIMS: OSCU or VSCU
What it takes for a Kenyan business to connect its own invoicing or ERP system to eTIMS through OSCU or VSCU, and questions to ask an integrator.
By Achekam · · 4 min read · For Running a business businesses in Kenya
A distributor raising hundreds of invoices a day from its ERP cannot sensibly retype each one into a separate eTIMS screen. Neither can a utility billing thousands of customers, or a hotel whose property system already produces every bill. For businesses like these, the natural answer is to connect the system they already use directly to eTIMS.
KRA allows this through system-to-system integration, using one of two control units: OSCU or VSCU. The idea is simple; the path to going live is not short. This article explains the two options, the stages KRA describes, the choice between building it yourself and using an integrator, and where Achekam's own connector stands.
System-to-system integration as KRA describes it
KRA says businesses with their own invoicing or ERP system can integrate with eTIMS through an API, using either the Virtual Sales Control Unit (VSCU) or the Online Sales Control Unit (OSCU). Your system sends each invoice's details to eTIMS and receives back the identifiers that make it a valid electronic tax invoice.
The important condition comes first: a system can connect to eTIMS system-to-system only after KRA certifies the integration. Until then, whatever has been built is a test, not a live link.
KRA's page on eTIMS system-to-system integration explains OSCU and VSCU, links to their specifications and the sandbox, and sets out the stages to certification.
OSCU or VSCU?
KRA describes the difference in terms of how you invoice:
| OSCU | VSCU | |
|---|---|---|
| Suits | Invoicing that is always online | Bulk invoicing by taxpayers not always online |
| Connection | Needs a stable connection | Keeps invoicing offline and transmits when connected |
A business whose invoices are generated centrally on a reliable connection fits OSCU. A business generating large batches, or working where connections drop, fits VSCU. If you are not sure whether integration is right for you at all, compare it with the other solutions in choosing the right eTIMS solution.
Building it yourself or using an integrator
KRA says a taxpayer can integrate with eTIMS itself or use a KRA-verified third-party integrator. Either way, KRA describes integration as involving development, testing, vetting and certification.
KRA provides material for both routes. It links the OSCU and VSCU specification documents, a sandbox registration guide and a sandbox test environment, and it publishes third-party vendor requirements on etims.kra.go.ke. KRA's GavaConnect developer platform also lists an eTIMS OSCU integrator automated testing API and an Invoice Checker API, among others; see KRA's GavaConnect APIs.
Building in-house makes sense when you have developers who already maintain the invoicing system and can keep the link working through KRA's future changes. Using an integrator makes sense when you do not, or when the integrator already connects systems like yours. In both cases, someone inside the business must own the result, because it is your invoices, and your customers' claims, that depend on it.
On cost, KRA says its own eTIMS software is free, but businesses integrating their own invoicing system may incur costs if they use an approved third-party integrator.
The stages, in order
- Development. Your developers, or the integrator's, build the link to the specification for OSCU or VSCU.
- Sandbox testing. The system is registered in KRA's sandbox and tested there. Nothing sent to the sandbox is a real invoice.
- Vetting. KRA reviews the integration.
- Certification. KRA certifies the integration. Only then can it connect to eTIMS for real.
- Production set-up. The business moves to the live environment and starts issuing real invoices through the link.
Plan the project around those stages. Budget time for retesting if vetting finds problems, and keep your existing eTIMS solution running until the integration is live.
Where Achekam's eTIMS connector stands
Achekam has a connector for KRA's online channel, OSCU. It can use KRA's sandbox without platform authorisation, but it does not transmit Kenyan invoices to eTIMS in production today. Three things must happen first: KRA certifies the integration, an Achekam platform administrator records that authorisation, and the business initialises a production eTIMS device. Several eTIMS details also have to be configured, because the research behind the connector could not confirm them.
Achekam is careful about what it claims. It does not claim to be a KRA-approved eTIMS integrator, and it never generates eTIMS receipt numbers, internal data or signatures itself. Tax rates come from KRA's code list, never from the sample values in KRA's specification.
On documents, Achekam prints eTIMS identifiers on an invoice only once the invoice is fiscalised, and otherwise the document says it is not yet fiscalised. A sandbox submission is labelled as test only, so a test invoice cannot pass for a real one. For how shops using Achekam's till get their sales through eTIMS in the meantime, see fiscalising Kenyan till sales through eTIMS.
Questions to ask an integrator before signing
- Are you KRA-verified for eTIMS integration, and can we see it?
- OSCU or VSCU, and why for our business?
- Which of our systems will you connect: the ERP, the till, the billing system, or all of them?
- Who handles sandbox testing, vetting and certification, and what happens if vetting fails?
- How are credit notes handled, given they must come from the solution that issued the original invoice?
- What happens when your service is down? Can we still invoice?
- What does it cost, set-up and ongoing, and who owns the integration if we leave?
- How will we see the eTIMS identifiers in our own accounting records?
Write the answers into the contract. An integration is a long-term dependency, and the time to agree how it will be supported is before anyone writes code.
General guidance only, not advice on your own circumstances. Tax and payroll rules change: check the current position with the authority or your adviser.
