INVALID-INVOICE-HASH: Cryptographic Invoice Hash Mismatch
خطأ هاش الفاتورة غير صالح: عدم تطابق بصمة الفاتورة الرقمية
ZATCA clearance/reporting engine validates the SHA-256 digest of the canonicalized UBL 2.1 invoice XML. If characters, whitespace, or transforms deviate, hash validation fails.
/ubl:Invoice/ext:UBLExtensions/.../ds:DigestValue 📌 Overview & Impact
The generated SHA-256 digest of the canonicalized invoice does not match the hash verified by ZATCA validator.
⚠️ Common Causes for Rejection
- ✕ Failing to exclude <ext:UBLExtensions>, QR DocumentReference, and <cac:Signature> nodes before canonicalization
- ✕ Using non-C14N11 canonicalization (e.g. basic XML string serialization)
- ✕ Operating system line-ending differences (CRLF \r\n vs LF \n)
- ✕ Modifying any invoice field after computing the hash
✅ How to Fix & Resolve
Follow ZATCA Transform Steps Exactly
1. Remove UBLExtensions. 2. Remove QR AdditionalDocumentReference. 3. Remove Signature. 4. Canonicalize XML with C14N11. 5. Hash binary with SHA-256. 6. Base64 encode.
Enforce UTF-8 & LF Line Endings
Ensure all XML processing operates strictly in UTF-8 encoding with standard Unix LF (\n) line breaks.
💻 Code Comparison: Invalid vs Compliant UBL 2.1 XML
// Anti-pattern: Hashing the full XML directly without transforms
const hash = crypto.createHash('sha256').update(fullXmlString).digest('base64');// Best practice: Transform, canonicalize, then hash
const cleanedXml = stripSignatureNodes(rawXml);
const canonicalXml = c14n11Canonicalize(cleanedXml);
const invoiceHash = crypto.createHash('sha256').update(canonicalXml, 'utf8').digest('base64');Verify Your Invoice XML Online
Use Qeemah's free developer tools to inspect transforms, C14N digests, and Phase 2 QR codes.
❓ Frequently Asked Questions
Can I test my invoice hash before sending to production?
Yes! Use Qeemah's free ZATCA XML Viewer & Hash Validator tool to verify your XML transforms, canonicalization, and SHA-256 digests instantly.
🔗 Related ZATCA Rules
BR-KSA-26: Invalid Previous Invoice Hash Calculation (PIH / KSA-13)
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).
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.
Stop Fighting Cryptic ZATCA XML Errors
Qeemah handles Phase 2 e-invoicing, cryptographic signing, and real-time clearance automatically. Integrate in minutes.