Egypt's Tax Authority (ETA) requires many businesses to report every retail sale as an electronic receipt. For a POS that means three hard problems: the receipt ID is a hash of text the authority rebuilds on its side, so one character of difference breaks it; totals must add up to the piastre after discounts and VAT; and a send interrupted by the network cannot simply be retried. We built one engine for this and ship it in two products, ELKASHIER Cloud (shops and salons) and Curava (clinics). This article covers what it does, how we tested it, and, plainly, what is not certified yet.
Status, first
- Built and deployed: the module has been in production in both products since 10 November 2026, switched off for every business. On 22 November both production databases hold zero e-receipt settings and zero receipts.
- Not certified: it has never talked to the authority's systems, not even the pre-production one. That step needs a taxpayer's own pre-production and POS credentials, which only the business can obtain and type in. Until then, a handful of behaviours can only be confirmed against the real pre-production API.
- Tested: against the authority's published serialization example, against our real pricing engine, and end to end against a practice server we wrote to behave like the API.
TL;DR
- The receipt UUID is SHA-256 of the authority's "canonical" text of the receipt. We never format a number twice: every amount is a decimal string built once from integer piastres, and the same characters go into the hash and the JSON.
- Each line's VAT and discount are rebuilt from what the invoice already froze, using a largest-remainder split, and the receipt must equal the invoice total exactly or it is not built.
- The sender marks a batch "unsure" before the request leaves. After a crash or timeout it asks the authority whether it has the receipt instead of sending it again.
- Checkout only queues; a background worker sends, so the tax system can never fail a sale.
The problem
The ETA e-receipt (document version 1.2 in our build) is a JSON document: header, seller and branch, buyer, lines, totals, payment method. Each receipt carries the previous receipt's UUID from the same device, forming a chain, and a return points at its sale. The UUID is the SHA-256 of a serialization the authority defines and recomputes from the JSON you send.
The serialization is simple to describe: a value becomes "value"; an object becomes each property name in upper case followed by its value; an array property writes its name once, then the name again before every element. Our implementation is about fifteen lines:
export function canonical(v) {
if (v instanceof Num) return `"${v.raw}"`;
if (typeof v === "string") return `"${v}"`;
let out = "";
for (const [k, val] of Object.entries(v)) {
if (val === undefined) continue;
const name = `"${k.toUpperCase()}"`;
if (Array.isArray(val)) { out += name; for (const el of val) out += name + canonical(el); }
else out += name + canonical(val);
}
return out;
}
Why the obvious approach fails
The obvious approach is to build an object with numbers, hash its canonical form, then JSON.stringify it. That breaks quietly: 150.50 and 150.5 are the same number but different text; floating-point VAT produces long tails of nines; a quote in an item name is escaped in the JSON but not in the canonical string. Each time the authority hashes different characters from yours and rejects the UUID, with nothing on your side that looks wrong.
The second trap is money. A POS discounts and taxes the whole bill; the authority wants net sale, discount, tax and total per line, adding up to the totals. Recomputing each line with rounding drifts a piastre away from the till.
What we built
1. Numbers are text, written once
Money in both products is stored as integer piastres. A small Num class holds a decimal as a string in its shortest form, built directly from integers: dec(15050, 2) is "150.5", dec(1400, 2) is "14". The canonical text and the JSON writer both print v.raw; there is no second formatting step to disagree with the first. Text fields go through a clean() function that removes control characters, quotes and backslashes before anything is hashed, and the JSON writer refuses any string that would still need escaping.
The tests serialize the authority's published sample (read with a parser that keeps numbers exactly as written) and compare it with the authority's published canonical text, character for character.
2. Lines rebuilt from the frozen invoice
The receipt builder is a pure function: invoice in, receipt out, no database, clock or network. It takes the line totals and each line's share of the discount as the invoice already recorded them, splits the invoice's VAT across lines by largest remainder, and handles three pricing modes (prices without VAT, VAT on top, VAT included in the price). Then it checks:
const totalAmount = sum(items.map((x) => x.total));
if (totalAmount !== inv.totalMinor) throw new EtaBuildError("mismatch", ...);
A receipt that does not match the invoice to the piastre is not sent; it is shown to the owner with the reason. The fuzz test drives 4,000 random carts per run through the real pricing engine (one to six lines of services and products, no, fixed or percentage discounts, loyalty redemptions, VAT off, on top or included, at four rates) and asserts that every receipt it builds balances and that its UUID is the hash of the exact text that would be sent.
The builder also refuses what it cannot report honestly: a sale of 150,000 EGP or more needs the buyer's national ID, which the products do not collect, so the owner is told that case is not supported yet. The buyer is otherwise sent as an anonymous walk-in person: no name or phone leaves the system.
3. A sender that never sends twice blindly
Checkout only writes an invoice. A worker runs every 30 seconds (and immediately after a sale) and does three things: creates any receipt that is due, sends each device's queue in issue order, and asks the authority for verdicts. One sender per device is enforced with a PostgreSQL advisory lock, so two app instances cannot interleave a chain.
The important rule is about unknown outcomes. Before a batch leaves, its rows are marked unsure in the database. If the reply never comes (timeout, network error, process killed), the next pass does not resend; after a short wait it asks the authority for that receipt's details. If the authority has it, it is marked submitted; only if the authority definitely does not have it does it go out again. The authority treats a second copy as a duplicate, so a blind retry would both be refused and leave us unsure which copy counted.
Other replies: a refused multi-receipt envelope is resent one by one to find the bad receipt; rate limiting waits slightly longer than Retry-After; bad device credentials pause that device and say so on the owner's page; a return waits until its sale is confirmed valid; verdict polling is paced per device.
4. Credentials sealed, environments separated
Each branch is one registered POS with its own credentials, stored encrypted, opened only inside the client module and never logged. Tests can redirect only the pre-production endpoints to the practice server; nothing can point the live environment anywhere else.
A bug the end-to-end test caught
The end-to-end script starts the built app with a practice ETA server on loopback and runs real sales, voids and returns through the app's API. It found that card payments were being reported with payment code O ("other") instead of V (bank card). The mapping read the method's name from a field that, on that query, was called pay_name, so the name was empty and the "looks like a card" rule never matched. Unit tests passed because they built the object by hand; only a test through the real query found it.
Measured result
- Unit suite: 85,348 checks, 0 failures, in both ELKASHIER Cloud and Curava, run on 22 November 2026.
- End to end against the practice server: 160/160 in both products on 10 November 2026.
- Production: deployed, off for everyone, zero receipts sent; the pre-production run with a real taxpayer's credentials comes before any business switches it on.
Checklist if you are building this yourself
- Keep money as integers to the end. Turn it into text exactly once, and use that same text for the hash and the payload.
- Test your canonical serializer against the authority's own published example, byte for byte.
- Rebuild lines from what the invoice froze; never recompute prices. Refuse to send a receipt that does not equal the invoice.
- Mark a send as uncertain before it leaves. After a failure, ask before resending.
- One sender per device chain. Returns wait for their sale.
- Never let the tax system block a sale, and make it impossible for tests to reach the live environment.
- Run at least one test through your real database queries, not hand-built objects.
Need this?
The e-receipt engine ships inside ELKASHIER Cloud for shops and salons and inside Curava for clinics, ready for the pre-production run as soon as a business has its credentials. If you run a POS or clinic system in Egypt and need e-receipts built in, talk to GeoTech.