What Phase 2 integration actually asks of your clinic
Phase 1 was a QR code printed on the invoice. Phase 2 is a different thing: the invoice becomes a signed document, chained to the one before it, that reaches the tax authority by itself. This guide covers what changes at the front desk, how onboarding works step by step, and the one question to put to your vendor before anything else — can reception still issue an invoice when the authority is unreachable?
The first question a clinic manager asks after the letter naming their wave and their compliance date is not a technical one: will the front desk stop issuing invoices on the day we switch this on? The worry is reasonable. Everything written about Phase 2 talks about a direct link to an external authority, and anything standing between a patient and their invoice at the desk becomes a queue within minutes.
The correct answer is that billing should not stop, not for a second. But getting there depends on an architectural decision inside the system you use, not on your luck with the clinic's internet. This guide covers what Phase 2 genuinely changes, how onboarding runs, and where it usually goes wrong. For the programme itself and the difference between the two invoice types, start with the clinic e-invoicing guide.
What Phase 2 adds to what you already have
Phase 1 — which your clinic has been running for years — means the invoice is generated electronically and carries a QR code holding five fields: seller name, VAT number, timestamp, total including VAT, and the VAT amount. The code exists so an inspector can read it off the paper with a phone. It goes nowhere.
Phase 2 changes what an invoice is. It becomes a structured document in a defined format, with a cryptographic hash computed over it, linked to the invoice issued before it, and signed with a private key whose certificate the authority issues to your issuing device — and then it reaches the authority. The invoice stops being a sheet you print and becomes a document you sign.
| Invoice type | When it reaches the authority | Deadline |
|---|---|---|
| Simplified — patient paying for themselves | After it is issued and handed over | Within 24 hours (reporting) |
| Standard — a registered business buyer | Before it is handed to the buyer | Before issue (clearance) |
That table is the most important thing on this page, because it decides what the working day looks like. The overwhelming majority of clinic invoices are simplified — an individual patient paying for themselves — and reporting them is after the fact: the window is twenty-four hours, and nothing waits on the authority at the desk. Clearance in advance applies to standard invoices raised for a registered business, which is the case for a clinic contracted to screen a company's staff. If your system raises invoices against a patient and holds no buyer VAT number anywhere, it is a simplified-invoice system by design — and the certificate the authority issues carries that limit and refuses anything else.
Onboarding: a one-time code and three sample documents
Switching this on is not a toggle your vendor flips for you. It is an exchange between your system and the authority that ends with a digital certificate bound to an issuing device in your clinic. These are its four steps as they actually run:
Complete the clinic's own details first
The VAT number — fifteen digits beginning and ending with a three — and the full national address: street, building number, district, city, and postal code. The authority requires it on every invoice, and one missing field stops everything later. A good system blocks onboarding and names the missing fields, rather than accepting them and failing on the first real invoice.
A one-time code from the Fatoora portal
You sign in to your own establishment's account on the portal and request a code. It is single-use and expires within about an hour, which is what makes onboarding an act the clinic owner performs rather than a third party. No vendor can fetch that code for you, and any vendor asking for your portal credentials is asking for more than the job needs.
A signing key and a certificate request
A private key is generated for the issuing device, and from it a certificate request carrying your VAT number, the establishment name, and the invoice types allowed. That private key is your clinic's identity to the tax authority, and its correct home is encrypted inside the system — not a file on the reception PC.
Three sample documents, then the certificate
Before anything is saved, three documents — an invoice, a credit note, and a debit note — are built by the same code that will issue your real invoices, signed by the same key, and sent to the authority's compliance endpoint. The production certificate is requested, and settings written, only if all three are accepted. If one fails, your configuration is left exactly as it was.
Why the sample-document step is the real guarantee
Any internal test at the vendor proves the document matches the specification as understood by whoever wrote the code. None of it proves the authority's own validator computes the same hash over the same bytes and accepts this form of signature. Those three documents are the only proof available before the first real invoice — which is why they should be a precondition of switching on, not an optional step afterwards.
The chain: why invoice order is now a compliance matter
Under Phase 2 no invoice stands alone. Each one carries a sequential counter and the hash of the invoice before it, forming a linked chain: invoice one hundred carries ninety-nine's hash, ninety-nine carries ninety-eight's, back to the first one issued after onboarding. The authority can verify that nothing was removed from the middle.
The practical consequence is blunt: a broken chain cannot be repaired retroactively. An invoice that has taken its place and later turns out to be wrong cannot be pulled out of the order, because the one after it carries its hash. This is why a correct system gives no chain position to an invoice whose document failed to build — a blocked invoice stays outside the ordering entirely until its cause is fixed, so the chain stays gapless across failures.
Deleting was an accounting error; now it is a broken chain
Deleting an issued invoice was always prohibited — corrections go through a credit or debit note referencing the original. Phase 2 sharpens it: a deleted invoice was not just a number in a ledger, it was a link whose hash the next link carries. If your system still lets a receptionist delete an invoice, fix that before onboarding rather than after.
When the authority refuses a document, or cannot be reached
Here is the question to put to your vendor in exactly these words: can reception issue an invoice and hand it to the patient while the authority's service is unavailable? The only correct answer is yes. A simplified invoice has twenty-four hours to be reported, so a submission that did not land is queued, not late, and its right home is a background retry queue. A system that makes invoice issue wait on an external response has tied your clinic's revenue to a network connection.
And there are two kinds of failure that must never be conflated: a connection that did not go through, which should simply be retried; and a rejection after the authority has read the document, where re-sending the same bytes burns the window for nothing because it will be refused again for the same reason. The second needs a person. A system that does not separate them hides the case that needs your attention inside the case that does not.
A system that respects your clinic refuses what it cannot build rather than guessing, and names the reason in a sentence a staff member can act on. The common ones:
- An incomplete national address: one field — a postal code, a building number — is enough for the document to be refused. It should surface at onboarding, not on the first invoice.
- An invoice in a currency other than the riyal: the document is built for Saudi riyals, and another currency is not a case to guess at.
- An invoice with no VAT and no recorded exemption reason: the authority wants the reason stated, and if the system has nowhere to record one, refusing is more honest than filing something incomplete.
- A line whose total does not match quantity times unit price: an arithmetic error that passes on a printout and does not pass a validator.
A refusal is not the end of the story either. A system that records the reason and has nothing that can ever act on it leaves the clinic reading a list of unfiled invoices it cannot do anything about — which is worse than not having the list. Two things need to exist: a periodic sweep that automatically retries recently blocked invoices once the data that blocked them is corrected, and an explicit button that retries everything that has piled up in one go.
The QR code grows, and it still has to scan
One last detail that is missed in every demo and shows up on the first batch of printed invoices: the Phase 2 code is much larger than its predecessor. The Phase 1 code carries five short fields. The Phase 2 one carries nine, among them the document hash, the signature, the public key, and the certificate's signature — several times the content, packed into a far finer grid of modules.
Because the content multiplied, printing the code at the old size drops each module below what a phone camera can resolve, producing a code that does not scan on paper — a defect that never appears on screen. The print size has to be computed from the code's own module count rather than fixed, particularly since that count shifts with the length of the registered establishment name. Ask your vendor for an invoice printed on real paper and scan it with an ordinary phone before you switch anything on.
A checklist before you press enable
- Clinic details complete: a valid VAT number and a national address with every field filled.
- An explicit confirmation from the vendor that invoice issue never waits on the authority.
- Onboarding runs through sample documents the authority accepts, with nothing written before they are.
- A screen listing blocked invoices with their reasons, and a button that retries them.
- The private key stored encrypted inside the system, never sent to a browser or a device.
- An invoice printed on paper and scanned with a phone before the new code goes live.
- A plan to test against the sandbox environment first, then move to production.
Saudi billing, from the front desk to the authority
Invoices carry the Phase 1 QR as soon as your VAT number is saved, and Phase 2 integration is there for the clinics that need it — with nothing in it that can stop an invoice being issued.
See what the system does