ZRA Smart Invoice — Invoicing (Zambia)
by AminiTech Solutions https://www.aminitechsolutions.com$ 391.00
ZRA Smart Invoice — every invoice, declared
Declare every customer invoice and credit note to the Zambia Revenue Authority through your own VSDC in real time. The receipt number, the receipt signature, the internal data and the verification QR come straight back and print on the invoice PDF. VAT is reported in the ZRA tax types — A Standard Rated 16%, B Minimum Taxable Value, C1/C2/C3 zero-rated, D Exempt, RVAT, E and TOT — with the VAT-inclusive amounts the VSDC expects.
One-time purchase · unlimited documents · free updates on every ZRA Smart Invoice spec change. Requires the free ZRA Smart Invoice Base.
Post as usual — ZRA compliance happens for you
Posting a customer invoice enqueues a saveSales declaration (receipt type S); the accountant never waits on the VSDC. Credit notes go out as refunds (receipt type R) referencing the original invoice number, and the receipt number, signature, internal data, SDC ID and MRC No land on the record and on the printed PDF next to a verification QR. Because everything flows through the Base queue, posting is never blocked — and a document the ZRA has accepted is simply guarded from being reset to draft.
saveSales, done right
Every posted invoice is declared to your VSDC through /trnsSales/saveSales — the customer block, the item list, the per-band tax buckets and the totals built to the ZRA specification — and the receipt number and signature come straight back onto the record.
The signature on the paper
The ZRA invoice number, receipt number, SDC ID, MRC No, VSDC date, internal data and receipt signature print on the invoice PDF beside a scannable verification QR, under a plain statement that this is a fiscal receipt declared to the ZRA.
VAT the ZRA way
Tax is reported in the ZRA taxation types — A Standard Rated 16%, B Minimum Taxable Value 16%, C1 Exports, C2 Zero-rating LPO, C3 Zero-rated by nature, D Exempt, RVAT, E Disbursement and TOT Turnover Tax — with VAT-inclusive amounts, matched to the ngwee.
From draft to declared — every detail on the invoice
Every posted invoice is declared, and posting never waits
Posting a customer invoice builds the complete saveSales payload — customer TPIN and name, the receipt block, the item list, the per-band tax buckets and the totals — and hands it to the submission queue, which sends within about two minutes or immediately on demand. Your accountant never waits on the VSDC, and if a declaration cannot even be built the invoice still posts: the failure is recorded on the document instead of blocking your books. If the company’s ZRA configuration is incomplete the document is parked as Not Configured with the exact list of what is missing, rather than firing a reject at the VSDC.
The whole VSDC acknowledgement lives on the invoice
Every customer invoice and credit note gains a ZRA Smart Invoice tab in two halves. Declaration holds the ZRA Status, the receipt type (S Sale or R Refund), the ZRA invoice number, the refund reason on credit notes, the ZRA Exempt flag and which environment the document belongs to. ZRA Acknowledgement appears once the VSDC answers, holding the receipt number, total receipt number, receipt signature, internal data, SDC ID, MRC No and VSDC date. Nothing is buried in a log file — the full fiscal acknowledgement sits on the record, ready for an audit or a buyer query.
Five honest states, colour-coded in the header
A badge in the invoice header reports the fiscal state on the record itself: Queued, Declared, Failed, ZRA Exempt or Not Configured — green when the ZRA has it, red when it rejected it, amber while it is waiting or unconfigured, muted when the document is deliberately out of scope. When something goes wrong the failure reason returned by the VSDC appears in plain words on the ZRA tab, and stays hidden while everything is healthy so the form is not cluttered. Those last three matter because they are genuinely different problems: waiting, rejected and never-meant-to-go each need a different response from you.
A “Send to ZRA” button for anything not yet declared
A Send to ZRA button sits in the header of any posted invoice or credit note that has not reached the ZRA, and disappears the moment it is declared or marked exempt — so nobody can re-declare a document that already carries a receipt signature. Pressing it enqueues the declaration if needed and pushes every pending or failed entry for that document immediately, instead of waiting for the next sweep. It refuses drafts outright: only a posted document can be declared. It is the one button an accountant needs after an outage.
From the invoice to its declarations in one click
A ZRA Queue smart button on the invoice shows how many queue entries the document has produced and opens them filtered to that document alone. From there you see the payload that was sent, the VSDC’s answer, the attempt count and the full error history — the audit trail for this one invoice, without hunting through a global list. It hides itself when there is nothing to show.
The declaration is written into the invoice’s own history
The chatter records the fiscal life of the document as it happens: “Queued for ZRA transmission as invoice 6 (S).” when it is enqueued, then, once the ZRA accepts, a full “Declaration accepted by the ZRA” table — the invoice number, original invoice on a refund, receipt type, sale date, customer name and TPIN, every tax band with its taxable amount and VAT, the totals, the receipt number, SDC ID, MRC No, VSDC date, the receipt signature and internal data, followed by the item lines exactly as transmitted. A first failure posts its own note in red with the VSDC’s message and a reminder that the queue keeps retrying. Nobody has to reconstruct what was sent — it is on the record, in the record’s own history.
The ZRA invoice number is never reissued or overwritten
Each declarable document takes the next number from your continuous per-device ZRA series the first time its payload is built, and keeps it forever — the field is indexed, never copied to a duplicate and never overwritten on a retry. That is what makes a re-send safe: the same number goes back, so the VSDC either registers it or reports it as already received, never as a second sale. It is also what keeps your series auditable, which the Base then checks hourly for holes and duplicates.
Refunds go out as a proper refund declaration
A credit note is declared as a refund — receipt type R — carrying the original invoice’s ZRA number as orgInvcNo, plus the refund reason code and refund date. It is picked up from the reversal link automatically, so nothing has to be typed twice, and the refund reason field is editable per document with a sensible default when you leave it blank. The credit note comes back with its own receipt number and signature on its own ZRA tab, and prints its own fiscal footer. That is the ZRA-approved way to reverse a declared sale — not a hand-patched invoice.
Map each tax once, in Zambia’s own vocabulary
Every sale tax carries a ZRA Tax Type selector covering the full code class: A Standard Rated (16%), B Minimum Taxable Value (16%, charged on the retail or recommended price), C1 Exports (0%), C2 Zero-rating on a Local Purchase Order (0%), C3 Zero-rated by nature (0%), D Exempt, RVAT Reverse VAT where the buyer accounts for it, E Disbursement outside the tax base, and TOT Turnover Tax. Set it once per tax and every invoice afterwards reports VAT in the exact buckets the VSDC validates. The three different flavours of zero — export, LPO and by-nature — are genuinely different declarations, and this is where you tell them apart.
Unmapped taxes still declare — and zero-rating is never guessed
You do not have to hand-map a tax table before going live. Any sale tax left without a ZRA type falls back by rate: a positive rate declares as A (Standard Rated, 16%) and a zero rate as D (Exempt) — and a line with no tax at all declares as D. A one-pass classifier stamps every unmapped sale tax the same way for you. What it deliberately never does is guess C1, C2 or C3: exports, LPO zero-rating and zero-rated-by-nature are all 0% but they are legal choices, not arithmetic, so you pick them yourself.
The one calculation that trips up every Zambian connector
ZRA amounts are gross: the taxable amount includes VAT, and the VAT is extracted back out of it rather than added on top. The connector does exactly that — it grosses the unit price up by the band rate, applies the line discount as both a rate and an amount, and extracts VAT as taxable multiplied by rate over 100 plus rate. Get this backwards, as an add-on-top calculation would, and every declaration is quietly wrong by the VAT fraction while still returning a success code. Each line is declared with its band, gross unit price, supply amount, discount rate and amount, taxable amount, VAT and total.
The totals you print are the totals the ZRA validated
The declaration header carries a taxable amount, a rate and a VAT amount for every band from A through TOT, plus the total taxable, total VAT and grand total — and every one of those figures is aggregated from the lines that were actually sent, not recalculated separately. That means the header can never disagree with the item list, whatever rounding happened upstream, and the VAT 16% total on the printed invoice is exactly what the VSDC received. No re-keying, no second calculation to reconcile at year end.
Every line declares a complete, coherent item block
Each line goes up with its full item identity: the item code, the UNSPSC classification, the item name, barcode, packaging unit and quantity unit, plus its sequence number, packaging and quantity. Where a product has no explicit ZRA code the connector synthesises a valid one and falls back to your company’s default classification, so an invoicing-only install declares complete lines without you touching the product catalogue first. When the invoice line has its own description — the one the customer actually reads — that is what is declared, not a generic product name.
The customer’s TPIN travels with the declaration
The buyer’s TPIN, name and mobile number are read from the contact and sent on the declaration, alongside your own trade name and address in the receipt block and the invoice reference as the receipt’s top message. Because the free Base validates any contact’s TPIN against the ZRA register in one click — showing the taxpayer name the ZRA holds and the date it was checked — you can confirm the buyer before you ever declare against them. That is a thirty-second check that prevents a rejected declaration later.
The receipt signature and QR print on the invoice
Once the ZRA answers, the printed invoice carries a proper fiscal footer: the ZRA invoice number, receipt number, SDC ID, MRC No, VSDC date, internal data and receipt signature, beside a scannable QR and the plain statement that this is a fiscal receipt declared to the Zambia Revenue Authority. The VSDC returns no ready-made verification URL, so the connector composes the ZRA verification link itself from the device and signature values. The whole block prints only on documents the ZRA has actually accepted — a draft or an undeclared invoice can never carry a fake signature.
A declared invoice cannot be quietly edited
Once the ZRA has accepted an invoice, Reset to Draft is blocked with a plain explanation: the document is declared under its ZRA invoice number, editing it would make your books diverge from the ZRA, and a credit note is the correct remedy. This stops the single most damaging mistake in a fiscalised ledger — reopening a document the revenue authority has already accepted. Invoices that were never declared, that failed, or that are marked exempt reset to draft exactly as normal.
Keep the documents that must never be declared out of it
A ZRA Exempt tick box on the ZRA tab holds a document out of the declaration flow entirely — the right answer for opening balances, migrated history and internal documents that should never be declared. The document shows a muted ZRA Exempt badge instead of a fiscal status, the Send to ZRA button disappears, and it is copy-safe: duplicate the invoice and the flag does not travel with it, and neither do the receipt number, signature or ZRA invoice number of the original. The flag is restricted to the Manager role and is tracked in the chatter, so exempting a document is a decision with a name and a timestamp on it.
An hourly sweeper catches up anything that slipped through
Beyond the Base queue, an hourly sweeper re-examines posted invoices and credit notes that never made it — the ones parked as Not Configured before you finished setup, the ones that failed, the ones that somehow have no status at all — and enqueues them oldest first, but only for companies whose transmission is Active and only where no live queue entry already exists. So the day you finish configuring your VSDC, the backlog declares itself in the right order without anyone clicking through a list. Invoices generated by Point of Sale orders are deliberately skipped, because the POS app declares its own sales at the till.
We connect you to ZRA Smart Invoice
Buying the app includes the setup: we help you register your device on the ZRA Smart Invoice Taxpayer Portal, point the connector at your VSDC (or ZRA’s hosted OSDC), run the device initialisation, validate the full flow on the ZRA sandbox, then switch you to production.
Device on the ZRA Smart Invoice portal
TPIN, branch, device serial, tax bands
Full flow on the ZRA sandbox
Switch to production, declare for real
One suite, sold your way
Buy only what you need on the free Base, or take the all-in-one Suite.
Frequently asked
Does it need the ZRA Smart Invoice Base?
Yes — the free Base provides the VSDC connection, the device initialization and the asynchronous submission queue this app builds on. Install it first; it costs nothing.
What VAT rate does Zambia use?
Standard VAT is 16%, declared in ZRA taxation type A. The app also covers B (Minimum Taxable Value, 16% on the retail or recommended price), C1 Exports, C2 Zero-rating LPO, C3 Zero-rated by nature, D Exempt, RVAT Reverse VAT, E Disbursement and TOT Turnover Tax. Amounts are declared VAT-inclusive, as the VSDC expects.
What about credit notes?
They are declared as refunds (receipt type R) referencing the original invoice’s ZRA number, with a refund reason code, and come back with their own receipt number and signature — the compliant way to reverse a declared sale.
Does it ever block me from posting?
No. Declaration runs on the Base queue and retries on its own, so a VSDC that is slow, restarting or unreachable never stops an invoice being posted. A declared document is guarded from being reset to draft, but posting itself is never blocked.
Can I test before going live?
Yes. Point the sandbox VSDC URL at your bridge configured for the ZRA sandbox, declare real invoices with zero fiscal impact, then switch one radio to Production — the production URL is already stored, so nothing is retyped. Every queue entry keeps a record of the environment it was declared under.
My VSDC uses a different endpoint path. Is that a problem?
No. The ZRA specification is inconsistent about endpoint pluralization and a wrong path simply 404s, so every path is overridable per company through a JSON map in the Base. Your provisioned VSDC is the authority — point the connector at what it actually exposes.
Ready for ZRA Smart Invoice compliance?
Install now, or write to us — we set up your Smart Invoice connection with you.
reach@aminitechsolutions.comZRA, Smart Invoice and the Zambia Revenue Authority name are the property of the Zambia Revenue Authority and are used here only to identify the system this connector integrates with. AminiTech Solutions is an independent software vendor and is not affiliated with, or endorsed by, the ZRA.
| Availability |
Odoo Online
Odoo.sh
On Premise
|
| Odoo Apps Dependencies |
•
Invoicing (account)
• Discuss (mail) |
| Community Apps Dependencies | Show |
| Lines of code | 2018 |
| Technical Name |
aminitech_zra_invoice |
| License | OPL-1 |
| Website | https://www.aminitechsolutions.com |
Odoo Proprietary License v1.0 This software and associated files (the "Software") may only be used (executed, modified, executed after modifications) if you have purchased a valid license from the authors, typically via Odoo Apps, or if you have received a written agreement from the authors of the Software (see the COPYRIGHT file). You may develop Odoo modules that use the Software as a library (typically by depending on it, importing it and using its resources), but without copying any source code or material from the Software. You may distribute those modules under the license of your choice, provided that this license is compatible with the terms of the Odoo Proprietary License (For example: LGPL, MIT, or proprietary licenses similar to this one). It is forbidden to publish, distribute, sublicense, or sell copies of the Software or modified copies of the Software. The above copyright notice and this permission notice must be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Please log in to comment on this module