BR-KSA-26 🔐 Cryptography, Hash & Security error

BR-KSA-26: Invalid Previous Invoice Hash Calculation (PIH / KSA-13)

BR-KSA-26: خطأ في احتساب هاش الفاتورة السابقة (PIH / KSA-13)

Official ZATCA Specification:

If the invoice contains the previous invoice hash (KSA-13), this hash must be base64 encoded SHA256 computed according to the transforms block. For the first invoice, the hash must be 'NWZIY2ViNjZmZmM4NmYzOGQ5NTI3ODZjNmQ2OTZjNzljMmRiYzIzOWRkNGU5MWI0NjcyOWQ3M2EyN2ZiINTdIQ=='.

XPath Context: /ubl:Invoice/cac:AdditionalDocumentReference[cbc:ID='PIH']/cac:Attachment/cbc:EmbeddedDocumentBinaryObject

📌 Overview & Impact

Previous invoice hash (KSA-13) must be Base64-encoded SHA-256 digest of the canonicalized previous invoice XML (or the standard zero seed for the 1st invoice).

الوصف بالعربية: يجب أن يكون هاش الفاتورة السابقة (KSA-13) مشفراً بـ Base64 لترميز SHA-256 للفاتورة السابقة، أو الهاش المبدئي الصفري للفاتورة الأولى.

⚠️ Common Causes for Rejection

  • ✕ Broken invoice hash chain on the EGS device
  • ✕ Using wrong initial zero-seed hash for the first invoice on a CSID
  • ✕ Hashing the signed XML instead of canonicalized unsigned XML
  • ✕ Whitespace, formatting, or newline variations altering the SHA-256 digest

✅ How to Fix & Resolve

1

Use Official First Invoice Seed

For invoice #1 on a device, set PIH to 'NWZIY2ViNjZmZmM4NmYzOGQ5NTI3ODZjNmQ2OTZjNzljMmRiYzIzOWRkNGU5MWI0NjcyOWQ3M2EyN2ZiINTdIQ=='.

2

Apply C14N Canonicalization

Remove UBLExtensions, QR DocumentReference, and Signature nodes, canonicalize with C14N11, compute SHA-256, and encode in Base64.

3

Store Hash in Database for Chaining

Persist each invoice's generated hash in your DB to provide as the PIH for the next sequential invoice.

💻 Code Comparison: Invalid vs Compliant UBL 2.1 XML

❌ Invalid XML (Rejected by ZATCA) Invalid Payload 
<cac:AdditionalDocumentReference>
  <cbc:ID>PIH</cbc:ID>
  <cac:Attachment>
    <cbc:EmbeddedDocumentBinaryObject mimeCode="text/plain">0</cbc:EmbeddedDocumentBinaryObject>
  </cac:Attachment>
</cac:AdditionalDocumentReference>
✓ Valid XML (Compliant UBL 2.1) Valid Payload 
<cac:AdditionalDocumentReference>
  <cbc:ID>PIH</cbc:ID>
  <cac:Attachment>
    <cbc:EmbeddedDocumentBinaryObject mimeCode="text/plain">NWZIY2ViNjZmZmM4NmYzOGQ5NTI3ODZjNmQ2OTZjNzljMmRiYzIzOWRkNGU5MWI0NjcyOWQ3M2EyN2ZiINTdIQ==</cbc:EmbeddedDocumentBinaryObject>
  </cac:Attachment>
</cac:AdditionalDocumentReference>

Verify Your Invoice XML Online

Use Qeemah's free developer tools to inspect transforms, C14N digests, and Phase 2 QR codes.

Inspect XML & Hash → Decode QR Code →

❓ Frequently Asked Questions

What happens if our database loses the last invoice hash?

Breaking the hash chain invalidates future invoices on ZATCA portal. You must query the last accepted invoice from ZATCA or re-onboard the EGS device if unrecoverable.

🔗 Related ZATCA Rules

BR-KSA-27

BR-KSA-27: Mandatory QR Code (KSA-14) Missing or Malformed

The document must contain a Base64-encoded TLV QR Code (KSA-14) formatted according to ZATCA Phase 2 security specifications.

INVALID-INVOICE-HASH

INVALID-INVOICE-HASH: Cryptographic Invoice Hash Mismatch

The generated SHA-256 digest of the canonicalized invoice does not match the hash verified by ZATCA validator.

Stop Fighting Cryptic ZATCA XML Errors

Qeemah handles Phase 2 e-invoicing, cryptographic signing, and real-time clearance automatically. Integrate in minutes.

Start Free Trial Now → Browse All ZATCA Error Codes