PUBLIC
ISO 9001:2015 CERTIFIED
Virtual Sales Control Unit
(VSCU) Version 1.0.3
Application Installation and
Setup Guide for Windows
Operating System
August 27, 2024
Version 1.0.3
KENYA REVENUE AUTHORITY PUBLIC
Notice
© 2024 Kenya Revenue Authority (KRA)
This is a controlled document. Unauthorized access, copying, replication or
usage for a purpose other than for which it is intended, are prohibited.
All trademarks that appear in the document have been used for identification
purposes only and belong to their respective companies.
KENYA REVENUE AUTHORITY PUBLIC
3
eTIMS VSCU Application Installation and Setup
Step-by-Step Guide
STEP 0: Prepare System
Make sure your system meets the following Minimum System Requirements:
1. Java JDK/JRE 21 or later is installed on your system.
2. Internet Connectivity to eTIMS server URL located at:
3. 4GB RAM
STEP 1: Transfer Application file to your System
1. Transfer the Application file (VSCU-1.0.3.zip) to the target machine where
you want to deploy it. You can use methods such as SFTP, SCP, or a file-
sharing service to transfer the JAR file from your local machine to the target
machine.
2. Unzip the file to your target directory e.g. C:\KRAVSCU
The content of the zip file is:
STEP 2: Configure Application Properties
1. From the target directory, change directory to config directory
cd C:\KRAVSCU\config
For production deployment
https://etims-api.kra.go.ke/etims-api
For sandbox deployment
https://etims-api-sbx.kra.go.ke/etims-api
.
├ config
| ├ application.properties
|vscu-1.0.3.jar
|vscu.bat
|vscu.sh
# unzip VSCU-1.0.3.zip
KENYA REVENUE AUTHORITY PUBLIC
4
2. Edit the application.properties file using your favorite editor by updating
the following parameters:
• Update api.external.domain property based on VSCU use in production or
sandbox environments.
• Update server.port to the port you prefer VSCU to run on your target
machine. (Default 8088)
• Update property.path to a filesystem path preferable to host VSCU data.
(Default user.home)
3. Save changes
STEP 3: Update Runtime Configuration (vscu.bat)
1. From the target directory, change directory to config directory
cd C:\KRAVSCU\config
2. Edit the vscu.bat file using your favorite editor by updating the following
parameters:
• Update Java Runtime Memory allocation settings i.e. MIN_MEM (minimum)
and MAX_MEM (Maximum) properties (set in MB)
Note:
✓ MIN_MEM setting should be a minimum of ⅛ of your System
RAM.
✓ MAX_MEM setting is recommended to be a maximum of ½ of
your System RAM.
set MIN_MEM=512m
set MAX_MEM=4096m
property.path =user.home
server.port=8088
For production deployment
api.external.domain=https://etims-api.kra.go.ke/etims-api
For sandbox deployment
api.external.domain=https://etims-api-sbx.kra.go.ke/etims-api
KENYA REVENUE AUTHORITY PUBLIC
5
• Update ACT_PROC_COUNT property (This setting allocated CPU cores to
the application)
• Update BASE_FOLDER property (Location where VSCU files were extracted
to)
3. Save changes
STEP 4: Running VSCU as Standalone Application
1. Execute the bat file (vsdc.bat) by running the following on command prompt
from the BASE_FOLDER:
2. The VSCU application will now be accessible to the Trader Invoicing System
via the following URL:
http://<hostname or ip>:<configuredserverport>
e.g. http://localhost:8088
STEP 5: Initialize VSCU Application Instance (Applies to
new vscu installations)
1. Invoke the VSCU initialization endpoint (/initializer/selectInitInfo) with
Taxpayer PIN, branch office ID, and serial number earlier shared to you
during eTIMS service request.
set BASE_FOLDER= C:\KRAVSCU
set ACT_PROC_COUNT =3
vscu.bat
Request Payload
{
"tin":"P000000000N",
"bhfId":"00",
"dvcSrlNo":"CZC000H001"
}
KENYA REVENUE AUTHORITY PUBLIC
6
2. After successful initialization, the TIS will be able to access all other VSCU
operations.
Successful Response Payload
{
"resultCd": "000",
"resultMsg": "Successful",
"resultDt": "20240823162330",
"data": {
"info": {
"tin": " P000000000N ",
"taxprNm": "A COMPANY LIMITED",
"bsnsActv": "8690 - Other human health activities",
"bhfId": "00",
"bhfNm": "Headquarter",
"bhfOpenDt": "20240104",
"prvncNm": "Kiambu",
"dstrtNm": "Thika West District",
"sctrNm": "Thika",
"locDesc": "eTIMS Address",
"hqYn": "Y",
"mgrNm": "A NAME ",
"mgrTelNo": "10111111100",
"mgrEmail": "EMAIL@XX.COM",
"sdcId": null,
"mrcNo": null,
"dvcId": "59397",
"intrlKey": null,
"signKey": null,
"cmcKey": null,
"lastPchsInvcNo": 0,
"lastSaleRcptNo": null,
"lastInvcNo": null,
"lastSaleInvcNo": 10022,
"lastTrainInvcNo": null,
"lastProfrmInvcNo": null,
"lastCopyInvcNo": null,
"vatTyCd": "2"
}
}
}