Invoice hash

By Matheel, from ZATCA's specifications and SDK 3.4.8 · Updated

The ZATCA invoice hash is the base64 SHA-256 of the invoice XML with the signature and QR removed and C14N11 applied. It becomes the next invoice's PIH.

The invoice hash is the document's fingerprint: the base64-encoded SHA-256 of the invoice XML. Change a single character after computing it, even whitespace, and the hash is different.

The official method, from the text of BR-KSA-26: remove ext:UBLExtensions, remove the cac:AdditionalDocumentReference whose cbc:ID is QR, remove cac:Signature, canonicalize with C14N11, hash with SHA-256 and base64-encode the result. You get a 44-character string such as z5F9qsS6…JgQ=.

The same value appears in four places: the DigestValue of the invoiceSignedData reference in the signature, tag 6 of the QR code, the invoiceHash field of the API request to ZATCA, and the PIH of the next invoice. ZATCA recomputes it from the document and rejects a mismatch, so the classic mistake is reformatting or reordering the XML after hashing and signing.

Matheel computes the hash with ZATCA's transforms, matching the SDK's samples byte for byte in our tests, and returns it as invoice_hash for you to send as the next previous_invoice_hash.

Example

<ds:Reference Id="invoiceSignedData" URI="">
    ...
    <ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
    <ds:DigestValue>z5F9qsS6oWyDhehD8u8S0DaxV+2CUiUz9Y+UsR61JgQ=</ds:DigestValue>
</ds:Reference>

FAQ

Why is the first PIH longer than an invoice hash?

The official first PIH is the base64 of the hash's hex text (88 characters); an invoice hash is the base64 of the raw 32 bytes (44 characters).

Do I hash before or after signing?

Either gives the same result, because the method strips the signature and QR first. What matters is not changing the rest of the document afterwards.

Related ZATCA rules

Related terms

Let Matheel handle this for you

Matheel signs the invoice, files it with ZATCA and keeps the counter and hash in one request, and returns the PDF with the QR.

Try Matheel, no signup Matheel API docs