How to Set Up eTIMS OSCU: Step-by-Step Guide
OSCU (Online Sales Control Unit) is KRA's system-to-system route for invoicing systems designed to stay online. KRA positions VSCU as a separate route for bulk invoicing or systems that are not always online. Both require the applicable development, testing, vetting and certification process.
What Is OSCU?
OSCU stands for Online Sales Control Unit. KRA describes it as a system-to-system integration for invoicing systems that are always online and transmit transactions as they happen.
OSCU and VSCU are integration choices, not shorthand for hardware versus software. The right route depends on connectivity, transaction timing, volume and the current KRA approval process. Review KRA's current system-to-system integration guidance before making the technical choice.
OSCU vs VSCU: What's the Difference?
| Type | What It Is | Who Should Use It |
|---|---|---|
| VSCU | Virtual Sales Control Unit for bulk or not-always-online invoicing systems | Integrations that need controlled batch transmission or cannot remain continuously online |
| OSCU | Online Sales Control Unit for always-online invoicing systems | Integrations designed to send transactions to eTIMS as they happen |
A business using a hosted invoicing product does not need to choose an integration route from this table alone. Confirm the product's approved workflow and use KRA's current guidance when deciding between self-integration, a verified third party, OSCU and VSCU.
What You Need Before Setup
- Active KRA PIN — verify at itax.kra.go.ke
- Your Branch ID — confirm the branch identifier assigned to the invoicing location
- An integration route — OSCU for an always-online system or VSCU for the applicable bulk or not-always-online workflow
- Technical readiness — the current KRA specification, sandbox access, secure credential storage and a support owner
- Production approval — complete the applicable KRA vetting, certification and activation process before live invoices
Step-by-Step OSCU Setup
Choose the applicable integration and operating owner
Decide whether your invoicing system needs the always-online OSCU route or the VSCU route for bulk or not-always-online operation. Confirm whether your team will self-integrate or use a provider that has completed the applicable KRA process.
Confirm the taxpayer and branch details
Use the KRA PIN and branch identifier assigned to the business and invoicing location. Do not assume a branch code when the taxpayer has multiple branches; confirm it in the applicable KRA setup.
Complete sandbox and production readiness
Follow KRA's current development, testing, vetting and certification steps. A sandbox success demonstrates the integration flow; it does not by itself authorize production invoicing.
Initialize the authorized OSCU setup
After the applicable setup is approved, the integration calls KRA's initialization endpoint with the taxpayer, branch and device details. Store the returned communication credentials securely and never expose them in client code or support screenshots.
Sync codes and register valid items
Sync the current KRA code lists, map tax and item classifications, and validate the invoice payload before any live submission. Keep code ownership and update handling explicit.
Test status handling, then verify the first live receipt
Exercise success, validation and retry states in sandbox. After production enablement, submit an authorized live transaction and confirm the accepted KRA receipt fields and QR data before treating the workflow as operational.
What Happens During OSCU Initialization (Technical)
For developers or curious business owners: here's what actually happens when you click "Initialize."
Your platform calls KRA's POST /selectInitOsdcInfo endpoint with:
{
"tin": "P051234567R", // your KRA PIN
"bhfId": "00", // branch ID
"dvcSrlNo": "RISITI001" // device serial (generated by the app)
}KRA responds with:
{
"resultCd": "000", // success
"cmcKey": "abc123...", // communication key — store this securely
"sdcId": "SDC-12345", // your device ID
"dvcSrlNo": "RISITI001"
}The cmcKey is sent with every subsequent API call as a security token. It's stored encrypted in your Risiti account — you never see or manage it directly.
Common OSCU Setup Errors
Error: PIN not found
Your KRA PIN is not active or the format is wrong. Check iTax. Format should be like P051234567R (letter, 9 digits, letter).
Error: Branch ID invalid
Use '00' for your main branch. Some businesses use '01', '02' etc. for multiple locations — confirm with KRA if unsure.
Timeout / no response
KRA's API may be temporarily slow. Wait 30 seconds and retry. If it persists, check KRA's system status or try during off-peak hours (avoid month-end rush).
Error: Already initialized
Your PIN+Branch combination already has an active OSCU. Contact your eTIMS provider — you may need to retrieve the existing cmcKey rather than reinitialize.
Frequently Asked Questions
What is OSCU in eTIMS Kenya?
OSCU (Online Sales Control Unit) is KRA's system-to-system integration route for invoicing systems designed to stay online. KRA positions VSCU separately for bulk or not-always-online workflows.
Do I need a physical OSCU device for eTIMS?
OSCU and VSCU describe KRA system-to-system integration routes, not a simple hardware-versus-software choice. A hosted eTIMS product may handle the approved integration for you; self-integrators should follow KRA's current technical and certification process.
How long does OSCU initialization take?
Initialization time varies with taxpayer readiness, the selected solution, KRA availability and any required vetting or production approval. Do not treat an API response time as the full onboarding timeline.
What is the cmcKey in eTIMS?
The cmcKey (communication key) is a security token KRA returns during OSCU initialization. It must be included in every API call to KRA. Your eTIMS software stores and manages it automatically.