ZRA Smart Invoice — Point of Sale (Zambia)
by AminiTech Solutions https://www.aminitechsolutions.com$ 244.01
In-App PurchasesZRA Smart Invoice — Point of Sale (Zambia)
Declare every paid Point of Sale order to the Zambia Revenue Authority through your own VSDC, the moment the cashier takes payment. The ZRA receipt number, the receipt signature (rcptSign), the internal data, the SDC ID and the MRC No come straight back from /trnsSales/saveSales and print on the customer receipt. Because the VSDC runs on your own machine, the call is attempted inline — and if it is momentarily unreachable the order is queued and retried on its own, so the till never stops. Runs on the free ZRA Smart Invoice Base.
One-time purchase · unlimited documents · free updates on every ZRA Smart Invoice spec change. Requires the free ZRA Smart Invoice Base.
Fiscal receipts, without slowing the queue
The ZRA Smart Invoice VSDC is a Java bridge you run yourself — typically at http://localhost:8080/zravsdc, or ZRA’s hosted OSDC if that is what you were provisioned. This app POSTs each paid order to it directly: your data goes from your database to your device to ZRA, with no third-party SaaS sitting in the middle of your tax data. The declaration is attempted synchronously on an eight-second timeout so the signature block can reach the printer; any slower answer, refusal or outage drops the order into the shared queue and it is declared automatically the moment the VSDC responds. VAT is reported on the Zambian taxation-type codes — A Standard Rated 16%, B Minimum Taxable Value, C1/C2/C3 zero-rated, D Exempt, RVAT, E and TOT.
The signature on the paper
The receipt prints a fenced “ZRA Smart Invoice” block carrying the SDC ID, the MRC No, the receipt number, the invoice number, the receipt signature and the internal data — the values the VSDC returned, on the slip in the customer’s hand.
Inline first, resilient after
The VSDC is local, so it answers in well under a second and the declaration happens before the paper prints. Past eight seconds the connector stops waiting and hands the order to the retry queue — the cashier is never made to wait on a machine.
Zambian VAT, not a fork’s guess
Every line is declared on a real Zambian taxation-type code with the amounts VAT-inclusive exactly as ZRA expects, and the per-band header buckets are summed from the lines so the declaration is internally consistent to the ngwee.
Real-time declaration at the till, feature by feature
Every paid order is declared the instant it is validated
The connector hooks the order as it is processed and POSTs it to your VSDC at /trnsSales/saveSales as a sale (rcptTyCd S). The attempt is inline — not a nightly batch — so the receipt number, the total receipt number, the receipt signature, the internal data, the SDC ID, the MRC No and the VSDC publication date are written back onto the order before the paper leaves the printer. The buyer’s TPIN travels with the sale when a customer is set; an anonymous sale goes up as a walk-in buyer, which is exactly what a counter needs. Each order takes its own invoice number from a continuous, no-gap per-company counter, so a resend can never register the same sale twice.
The signature the VSDC returned prints on the customer receipt
The six values ZRA hands back — SDC ID, MRC No, receipt number, invoice number, receipt signature and internal data — are pushed into the Point of Sale receipt data and printed in a fenced “ZRA Smart Invoice” block above the cashier line. They are loaded onto the frontend order itself, so a reprint hours later still carries the same fiscal block rather than a blank space. No second device on the counter, nothing to re-key, no separate fiscal printer.
The whole VSDC acknowledgement lives on the order
Each POS order gains a ZRA Smart Invoice tab split into two groups. Declaration holds the ZRA Status badge (Queued, Declared, Failed or Not Configured), the active environment, the receipt type, the ZRA invoice number, the ZRA receipt number and the VSDC date; Fiscal Signature holds the receipt signature and the internal data behind copy-to-clipboard widgets, plus the SDC ID and the MRC No. If the VSDC rejects the sale, the verbatim failure reason appears in the same tab — and stays hidden while everything is healthy, so the form is not cluttered. Every one of these fields is copy-safe: duplicate an order and no fiscal identity travels with it.
A return is declared as a refund against the original sale
Return an order and the connector declares it as a refund (rcptTyCd R) rather than a hand-patched sale. It walks the refunded order lines back to the sale they came from and sends that order’s invoice number as orgInvcNo, together with a refund reason code and the refund date, so ZRA ties the reversal to the exact transaction it corrects. The refund earns its own invoice number and its own signature block on its own ZRA tab. That is the compliant way to undo a declared sale at the till.
One button for anything still outstanding
A Send to ZRA button sits in the POS order header for any paid, done or invoiced order that has not yet been declared, and it disappears the moment the order reaches Declared — so nobody can re-push a sale that already carries a signature. Pressing it re-prepares the payload if needed and immediately fires every pending or failed queue entry for that order instead of waiting for the next sweep. It is scoped to the ZRA User role, so a supervisor can clear a backlog after an outage without holding any device configuration.
Fiscal status and invoice number as columns
The Point of Sale orders list gains a ZRA Invoice No column and a colour-coded ZRA Status badge — green for Declared, amber for Queued or Not Configured, red for Failed — beside the order total. A manager closing the day sees in one glance which sales reached the VSDC and which did not, without opening a single order. Both columns are optional, so they can be toggled off for a leaner list.
A slow or offline VSDC never freezes the cashier
The inline call runs on a short eight-second timeout, and every failure mode is caught rather than thrown at the register: a connect timeout, a refused connection, a lost socket, an unreadable body, an HTTP 5xx. Whatever happens, the order is still completed, still paid and still printed — the declaration simply becomes a queue entry and is picked up automatically. The whole declaration step is additionally wrapped so that even an unexpected error is logged instead of surfacing at the counter. A VSDC problem can never become a cashier problem.
The tender on the order becomes the ZRA payment code
The payment type (pmtTyCd) is derived from the journals actually used on the order rather than typed by anyone. A cash-only sale is declared as 01, a sale settled entirely through bank or card journals as 05, and a mixed tender as 07. It is one less field for a cashier to get wrong under pressure, and one less reason for ZRA to bounce a receipt.
A resend can never register the same sale twice
The VSDC assigns fiscal numbers, and it rejects a re-submitted transaction with result code 921 (declared data cannot be re-received) or 994 (overlapped data). The connector treats both as success rather than as errors to retry forever, because the stored payload keeps the same invoice number on every attempt — so a resend either registers a sale that never landed, or is told it is already there. A successful inline declaration is also written into the queue as an audit entry in Sent state, so the trail is complete whether the sale went inline or through the retry path. This is what makes a delivery you could not read safe to re-send.
A scheduled job hunts down anything that slipped through
An hourly cron re-examines paid, done and invoiced orders from the last thirty days whose ZRA status is Failed, Not Configured or still blank, for companies whose transmission is Active. Before touching one, it checks that no live queue entry already exists for that order, so it can never duplicate work the queue is already doing. It is the safety net beneath the safety net: an order that was rung up while the TPIN was still missing is declared on its own once you finish configuring, with nobody chasing it.
A training till does not have to declare
Each Point of Sale carries a “Declare Orders to ZRA” switch, on by default, exposed both on the register and in a “ZRA Smart Invoice (Zambia)” block in the Point of Sale settings. Untick it and that register’s orders are left out of the declaration flow entirely — the right answer for a training till or a demo counter that must never reach ZRA. Every other register carries on exactly as before. The settings block is reserved for the ZRA Administrator role, and the switch itself for a ZRA Manager.
Prove a full shift before a single real receipt
The order carries the active ZRA environment as a badge of its own — blue for Sandbox, amber for Production — so a supervisor can tell at a glance whether a receipt in their hand is a real fiscal document or a test. The environment is set once on the company and points the whole suite at the VSDC URL you nominate for it, so you can run a complete trading day against the sandbox with zero fiscal impact and flip when you are satisfied. If the TPIN, branch, VSDC URL or device serial is not yet in place, orders are marked Not Configured with the missing fields named in plain words, instead of being silently dropped or fired at a device that would only reject them.
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 ZRA Smart Invoice Base holds your TPIN, branch (bhfId) and VSDC URL, runs the device init handshake and provides the resilient submission queue this app declares through. Install the Base first, then add POS.
What if the VSDC is down mid-shift?
The order is still paid and still printed. The declaration falls into the queue and is retried automatically on a widening back-off, and the receipt number and signature are attached the moment the VSDC answers — the cashier is never blocked.
Do I need a fiscal printer or a hardware device?
No. ZRA Smart Invoice is reached through a VSDC — a Java bridge you run on your own server, typically at http://localhost:8080/zravsdc — or through ZRA’s hosted OSDC. This connector POSTs JSON straight to whichever you were provisioned: your data goes to your own device, not through a third-party service.
Which VAT rate does it apply?
Zambia’s standard rate of 16%, on taxation-type code A. The full band set is supported — A Standard Rated, B Minimum Taxable Value, C1 Exports, C2 Zero-rating LPO, C3 Zero-rated by nature, D Exempt, RVAT Reverse VAT, E Disbursement and TOT Turnover Tax — and amounts are declared VAT-inclusive, as ZRA expects.
Any limits or subscription?
None. One-time purchase, unlimited orders and registers, and free updates on every ZRA Smart Invoice specification change.
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 |
•
Point of Sale (point_of_sale)
• Discuss (mail) • Inventory (stock) • Invoicing (account) |
| Community Apps Dependencies | Show |
| Lines of code | 1833 |
| Technical Name |
aminitech_zra_pos |
| 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