BR-KSA-27 📱 QR Code & TLV Encoding error

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

BR-KSA-27: رمز الاستجابة السريعة (QR Code / KSA-14) مفقود أو غير مطابق

Official ZATCA Specification:

The document must contain a QR code (KSA-14), and this code must be base64Binary encoded TLV containing all mandatory tags.

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

📌 Overview & Impact

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

الوصف بالعربية: يجب أن تحتوي الفاتورة على رمز QR مشفر بنظام Base64 ومبني بترميز TLV وفق متطلبات المرحلة الثانية من هيئة الزكاة.

⚠️ Common Causes for Rejection

  • ✕ Missing <cac:AdditionalDocumentReference> with <cbc:ID>QR</cbc:ID>
  • ✕ QR string is URL or plain text instead of Base64-encoded TLV bytes
  • ✕ Missing Phase 2 TLV Tags: Tag 5 (ECDSA Signature), Tag 6 (Public Key), or Tag 7 (Certificate Signature)
  • ✕ TLV byte lengths encoded as ASCII numbers rather than raw byte counts

✅ How to Fix & Resolve

1

Encode All 9 TLV Tags

Build TLV buffer: Tag 1 (Seller Name), Tag 2 (VAT No), Tag 3 (Timestamp), Tag 4 (Invoice Total), Tag 5 (VAT Total), Tag 6 (Invoice Hash), Tag 7 (ECDSA Signature), Tag 8 (ECDSA Public Key), Tag 9 (ZATCA Stamp).

2

Convert to Base64 String

Convert the concatenated binary TLV buffer to a Base64 string and embed inside the QR document reference node.

💻 Code Comparison: Invalid vs Compliant UBL 2.1 XML

❌ Invalid XML (Rejected by ZATCA) Invalid Payload 
<cac:AdditionalDocumentReference>
  <cbc:ID>QR</cbc:ID>
  <cac:Attachment>
    <cbc:EmbeddedDocumentBinaryObject mimeCode="text/plain">https://example.com/invoice/123</cbc:EmbeddedDocumentBinaryObject>
  </cac:Attachment>
</cac:AdditionalDocumentReference>
✓ Valid XML (Compliant UBL 2.1) Valid Payload 
<cac:AdditionalDocumentReference>
  <cbc:ID>QR</cbc:ID>
  <cac:Attachment>
    <cbc:EmbeddedDocumentBinaryObject mimeCode="text/plain">AQhNZXJjaGFudAIPMzAwMDAwMDAwMDAwMDAzAxgyMDI2LTA4LTI5VDE0OjMwOjAwWgQFMTAwLjAFATE1LjA=</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 is the difference between Phase 1 and Phase 2 QR codes?

Phase 1 QR codes only required tags 1-5 (Seller Name, VAT Number, Timestamp, Total, VAT Amount). Phase 2 requires ECDSA cryptographic tags (Tags 6-9) for tamper-evident verification.

🔗 Related ZATCA Rules

BR-KSA-26

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).

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