ZATCA Phase 2 rejections: the most common errors and how to fix them (SAP Business One)

First, know which flow failed

Phase 2 has two flows, and a rejection means different things in each.

ZATCA’s response separates errors from warnings. An error rejects the document. A warning comes with an accepted document. In a real NOT_CLEARED response you will see a validationResults block with a code, a category and a message, for example:

BR-KSA-39: The invoice must contain the seller VAT registration number (BT-31) and/or seller group VAT registration number (KSA-18).

The rule code at the start is what you search for. Almost every rejection points back to one of the groups below.

1. Buyer address fields (B2B)

This is the most common one we see in SAP Business One.

The XML standard requires a buyer postal address on every invoice except simplified invoices and their notes (rule BR-10). On top of that, BR-KSA-63 says that when the buyer country is SA, these fields are mandatory: street name, building number, postal code, city, district and country. Address rules also expect a 4-digit building number and a 5-digit postal code.

In SAP B1, the customer’s bill-to address often has a street and city but no district, or the building number is typed into the street line. Which SAP field maps to which ZATCA field depends on your integration, so check its mapping document.

Fix: clean the bill-to addresses of all Saudi customers before go-live, and add a check in SAP B1 so a sales invoice cannot be added for a Saudi B2B customer with an empty district or a postal code that is not 5 digits.

2. VAT number format

BR-KSA-44 checks the buyer VAT number when it is present and the invoice is not an export: it must be 15 digits, starting and ending with 3. In SAP B1 this usually comes from the Federal Tax ID on the business partner. Spaces, dashes, a missing digit or an old CR number in that field will fail.

For export invoices the rule is the opposite: BR-KSA-46 says the buyer VAT number must not be sent.

Standard invoices still need a buyer identifier when the buyer has no VAT number. ZATCA accepts other ID schemes such as commercial registration (CRN) or national ID (NAT), as listed under BR-KSA-14 and BR-KSA-81.

Fix: validate the Federal Tax ID format on the business partner master, and mark export customers clearly so the integration knows not to send it.

3. Totals and rounding

ZATCA recalculates your invoice. If its numbers do not match yours, the document fails. The rules that catch most SAP B1 cases:

• BR-KSA-50: line VAT amount must equal line net amount × (VAT rate / 100).
• BR-KSA-51: line amount with VAT must equal line net amount + line VAT amount.
• BR-CO-10: the sum of line net amounts must equal the invoice total of line net amounts.
• BR-CO-17: VAT per category must equal taxable amount × rate, rounded to two decimals.

The XML standard requires half-up rounding, and the document VAT total is calculated at document level, not by adding rounded line VAT figures. SAP B1 can produce small differences here, especially with document-level discounts, prices with many decimals, or rounding settings on the document. A difference of 0.01 SAR is enough to reject.

Fix: make the integration build the XML amounts using ZATCA’s formulas, and test invoices with discounts, fractional quantities and mixed VAT rates in the simulation environment. Our Saudi VAT calculator helps when you check a single line by hand.

4. Credit and debit notes

Credit memos in SAP B1 are often created without a base document, for example a manual price adjustment. ZATCA does not accept that.

• BR-KSA-56: credit notes (code 381) and debit notes (code 383) must carry the billing reference of the original invoice.
• BR-KSA-17: notes must state the reason for issuance.

Fix: require a base A/R invoice (or at least a reference field) and a reason on every credit memo that goes to ZATCA.

5. Hash chain, ICV and PIH

Every invoicing unit keeps one chain. Each document carries an Invoice Counter Value (ICV) that goes up by one and a Previous Invoice Hash (PIH) that points to the document before it. BR-KSA-61 makes the PIH mandatory.

ZATCA’s guidelines are strict here:

• The counter must not be reset, and there should be no gaps in the counter or the hash sequence.
• An ICV must not be reused.
• Rejected documents still count. Their hash and counter are not changed, and the next document’s PIH points to the document immediately before it, even if that one was rejected.

Chain errors in SAP B1 usually come from two users or two services sending at the same moment, a database restored from backup, or a test company copied into production with its counter.

Fix: issue the counter and hash from one place per invoicing unit, lock it during submission, and never reset it after a restore without checking the last value ZATCA received.

6. Signature, hash and QR

For simplified invoices your system signs the XML. If the hash in the signature does not match the XML that ZATCA receives, the invoice fails. ZATCA’s security standard defines the hash as SHA-256 over a canonicalised XML that excludes the UBL extensions, the signature block and the QR element. Any change after signing, even reformatting whitespace or reordering elements, breaks it.

The QR code for B2C must hold all 9 tags in Base64 TLV, up to 700 characters. Decode a sample with our ZATCA QR code decoder to check the fields, and see our QR code guide for what each tag holds.

Fix: sign the final XML, store exactly what was sent, and never rebuild the XML for printing.

7. CSID problems

Your production CSID is a certificate with an expiry date. ZATCA’s security standard allows a validity of up to 60 months, and the portal sends a reminder before it ends. Renewal revokes the old certificate and issues a new one. The certificate must also be checked before stamping, so an expired or revoked CSID stops submissions for that invoicing unit.

A compliance CSID works only on the compliance APIs. Clearance and reporting need the production CSID.

Fix: record the expiry date of every CSID and plan renewal well before it.

How to handle a rejected invoice in SAP Business One

1. Read the code. Note the rule ID and message from the response, not just “rejected”.
2. Find the cause. Master data (address, VAT number), document data (reference, reason) or calculation (rounding).
3. Fix the source. Correct the business partner or the setup, not just the XML.
4. Do not edit the rejected document. It stays in the chain with its counter and hash.
5. Submit a new document. It gets a new ICV, UUID, hash and timestamp. For B2B, it must be cleared before it goes to the customer.
6. Watch the queue. Check rejected and pending documents every day, not at VAT return time.

Our ZATCA e-invoicing page covers the full setup, and the Wave 25 checklist helps if you are going live in 2027. If your SAP Business One invoices keep getting rejected, send us the error codes and we will tell you where the fix belongs. See also our e-invoicing integration service.

Sources

• ZATCA: E-Invoicing Detailed Technical Guideline, Version 2 (Nov 2022)
• ZATCA: Detailed Guidelines for E-Invoicing, Version 2 (May 2023)
• ZATCA: Electronic Invoice XML Implementation Standard, Version 1.2 (19 May 2023)
• ZATCA: Electronic Invoice Security Features Implementation Standards (19 May 2023)
• Qoyod Knowledge Base: ZATCA error codes and customer responses
• GOBL documentation: Saudi Arabia ZATCA addon (rule references)
• ZATCA Developer Community: NOT_CLEARED response with BR-KSA-39

Related services

• E-invoicing integration
• SAP Business One development