Payment means code (BT-81) not in ZATCA's subset of UNTDID 4461

What does this mean?

The element is cac:PaymentMeans/cbc:PaymentMeansCode (BT-81): a code for how the payment is expected to be, or has been, settled. ZATCA's Data Dictionary marks it optional on every type of document. The rule's condition is that the code exists; once it does, the rule checks one thing, that the value belongs to the subset.

The subset as ZATCA last printed it was a table in its XML Implementation Standard: 10 In cash, 30 Credit, 42 Payment to bank account, 48 Bank card, and 1 Instrument not defined (Free text). The labels are ZATCA's own.

One thing to know before you build on that table. The tracked-changes edition of version 1.2 of the standard, dated 2023-05-19, shows it struck out. The clean version 1.2 now says only that the code comes from a subset of UN/CEFACT code list 4461, D.16B, and the Data Dictionary of the same date does not list the values either; its example for BT-81 is 30. We read each rule's message and severity, not the test behind it, so we cannot tell you whether the validator accepts anything beyond those five. They are the values ZATCA itself published, which makes them the safe choice.

The same cac:PaymentMeans block carries the reason for a credit or debit note: KSA-10 is its cbc:InstructionNote. That reason is required by BR-KSA-17, an error, and BR-49 from EN 16931, which the standard carries, requires a payment instruction to state its code. So in practice a note carries this block, and a code in it.

It is a warning: the document is accepted and the warning is recorded with it.

Why does it happen?

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

• The payment method's name sent instead of a code: cash, card or bank transfer, or the internal key that the point of sale or the ERP uses for the method.
• The note reason written into cbc:PaymentMeansCode instead of cbc:InstructionNote. The code fails here, and the note loses the reason BR-KSA-17 requires.
• A code from the wider UNTDID 4461 list that is not among the five ZATCA published, carried over from a European template or a general code table.
• The right code in a form that is not the code: 010, or 10.0 from a value that passed through a number type on its way into the XML.

How to fix it

4 steps, then send the invoice again.

1. 1
   Map your payment methods to codes explicitly

   Keep a small table in the integration from your own payment methods to the published codes: cash to 10, a transfer to the seller's bank account to 42, a card payment on any network to 48, a sale on credit terms to 30, which ZATCA labels Credit, and 1 where none of them describes the case. Never pass a method's name or your internal key straight through.

2. 2
   Keep the note reason in its own element

   On a credit or debit note, cac:PaymentMeans holds both: the code in cbc:PaymentMeansCode and the reason in cbc:InstructionNote. Write each to its own element. The reason, and what it should say, is covered in BR-KSA-17.

3. 3
   Write the code as text

   Emit the code as a literal string from your table, 10 and not 10.0 or 010, without passing it through a numeric type or a formatter on the way.

4. 4
   Check before you widen the list

   Because version 1.2 of the standard no longer prints the values, confirm on zatca.gov.sa before you map any method to a code outside the five ZATCA published.

This code does not block acceptance, so the invoice you have is compliant. Correct the data so the warnings disappear from future invoices.

Frequently asked questions