Skip to content

eTIMS — fiscalising invoices and till receipts in KRA (Kenya)

What it is

eTIMS is the system of the Kenya Revenue Authority (KRA) in which every sales document is registered. A registered document gets a KRA receipt: the CU invoice number, the device identifier (SCU ID), a signature and a QR code for verification. ERPJS sends invoices, credit notes and till receipts to eTIMS by itself — right after approval — through the eTIMS intermediary service. All of this exists only in the Kenya edition of ERPJS; the Ukrainian edition has no eTIMS module.

An overview of the module and its objects is on the eTIMS (KRA, Kenya) page.

Prerequisites: what to get from the eTIMS intermediary

  1. The intermediary service URL (starts with https://).
  2. An API key — the intermediary issues it for your KRA device (OSCU/VSCU).
  3. KRA reference codes: item classification codes, packaging and unit codes — issued by KRA or the intermediary.

Step 1. The eTIMS account

Open Modules → eTIMS → Registers → eTIMS Accounts and create a record.

  • Fill in «eTIMS URL» and «eTIMS API key». The key is stored encrypted: after saving, the field shows a mask. Leave it as is — the key stays; type a new one — it replaces the old one; clear the field — the key is erased on saving. If you change the URL, type the key again.
  • Tick «Company default» — this account will send the company's invoices. A company can have only one such account.
  • On the «eTIMS VAT mapping» tab, set the KRA tax type for every VAT code: A — exempt, B — 16%, C — zero rated, D — non-VAT, E — 8%. The VAT code's rate must match the type's rate: a 20% code on type B is saved, but a document with that code is not sent to eTIMS — the error names the row and the code.
  • Click «Test Connection» in the window menu.

Fields and checks are on the register page eTIMS Accounts.

Step 2. KRA codes for items

KRA requires a classification code, an item type, packaging and unit codes and a country of origin for every item. The ERPJS item card holds little of this data, so it is set up separately:

Whatever neither the item nor the group has is taken from the account's «eTIMS item codes» tab (the defaults). Before those defaults, the packaging and unit codes come from the «eTIMS unit mapping» tab (the item's unit of measure → KRA codes), the country from the item card's «Country of Origin» field if it holds a two-letter ISO code, and the item type from the card (a service — 3, anything else — 2). If a code is found nowhere, the document is not sent, and its record in eTIMS Receipts says which item is missing what.

Step 3. Payment type and the till

A back-office invoice goes out with payment type 01 (cash) if it is paid at sale: a till invoice or an invoice with payment terms of type "Cash" — accounting also posts it straight into the cash desk. A credit note never goes out this way. Otherwise with the account's «Default payment type», and if that is empty, with 02 (credit).

A till receipt goes out with the type of the payment method that paid the larger part of the amount:

  • in the Payment Methods setting, fill in the «eTIMS payment type» column (cash, card, mobile money…);
  • where the column is empty, the type comes from the till's payment slot: cash — 01, terminal — 05, cheque — 04. The "other" slot works only through the column.

A receipt the till closed only partly paid (a non-cash payment term) goes out with type 03, and one not paid at all — with type 02.

The till's account. If a shop has its own KRA device, fill in the «eTIMS account» field in POS payment modes (for one till) or in POS settings (for all tills). Otherwise the receipt goes out through the default account. A till account that is set but closed or deleted is an error, not a fallback to the default account.

Step 4. Approval and sending

Approve the invoice. After approval ERPJS sends it to eTIMS: first it registers the items, then the sale. Usually the receipt arrives within a second, and the user sees nothing extra.

The result is in the eTIMS Receipts register: one record per document, with the status, the number of attempts, the last error and the KRA receipt.

What the user sees What happened What to do
nothing the document is in eTIMS, the receipt is recorded nothing
«eTIMS server is busy — invoice 77 will be validated later» eTIMS did not answer or answered with a server error nothing: the system retries by itself, the pause grows from 1 minute to an hour
«eTIMS: invoice 77 is not fiscalized: …» the document was not sent because of data or settings (no item codes, no tax type for a VAT code) fix what the text names and click «Send again» in the eTIMS Receipts record
«eTIMS did not accept invoice 77: …» the intermediary refused the refusal text comes from eTIMS; fix it and send again
«eTIMS: credit note 78 will be sent after its original invoice is fiscalized» the original invoice is still in the eTIMS queue nothing: the note follows it by itself

Errors are written in the language of whoever approved the document — both in the notification and in the «Last error» field. If a retry the system makes by itself ends in an error, whoever approved the document gets the same notification as in the table above.

Step 5. Credit note

