Skip to main content

The Fawtara QR code

QR Code Requirements (Fawtara)โ€‹

Oman requires a QR code on B2C invoices โ€” full or simplified โ€” so the copy the consumer is given can be verified offline. It is defined in the Oman Solution Reference Architecture v1.0.3, section 4.2 and Appendix D. B2B invoices carry no QR: the code asserts a B2C invoice type and a Seller UUID that exist only for the consumer flow.

TLV fields โ€” B2C invoice (Table 5)โ€‹

TagFieldSourceExample
1QR versionfixed1.1
2Invoice typefixed, B2C01
3Invoice numberIBT-001INVOICE-01
4Seller nameIBT-027ุจุงุฆุน
5Seller VATINIBT-031OM1234567891
6Invoice dateIBT-002, YYYY-MM-DD2026-05-13
7Invoice timeIBT-168, HH:MM:SS18:31:00
8Total with VATIBT-112302.340
9VAT totalIBT-11014.520
10Seller UUIDBTOM-004, UUIDv5454cb7ea-f1f7-5b69-9e0b-756f002efa52

TLV fields โ€” profit-margin invoice (Table 6)โ€‹

A profit-margin B2C invoice carries invoice type 02, no VAT total, and the total amount due (BTOM-020) at tag 8. The Seller UUID moves to tag 9, so the code has nine tags.

Seller UUID (BTOM-004)โ€‹

A version 5 UUID in namespace e0bc4ac8-b025-46e5-a76d-0c893fc3027e over the other fields, joined with | and upper-cased (Appendix D.1):

1.1|01|INVOICE-01|ุจุงุฆุน|OM1234567891|2026-05-13|18:31:00|302.340|14.520

For a profit-margin invoice the VAT total is left out of the seed. The same value is carried as BTOM-004 in the UBL, so the document and its QR cannot disagree.

TLV encodingโ€‹

Each field is tag (1 byte) + length (1 byte) + value (UTF-8 bytes). The length is the byte length of the UTF-8 value, not the character count: the four-letter Arabic name above has length 8. The concatenated bytes are base64-encoded, and the result must not exceed 700 characters.

01 03  1.1
02 02  01
03 0a  INVOICE-01
04 08  <8 bytes of UTF-8 Arabic>
05 0c  OM1234567891
06 0a  2026-05-13
07 08  18:31:00
08 07  302.340
09 06  14.520
0a 24  454cb7ea-f1f7-5b69-9e0b-756f002efa52

QR embedding in UBLโ€‹

The QR data is stored in an AdditionalDocumentReference with ID QR:

<cac:AdditionalDocumentReference>
    <cbc:ID>QR</cbc:ID>
    <cac:Attachment>
        <cbc:EmbeddedDocumentBinaryObject mimeCode="text/csv" filename="QR">
            AQMxLjECAjAxAwpJTlZPSUNFLTAx...
        </cbc:EmbeddedDocumentBinaryObject>
    </cac:Attachment>
</cac:AdditionalDocumentReference>
Whether GoRoute adds the QR depends on how you send the document

Documents GoRoute renders for you โ€” POST /api/v1/invoices, drafts, the ERP connectors, the pollers and the retail and POS counters. GoRoute composes the UBL and, when the invoice is B2C, builds the QR from the finished document and embeds it. A value of yours that GoRoute writes as a reference ID cannot be QR or HASH (in any case, with or without spaces), since those are the IDs of the QR code and hash GoRoute adds: a supporting document's ID (BUS_025), a credit note's project_reference, or a prepayment invoice's prepayment_invoice_number โ€” or its number when no prepayment number is given (BUS_027, against that field). POST /api/v1/invoices, /validate and /preview-xml answer with the validation error, a CSV or Excel import rejects the row, and the connectors park the invoice with the same sentence. An invoice's own project reference is written as cac:ProjectReference, not as a reference ID, and is not restricted. Only a reference with the QR embedded, as above, ever counts as the QR.

Documents you submit as final UBL โ€” POST /api/v1/documents. The XML is transmitted exactly as you submitted it, and no QR is added. If your B2C invoice needs one, embed it before you submit.

That difference is deliberate: altering a final document would leave the copy you archive different from what was transmitted and reported.

Last updated on