Invoice currency code (BT-5) is not an ISO 4217 code

What does this mean?

The element is cbc:DocumentCurrencyCode at invoice level. The alphabetic ISO 4217 codes are exactly three capital letters: SAR, USD, EUR, AED. The check is on the value's membership of that list and nothing else — not on what you sell, not on who you sell it to, not on whether the amounts are right.

A currency symbol is not a currency code. SR, the Arabic abbreviation, the word Riyal and the riyal sign are all names for the money on a printed document; none of them is a value in ISO 4217. Only the three letters go in this field.

The standard also has a numeric form — 682 for the riyal — which is another representation of the same currency. What we read from the compiled schematron is the text of each rule and its severity, not the test that fires it, so we cannot tell you how a numeric value is treated here. Every ZATCA example writes the three letters, so write them.

This rule and its sibling BR-KSA-CL-02 are two halves of one question: this one asks whether the value is valid, that one asks whether the whole document repeats it. A file that writes EUR in the header and SAR on one line passes here and fails there. And there is a third, entirely different field: the tax accounting currency (BT-6), whose existence is required by BR-KSA-68 and whose value is pinned to SAR by BR-KSA-EN16931-02.

Why does it happen?

Ordered from the most common to the least — your cause is most likely the first or the second.

• A point of sale or a template that prints the currency symbol on the page and passes the same string into the XML.
• Lower case, from a database column holding sar.
• The currency name rather than its code — Saudi Riyal — taken from a settings field meant for display.
• An element emitted empty, or holding whitespace, from a mapping whose source value was null. No value is not a value in ISO 4217.
• An invented or four-letter code: SAUD, SRL, RS.
• A language or region tag picked up from a formatting library: ar-SA.

How to fix it

3 steps, then send the invoice again.

1. 1
   Write the three letters

   cbc:DocumentCurrencyCode with the value SAR, in capitals and with no surrounding whitespace. Write it as a constant in code rather than a setting read from the establishment: a Saudi invoice is in riyals and there is nothing here to derive — and every field that is derived is a field that can be wrong.

2. 2
   Separate the presentation from the field

   The symbol, the name and the abbreviation all belong to the printed document; this field is a value from a closed list read by a machine. One string cannot serve both, and that conflation is the root of this code: a settings field called currency used once for printing and once for export.

3. 3
   Then check consistency and the tax currency

   Once the value is valid, two questions remain. Does every currencyID attribute on the amounts repeat it — that is BR-KSA-CL-02. And does the document carry a tax accounting currency of SAR — that is BR-KSA-68 and BR-KSA-EN16931-02. How to read a whole rejection response is in ZATCA error codes explained.

Once corrected, send the invoice again. A rejected invoice was never recorded with the Authority, so it needs no credit note — send the corrected invoice itself.

Frequently asked questions