A credit note (a return against an invoice) goes to eTIMS the same way, after approval, with the CU number of the original invoice and through the same account. So the credit note must name its original invoice, otherwise it gets an error.

  • While the original invoice is in the eTIMS queue (waiting or being sent), the note waits and follows it by itself.
  • If the original invoice is not in eTIMS (its record has an error, it was unapproved, it was approved before eTIMS was connected), the note gets an error. Fiscalise the invoice first, then click «Send again» in the note's record.
  • The credit notes against an invoice cannot add up to more than what is left of the invoice in eTIMS: such a note gets an error and is not sent.

Refund at the till

For KRA a refund at the till is a credit note too, and also against the original receipt. So on a till where eTIMS works, the refund button (in POS Buttons — the action «refund invoice») does not turn the receipt into a refund at once but asks which receipt is being refunded:

  1. Start from a new empty receipt. If a sale is already in progress on the receipt, the till refuses: «A refund starts from a new empty receipt» — close or delete the current receipt.
  2. The «Receipt being refunded» window opens: the closed sales of this till over the last 30 days, without refunds and credit notes, with the columns «Receipt No», «Date and amount», «Customer». Typed digits of the number only narrow the list — the receipt is chosen by its row.
  3. The new receipt becomes a refund receipt to the chosen one, with the customer of the original receipt. The printed receipt shows the line «Refund of receipt» with the original's number.
  4. Add the items being returned and close the receipt.

On closing, the till checks the refund receipt and refuses if:

  • the item is not on the original receipt or there is more of it than can be refunded: «Item A1: sold by receipt 77 — 2, already refunded — 1, can still be refunded — 1». Already refunded means everything against this receipt in approved refund receipts and credit notes;
  • the customer was changed: «Refund receipt 80: the customer must be the customer of receipt 77 (C1)»;
  • no original receipt was chosen: «In eTIMS a refund is a credit note to the original receipt: press the refund button at the till and choose the receipt».

In eTIMS the refund receipt goes as a credit note with the CU number of the original receipt, through the same account and with the customer PIN the original was sent with. From there it works like the credit note above: it waits for the original receipt while that one is in the queue, and gets an error if the original is not in eTIMS (for example, the receipt was sold before eTIMS was connected).

The original receipt cannot be unapproved while a refund receipt to it is approved: «Refund receipt 80 to this receipt is posted — unapprove the refund first».

On a till without eTIMS the refund button works as before.

Step 6. Printing the KRA receipt

The till receipt prints the KRA block and the QR code by itself. While there is no receipt yet, it prints a note instead: «eTIMS validation pending — the receipt will be validated later» or «Not validated by eTIMS»; a reprint after sending gives the QR code.

Invoices and credit notes print it through the document's print form (Print Forms). Add these variables to the template:

Variable What it prints
{Etims_SCU_Date} the KRA device date and time (DD/MM/YYYY hh:mm:ss)
{Etims_SCU_ID} the KRA device identifier
{Etims_CU_Invoice_No} the CU invoice number together with the device identifier: SCU ID/number
{Etims_Internal_Data} the receipt's internal data
{Etims_Signature} the receipt signature
{Etims_Note} a note when there is no receipt yet: «eTIMS validation pending — the document will be validated later» or «Not validated by eTIMS»
{Etims_Customer_PIN} the customer's KRA PIN the document went to eTIMS with (not the current one from the card)
{QR_Etims} the receipt's QR code as an image (about 3 × 3 cm)

A variable whose name starts with QR_ prints as a QR image, not as text. A document that is not in eTIMS prints the block empty.

When something goes wrong

The document was not sent, and the cause has been fixed. Open its record in eTIMS Receipts and click «Send again» in the window menu. The result comes straight away, in your language. This action and «Resolve unknown result» are available to those with the right to change the «eTIMS Receipts» register.

The eTIMS response was lost. If the connection dropped while a sale was being sent, it is unknown whether the document is in KRA. Such a record is marked «May already be in eTIMS»: the invoice cannot be unapproved, and a retry goes out as the same request (with the same amount and the same customer PIN). If the retries do not help, check the document on the KRA portal and click «Resolve unknown result»: «In eTIMS» with the CU number from the portal, or «Not in eTIMS» — then the document is sent again.

A customer without a PIN. If the «Tax Number» on the contact card is empty, the sale goes out without a customer PIN — as a sale to a private individual.

Limitations

  • A receipt sold before eTIMS was connected can be refunded at the till, but the refund does not go to eTIMS: KRA has no CU number of the original receipt, and the refund's fiscalisation record gets an error.
  • The refund limit counts quantities, not amounts. Credit notes adding up to more than what is left of the receipt in eTIMS are stopped by the eTIMS queue itself (see step 5).
  • Without an open «Company default» account, back-office invoices are not sent to eTIMS at all — with no fiscalisation record and no warning (till receipts with their own account go through it). When you clear the flag or close the account, set the flag on another open account.