Kenya eTIMS Integration

Kenya's Tax Invoice Management System (eTIMS) requires VAT-registered businesses to transmit sales transactions electronically to the Kenya Revenue Authority (KRA). This app connects your company's Sales Invoices (and, if configured, Stock Movements) to KRA's eTIMS OSCU/VSCU service — including the rent invoices from the Property Management app and the progress/retention invoices from the Construction app.

This app needs KRA registration steps that ECOSIRE cannot do for you

Before this app can transmit to Production, your tax team must register with KRA (see Step 1 below). Until that's done, keep the app in Sandbox — invoices are still created and posted normally in ERPNext; they simply aren't sent to KRA's live system.

What you'll need

• A System Manager or Finance role to configure eTIMS Settings.
• Your company's KRA PIN, Branch ID (bhfId), and a registered Device Serial Number — obtained from KRA/your tax consultant, not from this app.
• Sandbox access at KRA's eTIMS sandbox portal before going live in production.

1. External setup with KRA (do this first, outside the software)

This part happens with your tax consultant and KRA, not inside ERPNext:

1. Register for eTIMS system-to-system integration (OSCU — Online Sales Control Unit, or VSCU — Virtual Sales Control Unit, depending on what KRA assigns your business type).
2. Sign up for the eTIMS sandbox at etims-sbx.kra.go.ke to get sandbox credentials and test the flow before going live.
3. Confirm with KRA/your tax consultant: your company's KRA PIN, the Branch ID (bhfId) for each invoicing branch, and the device registration process for your Device Serial Number.
4. Once sandbox testing is clean, KRA will vet and approve you for Production transmission.

2. eTIMS Settings — configure the app

Open eTIMS → eTIMS Settings.

Device & Environment:

• Environment — Sandbox (default, safe for testing) or Production (only after KRA approval).
• Enable eTIMS Transmission — master on/off switch.
• Taxpayer PIN (KRA PIN), Branch ID (bhfId), Device Serial Number — from Step 1.

Device Registration (read-only fields, populated by an "Initialize Device" action once KRA issues them):

• Communication Key (cmcKey), Device ID (dvcId), Control Unit ID (sdcId), MRC Number, Last Initialised.

Transmission Options:

• Auto-transmit Sales Invoices & Credit Notes on submit — when on, every Sales Invoice you submit (rent invoices, progress bills, retention releases — all of them, across every company) is automatically sent to KRA.
• Auto-transmit Stock Movements — for construction/warehouse material movements, if your KRA registration requires stock reporting.
• Max Transmission Retries — how many times a failed transmission is retried automatically.

VAT Band Rates (%):

• Band A (Exempt), Band B (Standard VAT), Band C (Zero-rated), Band D (Non-VAT), Band E (Other). Confirm these against the current Finance Act with your tax team before go-live — rates can change by legislation and this app does not auto-update them.

3. How transmission works day to day

You don't do anything extra — this runs in the background:

1. A user submits a Sales Invoice (a rent invoice, a Progress Bill's invoice, a Retention Release invoice — anything).
2. If Auto-transmit is on, the app immediately sends the invoice to KRA's eTIMS endpoint for the configured environment (Sandbox or Production).
3. KRA responds with a Result Code and Result Message. On success, the invoice is now fiscally reported.
4. If KRA's response fails or times out, the app automatically retries every 15 minutes (up to Max Transmission Retries) — no manual resend needed unless it exhausts retries.

The same happens for a Stock Entry submission, if stock transmission is enabled.

4. eTIMS Transmission Log — checking what happened

Open eTIMS → eTIMS Transmission Log to see every transmission attempt:

Field	What it means
Reference	The Sales Invoice or Stock Entry that was transmitted
Environment	Sandbox or Production
Status	Pending, Success, Failed, or Dead Letter (exhausted all retries)
Attempt Number	Which retry this was
Result Code / Result Message	KRA's response
HTTP Status, Duration (ms)	Technical detail for troubleshooting
Next Retry At	When the app will try again, if Failed
Request/Response Payload	The raw JSON sent and received — useful when escalating to KRA or ECOSIRE support

Troubleshooting

Problem	Likely cause	What to do
Invoice shows no Transmission Log at all	Enable eTIMS Transmission or Auto-transmit Sales Invoices is off	Check eTIMS Settings
Status = Failed, retrying	Temporary network/KRA-side issue	Wait for the automatic retry; check Result Message for a specific KRA error
Status = Dead Letter	All retries exhausted	Review the Result Message and Request/Response Payload; contact your tax consultant or KRA support with the exact error, then use the "resend" action once the underlying issue (e.g. wrong Branch ID) is fixed
Result Message mentions PIN/Branch/Device mismatch	KRA-side registration details don't match what's entered in Settings	Re-confirm PIN, Branch ID, and Device Serial Number with KRA
Sandbox works but Production doesn't	Production requires separate KRA approval/vetting	Confirm your Production go-live approval with KRA before switching Environment

See also

• Overview
• Getting Started
• Property Management — where rent Sales Invoices originate
• Construction & Site Management — where Progress Bill / Retention Sales Invoices originate
• KRA eTIMS sandbox: etims-sbx.kra.go.ke (external, not part of this app)