TLV Encoding for QR Codes Under Oman’s E-Invoicing Mandate

The QR Code Requirement in Oman

For every electronic tax invoice, the supplier must generate and print a QR code, and the encoded content is carried as a Base64 string. That string is subject to a hard technical limit: it may not exceed 700 characters. This ceiling matters in practice, because it forces the encoded data to stay compact and disciplined, which is exactly what the TLV format is designed to achieve.

The QR code is not decorative. It is a machine-readable summary of the invoice's most important fields, allowing a buyer or the Oman Tax Authority (OTA) to scan and verify the document in seconds. When someone scans a compliant invoice, they are reading the TLV-encoded payload inside that QR code, decoded from Base64 back into its individual fields. If the encoding is malformed, the scan fails, and the invoice cannot be verified. That is why correct QR generation is not a cosmetic detail but a core compliance requirement under the Oman e-invoicing mandate.

What TLV (Tag-Length-Value) Encoding Is

TLV stands for Tag-Length-Value, and it is a compact, predictable way to pack multiple fields into a single binary string. Rather than relying on separators, headers, or fixed positions, TLV describes each field with three parts in sequence:

• Tag, one byte holding the numeric tag value that identifies which field this is.
• Length, one byte indicating the byte length of the UTF-8-encoded value that follows.
• Value, the actual UTF-8 text, which is variable in size.

The elegance of this approach is that a reader never has to guess where one field ends and the next begins. It reads the tag to learn what the field is, reads the length to learn how many bytes to take, then reads exactly that many bytes as the value. It then moves straight to the next tag and repeats the cycle until the string is exhausted. This makes the encoding both compact and completely unambiguous, which is why TLV is widely used for QR-based invoice verification across multiple tax jurisdictions.

A short worked example makes the pattern clear. Suppose the Seller Name field uses tag 3 and the name is "ABC TRADING LLC". The encoder writes the tag byte (3), then a length byte for the number of bytes in the UTF-8 value, then the value itself. The next field, the seller's VATIN under tag 4, follows immediately with its own tag, length, and value. Once every field is written this way, the full byte string is Base64-encoded and placed into the QR code, and a scanner simply reverses the process. Because every byte counts toward the 700-character ceiling, efficient encoding matters, which is one more reason the field set is tightly defined by invoice type.

The TLV Tag Mapping by Invoice Type

The fields included in the QR code, and the order in which they appear, depend on the invoice type. Under Oman's PINT-based model, the mapping follows a defined sequence that must be respected exactly.

For a simplified or full PINT invoice, the tags run in this order:

1. QR Version (Tag 1)
2. Invoice Type (Tag 2)
3. Seller Name (Tag 3)
4. VATIN of the Seller (Tag 4)
5. Date (Tag 5)
6. Time stamp (Tag 6)
7. Invoice total with VAT (Tag 7)
8. VAT total (Tag 8)
9. Seller UUID (Tag 9)

The Profit Margin PINT invoice follows the same order but consolidates two of the monetary fields. Instead of carrying the invoice total with VAT and the VAT total as separate entries, it uses a single Total amount due (Tag 7), which in turn shifts the Seller UUID to Tag 8. The logic is straightforward: a profit-margin scheme does not expose VAT in the same way as a standard taxable supply, so the field set adapts to reflect that.

Getting this order and these tag numbers exactly right is essential. Because TLV is read sequentially, a misplaced tag, an incorrect length byte, or a field in the wrong position will cause the entire QR code to be misread or rejected. There is no tolerance for "close enough" here; the encoding either reconstructs cleanly or it does not. The Seller UUID, which sits at the end of each sequence, is especially important, because it ties the QR code back to the underlying invoice data and is the field that makes tampering detectable.

How the QR Code and Seller UUID Work Together

The QR code and the Seller UUID are best understood as two halves of a single integrity system rather than as separate requirements.

The relationship runs in both directions. The invoice fields, including most of the TLV tags, are used to derive the Seller UUID through a deterministic, hash-based process. That UUID is then embedded back into the QR code as the final tag in the sequence. Because the UUID is generated from the content, any change to the underlying invoice produces a different UUID, and the embedded value no longer matches a fresh recalculation. In effect, the QR code carries its own proof of integrity.

The practical implication is clear: you cannot implement QR generation and UUID generation independently and hope they line up. They must be built together, with the same field values feeding both, so the QR code a customer scans genuinely reflects the invoice that was issued.

Common Errors and Why Validation Fails

Because the encoding is so precise, a handful of recurring mistakes account for most QR validation failures. Length bytes that do not match the actual UTF-8 byte count of the value are a frequent culprit, particularly when names or fields contain multi-byte characters. Encoding the character count instead of the byte count is a subtle but fatal error. Fields placed in the wrong tag order, or omitted entirely for a given invoice type, break sequential parsing. Exceeding the 700-character Base64 limit causes truncation. And a Seller UUID that was generated from a different field set than the one encoded in the QR code will fail any integrity recheck.

The takeaway is that QR generation for Oman e-invoicing is a precise technical task, not a formatting afterthought. An invoice that looks correct to a human can still fail machine validation if its TLV encoding is even slightly off, which is why this work belongs in a tested, purpose-built system.

It is also worth noting that the OTA has indicated the detailed QR specifications will continue to be confirmed as the Fawtara rollout progresses. Businesses should implement this defined structure while remaining ready to align with the authority's final published technical details.

Choosing an E-Invoicing Solution in Oman

As mandatory e-invoicing in Oman rolls out across phases, businesses in retail, manufacturing, logistics, construction, oil and gas, and trading all need a Fawtara compliant e-invoicing solution that handles Peppol exchange, OTA SMP integration, QR code and Seller UUID generation, and TDD reporting as one coherent system. Implementing these pieces in isolation is exactly where errors creep in. Implementing them together, validated end to end, is what produces invoices that pass on the first attempt.

Choosing an approved e-invoicing service provider in Oman that has passed the Oman Test Suite is the most reliable way to ensure compliance from day one. A provider that has already validated its QR, UUID, and TLV implementation on the testbed removes the guesswork and the risk of rejected invoices once the mandate takes effect for your business. For B2B and B2G transactions alike, that readiness is the difference between a smooth go-live and a scramble.

Why Businesses Trust SMARTeIS

Getting a QR code right under the Oman mandate comes down to small details done correctly, every time. The tags must be in order, the lengths must match, and the Seller UUID must line up with the invoice it represents. Miss any of these and the invoice fails. For most businesses, building and testing all of this in-house is more effort than it is worth.

SMARTeIS by Skill Quotient Technologies removes that burden. As an OTA pre-approved, Peppol-certified provider, it generates QR codes and Seller UUIDs to specification, handles Peppol exchange and OTA reporting, and checks each invoice before it goes out, all validated against the Oman Test Suite. With integration across 150 plus ERP and POS systems, it gives businesses of every size a foundation they can rely on.

Let our team walk you through how SMARTeIS can support your compliance goals.