EFRIS for your business
EFRIS is the Uganda Revenue Authority's electronic invoicing system. With it switched on, every invoice you issue and every sale at your till is sent to URA and comes back with a fiscal number your customer can verify.
The manual
| Getting ready at URA | The portal side: device, keys, thumbprint — and the traps at each step |
| This page | Switching it on in Smart Business Book |
| Commodity codes | Coding your catalogue, and units of measure |
| Codes for IT & software | A worked list for one industry |
| Day to day | What happens when you sell, and the queue |
| When URA refuses | Every error we have seen and its real cause |
| Going live | Moving off the test environment |
If you are starting from nothing, read them in that order. If something is already broken, go straight to When URA refuses — several EFRIS errors name a field other than the one that is actually wrong.
How long it takes
| Device application | Hours to a couple of days, at URA's pace |
| Thumbprint approval | Up to four business hours |
| Setting up in Smart Business Book | Minutes |
| Coding your catalogue | The real work — an afternoon for a small shop |
Nothing is sent to URA until every step is done, so there is no danger in starting and finishing later.
It is off until you turn it on
Nothing is sent to URA, and nothing about your invoices changes, until you switch EFRIS on for your business. If you are not in Uganda, are not VAT-registered, or have not enrolled with URA, you can ignore this page entirely — none of it is running in the background.
What you need before you start
| A TIN | Your taxpayer number. It is not your VAT number, and EFRIS keys everything on it |
| A device | Enrolled through the EFRIS portal. You get a DSN — a device serial number like 1058699282_01 |
| A keystore | You generate it yourself and register its thumbprint with URA |
| Commodity codes | URA's code for each thing you sell |
Getting the device and the thumbprint is done at URA, not here. It takes a few hours to a few days.
Switching it on
Settings → EFRIS, then Switch on.
Turning it on does not mean invoices start going to URA that minute — it means the setup can begin. The page then shows everything still outstanding, all at once, so you are not fixing one thing and being told the next.
Your identity
| Field | Where it comes from |
|---|---|
| TIN | Yours, digits only |
| Device number (DSN) | EFRIS portal → Device Management → View |
| Taxpayer ID | Issued with the device. Not the TIN. Blank sends 1 |
| Longitude / Latitude | Where the till is. Blank sends 0 |
The supplier's TIN is not your TIN
The device record names an accredited supplier and carries their TIN. Yours is the one in Section A of that record. Nothing refuses the wrong one until URA rejects your thumbprint, so it is worth checking twice.
The device key
Generate a keystore with your TIN as the common name:
keytool -genkeypair -alias efris -keyalg RSA -keysize 2048 -validity 3650 \
-keystore efris.jks -storepass CHANGE_ME -keypass CHANGE_ME \
-dname "CN=YOUR_TIN, O=Your Company Ltd, L=Kampala, C=UG"Then upload that file on the EFRIS page with its password. Smart Business Book reads both halves out of it: the private key your invoices are signed with, and the SHA-1 thumbprint you register in the URA portal.
Uploading your device public key
Device Management → Device Public Key Management → Upload
This is the step that decides whether the connection test passes, and it is separate from registering the thumbprint.
Your device starts with somebody else's key
Check the Public Key ID column on that list. A new device carries one reading Default — URA's placeholder. Everything URA encrypts for your device uses whatever is in that row, so until it is yours, Test connection fails on the key exchange in a way that looks exactly like a wrong key file.
The EFRIS page shows your device public key with a Copy button. Paste it into the Upload form — no headers, no line breaks.
Registering the thumbprint
This is a separate step from applying for the device, on its own screen:
Device Management → Device Public Key Management → Thumbprint Configure List → Add
An approved device is not a registered thumbprint
They are two different records. Your device application can read Approved, with its own reference number and an email confirming it, while the Thumbprint Configure List is still empty — and it starts empty.
Until a thumbprint is registered there, URA cannot encrypt anything for your device, and Test connection fails on the key exchange in a way that looks exactly like a wrong key file. If your key and certificate match each other, check this screen before anything else.
The form takes five things, and the EFRIS page shows all of them:
| Field | Where it comes from |
|---|---|
| TIN / Legal name | Prefilled by the portal |
| Type of Certificate | Self Signed |
| Thumbprint | Copy it from the EFRIS page |
| Valid Period from / to | Shown beside the thumbprint |
| Digital Certificate Form | Upload your .cer file |
"Remove any spaces" means the colons too
The portal rejects the colon-separated form that keytool -list prints. It wants the bare forty characters. The Copy button on the EFRIS page gives you that form, so use it rather than retyping from a terminal.
Upload the keystore, do not paste a key
A pasted key carries no certificate, so its thumbprint cannot be shown — and a key that does not match the one URA holds fails later in a way that looks like a URA outage rather than a wrong file.
Thumbprint approval takes up to four business hours. Then press Test connection: three checks run in order, and none of them sends an invoice.
How you price
One question decides how much tax is reported, so it is asked rather than assumed:
- Prices already include VAT — the usual case in Ugandan retail. A 118,000 line is 100,000 plus 18,000 VAT.
- Prices are before VAT — a 100,000 line becomes 118,000 with VAT added.
Getting this wrong misstates every return, which is why there is no default that quietly applies.
Commodity codes
EFRIS refuses any invoice line without a commodity code. This is the part that takes real work: every product you sell needs URA's code for it.
Set the code on the product, in Products → the URA EFRIS section. The EFRIS page counts how many are done, so you can see the job shrinking.
URA commodity codes → covers what the codes are, where to find the right one, and what happens to a line without one.
A code cannot be added to an invoice that is already issued
The code and the tax are recorded onto each line as the invoice is raised, and they stay as they were. This is deliberate: a catalogue you re-code in March must not change what an invoice said in January. If a line was raised without a code, correct the product and raise the invoice again.
What happens when you sell
Once EFRIS is on and the connection test passes, it is automatic. You do not press anything.
| You do this | Smart Business Book files | URA returns |
|---|---|---|
| Issue an invoice | a fiscal invoice | a fiscal number and QR |
| Sell at the till | a fiscal receipt | the same, printed on the receipt |
A till sale is filed as a receipt, not an invoice, because that is what it is.
A bad connection never stops a sale
Fiscalising happens after the sale is recorded and cannot undo it. If URA is unreachable, the sale still goes through and the receipt says "Not yet fiscalised with URA" rather than printing a number it does not have.
Anything unfiled waits in the queue on the EFRIS page. Press Try again when the connection is back.
The queue
The EFRIS page shows everything that has not reached URA, and why.
| Status | Means | Do |
|---|---|---|
| failed | URA refused, or could not be reached | Try again |
| blocked | The request could not be built at all | Fix the cause first |
Blocked is almost always a product with no commodity code. Fix the product, then press Try again — the request is rebuilt from the invoice.
A till receipt cannot be rebuilt: a POS sale keeps no line rows, so what was built at the moment of sale is what gets retried. Code your products before you start selling, not after.
Nothing is ever marked filed without URA's own number
There is no invented reference and no optimistic tick. If the queue says a sale has not been filed, it has not been filed.
When something is refused
Refusals carry URA's own code and message rather than "submission failed".
| Code | Means | Do |
|---|---|---|
1001 | TIN not registered for this device | Check the TIN and device number belong together, and to this environment |
2001 | Invoice already fiscalised | It went through. Do not resubmit |
2002 | Payload rejected | The message names the field — usually a missing commodity code |
A failed submission stays failed. The invoice is not given a made-up reference and is not marked as fiscalised. Believing your invoices are filed when they are not is worse than seeing a queue.